@capagents/forgeqe 0.0.0-stage → 1.0.0

package/src/tui/App.tsx

@@ -0,0 +1,983 @@
+import type { ScrollBoxRenderable, Selection } from "@opentui/core"
+import { useKeyboard, usePaste, useRenderer, useTerminalDimensions } from "@opentui/react"
+import path from "node:path"
+import { useEffect, useRef, useState } from "react"
+
+import { NO_MODEL_SET_UP } from "../llm.ts"
+import type { CodeEvent, ReplayMode } from "../types.ts"
+import { brainUnavailable, carryOver, openBrain, sessionSetup, type Brain, type BrainOptions } from "../brain/index.ts"
+import { INSTALL_HINT } from "../code/runtime.ts"
+import { briefText, detailFrom, shows, showsAgentTool, stepIntent, type Detail } from "../detail.ts"
+import { stepVerdictLines } from "../cases/types.ts"
+import { FAILURE_ACTION, FAILURE_LABEL } from "../cases/failure.ts"
+import { authStatus, openInBrowser, signIn, signOut, type AuthIO } from "../auth/signin.ts"
+import { HELP, parseCommand } from "../commands.ts"
+import { loadConfig, selectProfile, type AppConfig } from "../config.ts"
+import { TOOLS, type AskQuestion, type ToolEvent } from "../mcp/tools.ts"
+import type { executeRun } from "../run.ts"
+import { bundleLogs } from "../sessionLog.ts"
+import { findSkill, loadSkills } from "../skills/registry.ts"
+import { skillDetail, skillsOverview } from "../skills/view.ts"
+import { counts } from "../suite/report.ts"
+import { buildSummary, shortPath } from "../summary.ts"
+import { meterSnapshot, requestLine } from "../usage.ts"
+import { cleanSelection, copyText } from "./clipboard.ts"
+import { ChoicePanel, Footer, Hints, Logo, Prompt, Spinner, type Hint } from "./components.tsx"
+import { EXAMPLES, TIPS, formatDuration, formatTokens, packageVersion, pick, shortCwd, theme } from "./theme.ts"
+import { emptyProduced, Line, Produced, producedCard, TestsSetting, TranscriptLine } from "./transcript.tsx"
+import { Dialog, dialogSpec } from "./dialogs.ts"
+import { activityFromLog, clip, hostOf, modelLabel } from "./text.ts"
+import { featuresText } from "../capabilities/render.ts"
+
+export type TuiOptions = {
+  configPath?: string
+  profile?: string
+  /** Start URL pinned for browser runs. */
+  url?: string
+  /** First message, sent as if typed. */
+  goal?: string
+  headed?: boolean
+  replay?: ReplayMode
+  memory?: boolean
+  /** Repo the agent works in and writes tests for; null: no tests unless asked; undefined: code.repo. */
+  repo?: string | null
+  /** Replaces executeRun; tests use it to hold a run open. */
+  runner?: typeof executeRun
+  /** Replaces openBrain in tests. */
+  brain?: (o: BrainOptions) => Promise<Brain>
+  /** Replaces the clipboard write in tests. */
+  copy?: (text: string) => boolean
+  /** Show everything the agents do (their reasoning, every file read, engine logs); /details toggles it. */
+  verbose?: boolean
+  /** Replaces opening a page in the browser (sign-in) in tests. */
+  openUrl?: (url: string) => void
+}
+
+const VERSION = packageVersion()
+
+export function App({ options }: { options: TuiOptions }) {
+  const renderer = useRenderer()
+  const { width, height } = useTerminalDimensions()
+  const scrollRef = useRef<ScrollBoxRenderable>(null)
+  const submitRef = useRef<(value: string) => void>(() => {})
+  const configRef = useRef<AppConfig | null>(null)
+  const abortRef = useRef<AbortController | null>(null)
+  const brainRef = useRef<Brain | null>(null)
+  /** The conversation so far, carried into a new agent session when the profile changes. */
+  const convoRef = useRef<{ user: string; reply: string }[]>([])
+  const idRef = useRef(1)
+  const booted = useRef(false)
+  const closeAfterRun = useRef(false)
+  const markRef = useRef(0)
+  const stepRef = useRef(0)
+  const replayingRef = useRef(false)
+  const usedRef = useRef(new Map<string, number>())
+  const directNoted = useRef(false)
+  const thinkingRef = useRef(false)
+  const runIndex = useRef(0)
+  const producedRef = useRef<Produced>(emptyProduced())
+  const testsRef = useRef<TestsSetting>({ on: false, why: "" })
+  const codingRef = useRef(false)
+  const codeRunDir = useRef("")
+
+  const [lines, setLines] = useState<Line[]>([])
+  const [headed, setHeaded] = useState(Boolean(options.headed))
+  const [maxSteps, setMaxSteps] = useState(40)
+  const [profile, setProfile] = useState(options.profile || "")
+  const [model, setModel] = useState("")
+  const [status, setStatus] = useState("idle")
+  const [step, setStep] = useState(0)
+  const [tokens, setTokens] = useState(0)
+  const [tick, setTick] = useState(0)
+  const [inputKey, setInputKey] = useState(0)
+  const [activity, setActivity] = useState("")
+  const [lastStats, setLastStats] = useState("")
+  const [dialog, setDialog] = useState<Dialog | null>(null)
+  const [choice, setChoice] = useState(0)
+  const [thinking, setThinking] = useState(false)
+  const [browsing, setBrowsing] = useState(false)
+  const [coding, setCoding] = useState(false)
+  const [suiteProgress, setSuiteProgress] = useState<{ done: number; total: number } | null>(null)
+  const [copied, setCopied] = useState("")
+  const [example] = useState(() => pick(EXAMPLES))
+  const [tip] = useState(() => pick(TIPS))
+  const started = useRef<number | null>(null)
+
+  const detailRef = useRef<Detail>(detailFrom(options.verbose))
+  const headedRef = useRef(headed)
+  const stepsRef = useRef(maxSteps)
+  const dialogRef = useRef(dialog)
+  const choiceRef = useRef(choice)
+  const waitRef = useRef<{ text: string; resolve: (ok: boolean) => void } | null>(null)
+  const askRef = useRef<{ q: AskQuestion; resolve: (id: string | null) => void } | null>(null)
+  /** A line the sign-in is waiting for (a URL, an email, a token); the next Enter answers it instead of the agent. */
+  const priceNotesRef = useRef<string[]>([])
+  const entryRef = useRef<{ label: string; secret: boolean; initial?: string; resolve: (v: string | null) => void } | null>(null)
+  const [entry, setEntry] = useState<{ label: string; secret: boolean; initial?: string } | null>(null)
+  /** What has been typed or pasted into a secret entry; only its length is ever rendered. */
+  const secretRef = useRef("")
+  const [secretLength, setSecretLength] = useState(0)
+  headedRef.current = headed
+  stepsRef.current = maxSteps
+  dialogRef.current = dialog
+  choiceRef.current = choice
+  thinkingRef.current = thinking
+
+  const push = (kind: Line["kind"], text: string) => {
+    const parts = kind === "user" || kind === "reply" ? [text] : text.split("\n")
+    setLines((prev) => {
+      const next = [...prev]
+      for (const part of parts) next.push({ id: idRef.current++, kind, text: part })
+      return next.slice(-300)
+    })
+  }
+  const pushLine = (line: Omit<Line, "id">) => setLines((prev) => [...prev, { ...line, id: idRef.current++ }].slice(-300))
+  /** An agent's tool call; files it writes or edits (the test script) stand out from reads and searches. */
+  const pushTool = (text: string, ok: boolean) => push(!ok ? "err" : /^(Writing|Editing) /.test(text) ? "file" : "tool", text)
+  const pushProduced = () => {
+    const card = producedCard(producedRef.current, testsRef.current)
+    if (card) pushLine({ kind: "card", text: card.title, card })
+  }
+
+  const useTokens = (key: string, n: number) => {
+    usedRef.current.set(key, n)
+    setTokens([...usedRef.current.values()].reduce((a, b) => a + b, 0))
+  }
+
+  useEffect(() => {
+    if (status !== "running") return
+    const timer = setInterval(() => setTick((n) => n + 1), 1000)
+    return () => clearInterval(timer)
+  }, [status])
+
+  // The terminal hands mouse drags to the TUI, so text selected with the mouse is copied here when the drag ends.
+  useEffect(() => {
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const onSelection = (selection: Selection | null) => {
+      const text = cleanSelection(selection?.getSelectedText() || "")
+      if (!text.trim()) return
+      const ok = (options.copy || ((t: string) => copyText(t, (x) => renderer.copyToClipboardOSC52(x))))(text)
+      setCopied(ok ? `copied ${text.length} ${text.length === 1 ? "character" : "characters"}` : "could not reach the clipboard")
+      clearTimeout(timer)
+      timer = setTimeout(() => setCopied(""), 2500)
+    }
+    renderer.on("selection", onSelection)
+    return () => {
+      clearTimeout(timer)
+      renderer.off("selection", onSelection)
+    }
+  }, [renderer])
+
+  const closeBrain = () => {
+    const brain = brainRef.current
+    brainRef.current = null
+    void brain?.close().catch(() => {})
+  }
+
+  const quit = () => {
+    abortRef.current?.abort()
+    closeBrain()
+    renderer.destroy()
+  }
+
+  const outDirLabel = () => path.relative(process.cwd(), configRef.current?.export.outDir || "out") || "."
+
+  const settleWait = (ok: boolean) => {
+    const w = waitRef.current
+    waitRef.current = null
+    w?.resolve(ok)
+  }
+
+  const settleAsk = (id: string | null) => {
+    const a = askRef.current
+    askRef.current = null
+    a?.resolve(id)
+  }
+
+  const openDialog = (next: Dialog) => {
+    if (next !== "wait") settleWait(false)
+    if (next !== "ask") settleAsk(null)
+    setChoice(0)
+    setDialog(next)
+  }
+
+  const closeDialog = () => {
+    if (dialogRef.current === "wait") settleWait(false)
+    if (dialogRef.current === "ask") settleAsk(null)
+    setDialog(null)
+  }
+
+  /** A tool needs the user to do something by hand (sign in in the browser); resolves when they continue or cancel. */
+  const waitForUser = (prompt: string) =>
+    new Promise<boolean>((resolve) => {
+      settleWait(false)
+      waitRef.current = { text: prompt, resolve }
+      push("sys", prompt)
+      openDialog("wait")
+    })
+
+  /** A tool asks the user to pick an option (a sprint, whether to run tests); resolves with its id, or null on cancel. */
+  const ask = (q: AskQuestion) =>
+    new Promise<string | null>((resolve) => {
+      settleAsk(null)
+      push("sys", [q.title, ...(q.lines || [])].join("\n"))
+      openDialog("ask")
+      askRef.current = { q, resolve }
+    })
+
+  const settleEntry = (value: string | null) => {
+    const e = entryRef.current
+    entryRef.current = null
+    secretRef.current = ""
+    setSecretLength(0)
+    setEntry(null)
+    e?.resolve(value)
+  }
+
+  const setSecret = (value: string) => {
+    secretRef.current = value
+    setSecretLength(value.length)
+  }
+
+  /** The sign-in asks for a line of text in the prompt box; a secret is typed unseen and never sent to the agent. */
+  const input: AuthIO["input"] = (q) =>
+    new Promise((resolve) => {
+      settleEntry(null)
+      const e = { label: q.label, secret: Boolean(q.secret), initial: q.initial }
+      entryRef.current = { ...e, resolve }
+      setEntry(e)
+      setInputKey((k) => k + 1)
+    })
+
+  const runAuth = async (action: "status" | "login" | "logout", system?: string) => {
+    const cfg = configRef.current || undefined
+    if (action === "status") {
+      push("sys", authStatus(cfg).join("\n"))
+      return
+    }
+    if (action === "logout") {
+      push("sys", await signOut(system!))
+      reloadAfterAuth()
+      return
+    }
+    const controller = begin("Signing in…")
+    controller.signal.addEventListener("abort", () => settleEntry(null), { once: true })
+    let finalStatus = "fail"
+    try {
+      const res = await signIn(
+        {
+          say: (text, kind) => push(kind === "ok" ? "ok" : kind === "err" ? "err" : "sys", text),
+          input,
+          choose: ask,
+          openUrl: (url) => {
+            push("sys", `Opening ${url}`)
+            ;(options.openUrl || openInBrowser)(url)
+          },
+          signal: controller.signal,
+        },
+        system,
+        cfg,
+      )
+      finalStatus = res.ok ? "done" : controller.signal.aborted ? "stopped" : res.message === "Cancelled." ? "idle" : "fail"
+      if (res.ok) reloadAfterAuth()
+    } finally {
+      settleEntry(null)
+      finish(finalStatus)
+    }
+  }
+
+  /** New credentials: read the config again (a system may be set up now) and restart the agent so its MCP servers use them. */
+  const reloadAfterAuth = () => {
+    try {
+      const cfg = loadConfig({ configPath: options.configPath })
+      configRef.current = configRef.current ? selectProfile(cfg, configRef.current.activeProfile) : cfg
+    } catch (err) {
+      push("err", (err as Error).message)
+    }
+    if (brainRef.current) {
+      closeBrain()
+      push("sys", "The agent reconnects with the new sign-in on your next message and keeps the conversation.")
+    }
+  }
+
+  const requestStop = () => {
+    const controller = abortRef.current
+    if (!controller || controller.signal.aborted) return
+    controller.abort()
+    push("sys", "Stopping…")
+    setActivity("Stopping: closing the browser and saving files…")
+  }
+
+  const choose = (id: string) => {
+    setDialog(null)
+    if (id === "wait-done" || id === "wait-cancel") settleWait(id === "wait-done")
+    if (id.startsWith("ask:")) settleAsk(id.slice(4))
+    if (id === "stop") requestStop()
+    if (id === "close") quit()
+    if (id === "stop-close") {
+      if (!abortRef.current) {
+        quit()
+        return
+      }
+      closeAfterRun.current = true
+      requestStop()
+      push("sys", "ForgeQE closes once the browser has shut down.")
+    }
+  }
+
+  const applyProfile = (name: string) => {
+    if (!configRef.current) throw new Error("Config is not loaded.")
+    configRef.current = selectProfile(configRef.current, name)
+    setProfile(name)
+    setModel(modelLabel(configRef.current))
+    if (brainRef.current) {
+      closeBrain()
+      push("sys", "The agent switches to the new profile on your next message and keeps the conversation.")
+    }
+  }
+
+  const cycleProfile = () => {
+    const cfg = configRef.current
+    if (!cfg || abortRef.current) return
+    const names = Object.keys(cfg.profiles)
+    if (names.length < 2) return
+    const next = names[(names.indexOf(cfg.activeProfile) + 1) % names.length]
+    applyProfile(next)
+  }
+
+  useKeyboard((key) => {
+    const open = dialogRef.current
+    if (key.name === "c" && key.ctrl) {
+      if (open === "quit") quit()
+      else openDialog("quit")
+      return
+    }
+    if (open) {
+      const opts = dialogSpec(open, Boolean(abortRef.current), outDirLabel(), thinkingRef.current, waitRef.current?.text, askRef.current?.q).options
+      const n = opts.length
+      if (key.name === "left" || key.name === "up" || (key.name === "tab" && key.shift)) setChoice((c) => (c - 1 + n) % n)
+      else if (key.name === "right" || key.name === "down" || key.name === "tab") setChoice((c) => (c + 1) % n)
+      else if (key.name === "return" || key.name === "enter") choose(opts[Math.min(choiceRef.current, n - 1)].id)
+      else if (key.name === "escape") closeDialog()
+      return
+    }
+    if (key.name === "escape" && entryRef.current) {
+      push("sys", "Cancelled.")
+      settleEntry(null)
+      return
+    }
+    if (entryRef.current?.secret) {
+      if (key.name === "return" || key.name === "enter" || key.name === "kpenter") submitRef.current(secretRef.current)
+      else if (key.name === "backspace") setSecret(secretRef.current.slice(0, -1))
+      else if (key.name === "u" && key.ctrl) setSecret("")
+      else if (!key.ctrl && !key.meta && key.sequence && key.sequence.length === 1 && key.sequence >= " ") setSecret(secretRef.current + key.sequence)
+      return
+    }
+    if (key.name === "tab" && !key.shift) cycleProfile()
+    if (key.name === "p" && key.ctrl) push("sys", HELP)
+    if (key.name === "escape" && abortRef.current) openDialog("stop")
+  })
+
+  usePaste((event) => {
+    if (!entryRef.current?.secret) return
+    event.preventDefault()
+    setSecret(secretRef.current + new TextDecoder().decode(event.bytes).replace(/[\r\n]+/g, "").trim())
+  })
+
+  /** Browser runs and suites report here, whether the agent started them or the text went straight to the browser. */
+  const onToolEvent = (e: ToolEvent, agent: boolean) => {
+    const aborted = () => Boolean(abortRef.current?.signal.aborted)
+    const cfg = configRef.current
+    switch (e.type) {
+      case "run-start":
+        runIndex.current++
+        stepRef.current = 0
+        markRef.current = Date.now()
+        replayingRef.current = false
+        setStep(0)
+        setBrowsing(true)
+        if (agent) push("code", `Browser: ${clip(e.goal, 110)}`)
+        if (!aborted()) setActivity(cfg?.llm.provider === "mock" ? "Running the offline demo…" : "Starting the browser…")
+        return
+      case "run-event": {
+        const event = e.event
+        if (event.type === "step") {
+          stepRef.current = event.step
+          setStep(event.step)
+          replayingRef.current = event.source === "memory"
+          if (!replayingRef.current && detailRef.current === "full") push("timing", `Thought: ${formatDuration(Date.now() - markRef.current, true)}`)
+          else if (!aborted()) setActivity(`Replaying step ${event.step} from memory…`)
+        }
+        if (event.type === "memory") {
+          if (shows(event, detailRef.current)) push("memory", event.text)
+          markRef.current = Date.now()
+        }
+        if (event.type === "usage") useTokens(`run-${runIndex.current}`, event.usage.input + event.usage.output)
+        if (event.type === "log") {
+          if (shows(event, detailRef.current)) push(event.level === "error" ? "err" : "sys", event.text)
+          if (!aborted()) setActivity(activityFromLog(event.text))
+        }
+        if (event.type === "thought" && !replayingRef.current) {
+          if (shows(event, detailRef.current)) push("thought", stepIntent(event.step, event.text, detailRef.current))
+          if (!aborted()) setActivity(`Acting in the browser (step ${stepRef.current})…`)
+        }
+        if (event.type === "outcome") {
+          markRef.current = Date.now()
+          if (!aborted()) setActivity(replayingRef.current ? "Replaying from memory…" : `Thinking about step ${stepRef.current + 1}…`)
+        }
+        if (event.type === "outcome") push(event.ok ? "ok" : "err", briefText(event.text, detailRef.current))
+        return
+      }
+      case "run-done": {
+        const r = e.result
+        const summary = buildSummary({
+          status: r?.status || "fail",
+          text: r?.summary || e.error || "",
+          finalUrl: r?.finalUrl || "",
+          files: e.files,
+          memory: r?.memory,
+          usage: r?.usage,
+          cost: r?.cost,
+          outcome: r?.outcome,
+          failedChecks: r?.failedChecks,
+          quality: r?.quality,
+          budgetExceeded: r?.budgetExceeded,
+          ms: e.ms,
+          tokens: r ? r.usage.input + r.usage.output : 0,
+          steps: stepRef.current,
+        })
+        pushLine({ kind: "summary", text: summary.text, summary })
+        producedRef.current.runs.push({ runDir: e.runDir, status: r?.status || "fail", files: e.files })
+        setLastStats(summary.stats)
+        setBrowsing(false)
+        if (agent && !aborted()) setActivity("The agent is reading the result…")
+        return
+      }
+      case "suite-start":
+        push("sys", `${e.cases.length} test case${e.cases.length === 1 ? "" : "s"}${e.parallel > 1 ? `, ${e.parallel} at a time` : ""}`)
+        setSuiteProgress({ done: 0, total: e.cases.length })
+        return
+      case "suite-event": {
+        const s = e.event
+        const tag = (id: string) => ((configRef.current?.suite.parallel || 1) > 1 ? `[${id}] ` : "")
+        if (s.type === "case-start") {
+          push("code", `${s.index + 1}/${s.total}  ${s.case.id}  ${s.case.title}`)
+          // What was read from the test management system: where the case lives and the steps the browser will follow.
+          const steps = s.case.steps
+          const shown = detailRef.current === "full" ? steps : steps.slice(0, 15)
+          const caseLines = [
+            ...(s.case.url ? [`Source  ${s.case.url}`] : []),
+            ...shown.map((st, i) => `${String(i + 1).padStart(2)}. ${clip(st.action.replace(/\s+/g, " "), 110)}${st.expected ? `  → ${clip(st.expected.replace(/\s+/g, " "), 80)}` : ""}`),
+            ...(steps.length > shown.length ? [`    and ${steps.length - shown.length} more steps`] : []),
+            ...(!steps.length && s.case.description ? [clip(s.case.description.replace(/\s+/g, " "), 200)] : []),
+          ]
+          if (caseLines.length) push("sys", caseLines.map((l) => `     ${tag(s.case.id)}${l}`).join("\n"))
+          if (!aborted()) setActivity(`Running ${s.case.id}…`)
+        } else if (s.type === "case-done") {
+          setSuiteProgress((p) => (p ? { ...p, done: p.done + 1 } : p))
+          const r = s.result
+          push(r.status === "passed" ? "ok" : "err", `${r.case.id} ${r.status} in ${formatDuration(r.ms)}${r.failure ? ` · ${FAILURE_LABEL[r.failure.type]}` : ""}`)
+          if (r.failure) push("sys", `  ${tag(r.case.id)}${clip(r.failure.reason, 200)} Next: ${FAILURE_ACTION[r.failure.type]}.`)
+          // Each step of the case with its verdict, and what the page showed for a step that did not pass.
+          for (const line of stepVerdictLines(r)) push(line.startsWith("✓") ? "ok" : line.startsWith("✗") ? "err" : "sys", `  ${tag(r.case.id)}${clip(line, 200)}`)
+        } else if (s.type === "writeback" && !aborted()) setActivity("Posting results…")
+        else if (s.type === "case-event") {
+          const ev = s.event
+          const p = tag(s.case.id)
+          if (ev.type === "usage") useTokens(`case-${s.index}`, ev.usage.input + ev.usage.output)
+          else if (!shows(ev, detailRef.current)) {
+            if (ev.type === "log" && !aborted()) setActivity(`${p}${activityFromLog(ev.text)}`)
+          } else if (ev.type === "log") push(ev.level === "error" ? "err" : "sys", p + ev.text)
+          else if (ev.type === "memory") push("memory", p + ev.text)
+          else if (ev.type === "thought") push("thought", p + stepIntent(ev.step, ev.text, detailRef.current))
+          else if (ev.type === "outcome") push(ev.ok ? "ok" : "err", p + briefText(ev.text, detailRef.current))
+        }
+        return
+      }
+      case "suite-done": {
+        pushLine({ kind: "suitesummary", text: e.suite.name, suite: e.suite })
+        producedRef.current.suites.push({ html: e.suite.files.html, junit: e.suite.files.junit })
+        const c = counts(e.suite.results)
+        setLastStats(`${c.passed}/${c.total} passed · ${formatDuration(e.suite.ms)}`)
+        setSuiteProgress(null)
+        if (agent && !aborted()) setActivity("The agent is reading the results…")
+        return
+      }
+      case "info":
+        push(e.ok === undefined ? "code" : e.ok ? "ok" : "err", e.text)
+        return
+      case "agent": {
+        const ev = e.event
+        if (ev.kind === "usage") useTokens(`agent-tool-${runIndex.current}`, ev.usage.input + ev.usage.output)
+        // Hidden lines (reads, searches, the agent's narration) still show on the activity line below.
+        else if (shows(ev, detailRef.current)) {
+          if (ev.kind === "info") push("code", ev.text)
+          else if (ev.kind === "say") push("thought", ev.text)
+          else if (ev.kind === "tool") pushTool(ev.text, ev.ok)
+          else if (ev.kind === "test") push(ev.ok ? "ok" : "err", ev.text)
+        }
+        if (aborted()) return
+        const who = codingRef.current ? "Coding agent" : "Agent"
+        if (ev.kind === "tool") setActivity(`${who}: ${clip(ev.text, 60)}`)
+        else if (ev.kind === "info" && ev.text.startsWith("ForgeQE runs the test")) setActivity("ForgeQE is running the new test…")
+        else if (ev.kind === "say") setActivity(`${who} is working…`)
+        return
+      }
+      case "code-start": {
+        codingRef.current = true
+        codeRunDir.current = e.runDir
+        setCoding(true)
+        const show = shortPath
+        pushLine({
+          kind: "card",
+          text: "Handing over to the coding agent",
+          card: {
+            status: "info",
+            title: "Handing over to the coding agent",
+            stats: "browser agent → coding agent",
+            body: [
+              ...(e.goal ? [`Flow      ${clip(e.goal, 100)}`] : []),
+              `Run       ${show(e.runDir)}/`,
+              `Repo      ${show(e.repo)}`,
+              "It reads the run's steps, locators and page memory, studies the repo's tests, and writes a test.",
+              "ForgeQE then runs that test itself until it passes.",
+            ],
+          },
+        })
+        if (!aborted()) setActivity("Coding agent: reading the handoff…")
+        return
+      }
+      case "code-done":
+        codingRef.current = false
+        setCoding(false)
+        producedRef.current.tests.push({ runDir: codeRunDir.current, result: e.result, error: e.error })
+        if (e.error) push("err", `Coding agent: ${e.error}`)
+        if (agent && !aborted()) setActivity("The agent is reading the result…")
+        return
+      case "card":
+        pushLine({ kind: "card", text: e.card.title, card: e.card })
+        return
+    }
+  }
+
+  const onBrainEvent = (e: CodeEvent) => {
+    if (e.kind === "usage") {
+      useTokens("agent", e.usage.input + e.usage.output)
+      return
+    }
+    // ForgeQE's own agent: its tool calls (Azure DevOps and other MCP servers, commands) and what it says between them,
+    // one line each in brief; only its file reads and searches are left to /details.
+    if (e.kind === "tool" && showsAgentTool(e.text, e.ok, detailRef.current)) pushTool(e.text, e.ok)
+    else if (e.kind === "say") push("thought", briefText(e.text, detailRef.current, 200))
+    else if (shows(e, detailRef.current)) {
+      if (e.kind === "info") push("code", e.text)
+      if (e.kind === "tool") pushTool(e.text, e.ok)
+      if (e.kind === "test") push(e.ok ? "ok" : "err", e.text)
+    }
+    if (abortRef.current?.signal.aborted) return
+    if (e.kind === "tool") setActivity(`Agent: ${clip(e.text, 60)}`)
+    else if (e.kind === "say") setActivity("The agent is working…")
+  }
+
+  const toolContext = (agent: boolean, signal?: AbortSignal) => ({
+    headed: headedRef.current,
+    maxSteps: stepsRef.current,
+    replay: options.replay,
+    memory: options.memory,
+    url: options.url,
+    signal,
+    execute: options.runner,
+    emit: (e: ToolEvent) => onToolEvent(e, agent),
+    session: "shell" as const,
+    writeTests: testsRef.current.on,
+    waitForUser,
+    ask,
+  })
+
+  const begin = (activityText: string) => {
+    const controller = new AbortController()
+    abortRef.current = controller
+    started.current = Date.now()
+    usedRef.current = new Map()
+    producedRef.current = emptyProduced()
+    setTokens(0)
+    setStatus("running")
+    setActivity(activityText)
+    return controller
+  }
+
+  const finish = (finalStatus: string) => {
+    setStatus(finalStatus)
+    setActivity("")
+    setThinking(false)
+    setBrowsing(false)
+    codingRef.current = false
+    setCoding(false)
+    setSuiteProgress(null)
+    abortRef.current = null
+    started.current = null
+    setChoice(0)
+    setDialog((d) => (d === "stop" ? null : d))
+    if (closeAfterRun.current) quit()
+  }
+
+  /** No agent available: the text is the browser goal. */
+  const runDirect = async (goal: string, cfg: AppConfig, why: string) => {
+    if (!directNoted.current) {
+      directNoted.current = true
+      push("sys", `ForgeQE's agent is off (${why}), so the text runs as a browser goal.${why.includes("agent runtime") ? ` ${INSTALL_HINT}` : " Press Tab for a live profile."} /features lists what ForgeQE can do.`)
+    }
+    const controller = begin(cfg.llm.provider === "mock" ? "Running the offline demo…" : "Starting…")
+    testsRef.current = { on: false, why: why.includes("agent runtime") ? "the agent runtime Scribe needs is not installed" : "ForgeQE's agent is off in the offline profile" }
+    let finalStatus = "fail"
+    try {
+      const out = (await TOOLS[0].run({ goal }, { ...toolContext(false, controller.signal), config: cfg, cwd: process.cwd() })) as { status: string }
+      finalStatus = out.status === "passed" ? "done" : out.status === "stopped" ? "stopped" : "fail"
+    } catch {
+      finalStatus = controller.signal.aborted ? "stopped" : "fail"
+    } finally {
+      pushProduced()
+      finish(finalStatus)
+    }
+  }
+
+  const askAgent = async (text: string, cfg: AppConfig) => {
+    const controller = begin("Thinking…")
+    const meterStart = meterSnapshot()
+    setThinking(true)
+    const setup = sessionSetup(cfg, options.repo)
+    testsRef.current = { on: setup.writeTests, why: "the session was started with --no-code" }
+    let finalStatus = "fail"
+    let fresh = false
+    try {
+      if (!brainRef.current) {
+        fresh = true
+        setActivity("Starting ForgeQE's agent…")
+        const { cwd, notes } = setup
+        brainRef.current = await (options.brain || openBrain)({
+          config: cfg,
+          cwd,
+          notes,
+          context: () => toolContext(true, abortRef.current?.signal),
+          onEvent: onBrainEvent,
+        })
+        setModel(`${modelLabel(cfg)} · agent ${brainRef.current.model}`)
+      }
+      const brain = brainRef.current
+      const onAbort = () => void brain.abort()
+      controller.signal.addEventListener("abort", onAbort, { once: true })
+      if (!controller.signal.aborted) setActivity("Thinking…")
+      const answer = await brain.ask(fresh ? carryOver(convoRef.current, text) : text)
+      controller.signal.removeEventListener("abort", onAbort)
+      if (answer.outcome !== "stopped") convoRef.current.push({ user: text, reply: answer.reply })
+      if (answer.outcome === "stopped") {
+        push("sys", "Stopped.")
+        finalStatus = "stopped"
+      } else {
+        if (answer.reply) pushLine({ kind: "reply", text: answer.reply, outcome: answer.outcome })
+        if (answer.error && !answer.reply) push("err", answer.error)
+        finalStatus = answer.outcome === "done" ? "done" : answer.outcome === "needs_input" ? "idle" : "fail"
+      }
+    } catch (err) {
+      push("err", (err as Error).message)
+      closeBrain()
+    } finally {
+      pushProduced()
+      // What this request used and cost in total: ForgeQE's agent, browser runs, Scribe, and the reviewer.
+      const spent = requestLine(meterStart)
+      if (spent) push("sys", spent)
+      finish(finalStatus)
+    }
+  }
+
+  const handleText = (text: string) => {
+    const cfg = configRef.current
+    if (!cfg) {
+      push("err", "Config failed to load.")
+      return
+    }
+    if (abortRef.current) {
+      push("err", "ForgeQE is busy. Press esc to stop it.")
+      return
+    }
+    if (cfg.llm.provider === "none" && !options.brain) {
+      push("err", NO_MODEL_SET_UP)
+      return
+    }
+    const why = options.brain ? null : brainUnavailable(cfg)
+    if (why) void runDirect(text, cfg, why)
+    else void askAgent(text, cfg)
+  }
+
+  useEffect(() => {
+    if (booted.current) return
+    booted.current = true
+    try {
+      let cfg = loadConfig({ configPath: options.configPath, profile: options.profile })
+      if (options.profile) cfg = selectProfile(cfg, options.profile)
+      configRef.current = cfg
+      // A price in llms.json that differs from the model's list price (probably a typo or an old price), said with the
+      // first message so the home screen stays as it is.
+      const reviewer = cfg.code.reviewProfile ? cfg.profiles[cfg.code.reviewProfile] : undefined
+      priceNotesRef.current = [...new Set([cfg.llm.priceWarning, reviewer?.priceWarning].filter((w): w is string => Boolean(w)))]
+      setProfile(cfg.activeProfile)
+      setModel(modelLabel(cfg))
+      setMaxSteps(cfg.browser.maxSteps)
+      stepsRef.current = cfg.browser.maxSteps
+      if (options.goal) {
+        push("user", options.goal)
+        handleText(options.goal)
+      }
+    } catch (err) {
+      push("err", (err as Error).message)
+    }
+    return () => closeBrain()
+    // Boot once.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  const onSubmit = (value: string) => {
+    const text = value.replace(/\t/g, "").trim()
+    setInputKey((k) => k + 1)
+    const pending = entryRef.current
+    if (pending) {
+      const answer = text || pending.initial || ""
+      if (!answer) return
+      push("user", pending.secret ? "•".repeat(Math.min(12, answer.length)) : answer)
+      settleEntry(answer)
+      return
+    }
+    if (!text) return
+    push("user", text)
+    for (const w of priceNotesRef.current.splice(0)) push("sys", `Price check: ${w}`)
+    const cmd = parseCommand(text)
+    if (cmd.type === "help") {
+      push("sys", HELP)
+      return
+    }
+    if (cmd.type === "exit") {
+      if (abortRef.current) openDialog("quit")
+      else quit()
+      return
+    }
+    if (cmd.type === "clear") {
+      setLines([])
+      return
+    }
+    if (cmd.type === "stop") {
+      if (!abortRef.current) push("sys", "Nothing is running.")
+      else requestStop()
+      return
+    }
+    if (cmd.type === "headed") {
+      setHeaded(cmd.value)
+      headedRef.current = cmd.value
+      push("sys", `headed  ${cmd.value ? "on" : "off"}`)
+      return
+    }
+    if (cmd.type === "details") {
+      const full = cmd.value ?? detailRef.current === "brief"
+      detailRef.current = full ? "full" : "brief"
+      push("sys", full ? "details  on: the agents' reasoning, every file they read, and engine logs" : "details  off: progress, results, files written, and problems")
+      return
+    }
+    if (cmd.type === "profile") {
+      try {
+        applyProfile(cmd.name)
+        push("sys", `profile  ${cmd.name}`)
+      } catch (err) {
+        push("err", (err as Error).message)
+      }
+      return
+    }
+    if (cmd.type === "features") {
+      if (configRef.current) push("sys", featuresText(configRef.current))
+      else push("err", "Config is not loaded.")
+      return
+    }
+    if (cmd.type === "skills") {
+      try {
+        const cfg = configRef.current
+        if (!cfg) throw new Error("Config is not loaded.")
+        const reg = loadSkills(cfg.skills, process.cwd())
+        if (!cmd.name) push("sys", skillsOverview(reg, cfg.skills, process.cwd()))
+        else {
+          const skill = findSkill(reg, cmd.name)
+          if (!skill) throw new Error(`No skill named "${cmd.name}". /skills lists them.`)
+          push("sys", skillDetail(skill, reg.disabled.includes(skill)))
+        }
+      } catch (err) {
+        push("err", (err as Error).message)
+      }
+      return
+    }
+    if (cmd.type === "logs") {
+      try {
+        if (!configRef.current) throw new Error("Config is not loaded.")
+        const out = bundleLogs(configRef.current, { shots: cmd.shots })
+        push("sys", [`log      ${out.log}`, `runs     ${out.runs}`, `archive  ${out.archive}`, "Secrets are replaced in every file. Share the archive to get help with this session."].join("\n"))
+      } catch (err) {
+        push("err", (err as Error).message)
+      }
+      return
+    }
+    if (cmd.type === "auth") {
+      if (abortRef.current) {
+        push("err", "ForgeQE is busy. Press esc to stop it.")
+        return
+      }
+      void runAuth(cmd.action, cmd.system).catch((err) => push("err", (err as Error).message))
+      return
+    }
+    if (cmd.type === "unknown") {
+      push("err", "Usage: /headed on|off, /details on|off, /profile <name>, /auth [system], /auth logout <system>. /help lists the commands.")
+      return
+    }
+    handleText(cmd.text)
+  }
+  submitRef.current = onSubmit
+
+  void tick
+  const running = status === "running"
+  const elapsed = started.current != null ? formatDuration(Date.now() - started.current) : ""
+  const modeColor = running ? theme.warn : status === "fail" ? theme.err : theme.accent
+  const right = running
+    ? suiteProgress
+      ? `case ${Math.min(suiteProgress.done + 1, suiteProgress.total)}/${suiteProgress.total}`
+      : browsing
+        ? step > maxSteps
+          ? `step ${step} (past ${maxSteps}, still progressing)`
+          : `step ${step}/${maxSteps}`
+        : coding
+          ? "coding agent"
+          : "agent"
+    : status === "done" || status === "fail" || status === "stopped"
+      ? status
+      : options.url
+        ? hostOf(options.url)
+        : headed
+          ? "headed"
+          : ""
+  const rightColor = running ? theme.warn : status === "done" ? theme.ok : status === "fail" ? theme.err : theme.muted
+  const footerRight = VERSION ? `ForgeQE ${VERSION}` : "ForgeQE"
+  const home = lines.length === 0 && !running
+
+  const closeHint: Hint = { key: "ctrl+c", label: "close", onPress: () => openDialog("quit") }
+  const copiedHint: Hint[] = copied ? [{ key: `✓ ${copied}`, label: "" }] : []
+  const idleHints: Hint[] = [
+    ...copiedHint,
+    ...(lastStats ? [{ key: `last run ${lastStats}`, label: "" }] : []),
+    { key: "tab", label: "profiles" },
+    { key: "ctrl+p", label: "commands" },
+    closeHint,
+  ]
+  const runningHints: Hint[] = [
+    ...copiedHint,
+    { key: `${formatTokens(tokens)} tokens · ${elapsed}`, label: "" },
+    { key: "ctrl+p", label: "commands" },
+    closeHint,
+  ]
+  const runningLeft = (
+    <>
+      <Spinner kind="bar" />
+      <text onMouseDown={() => openDialog("stop")}>
+        <span fg={theme.text}>{"  esc"}</span>
+        <span fg={theme.muted}>{" stop"}</span>
+      </text>
+    </>
+  )
+
+  const renderControls = (promptWidth: number, placeholder: string, rows: [number, number]) => {
+    if (dialog) {
+      const spec = dialogSpec(dialog, running, outDirLabel(), thinking, waitRef.current?.text, askRef.current?.q)
+      const wide = spec.options.reduce((n, o) => n + o.label.length + 3, 0) > promptWidth - 36
+      return (
+        <ChoicePanel
+          vertical={spec.options.length > 3 || wide}
+          width={promptWidth}
+          title={spec.title}
+          detail={spec.detail}
+          color={spec.color}
+          options={spec.options}
+          selected={Math.min(choice, spec.options.length - 1)}
+          onChoose={choose}
+          onHover={setChoice}
+        />
+      )
+    }
+    return (
+      <>
+        <Prompt
+          width={promptWidth}
+          inputKey={inputKey}
+          onSubmit={(value) => submitRef.current(value)}
+          minRows={entry ? 1 : rows[0]}
+          maxRows={entry ? 3 : rows[1]}
+          placeholder={entry ? `${entry.label}${entry.secret ? " (hidden as you type)" : ""}${entry.initial ? ` · Enter keeps ${entry.initial}` : ""} · esc cancels` : placeholder}
+          masked={entry?.secret ? secretLength : undefined}
+          modeColor={modeColor}
+          profile={profile}
+          model={model}
+          right={right}
+          rightColor={rightColor}
+        />
+        <Hints width={promptWidth} items={running ? runningHints : idleHints} left={running ? runningLeft : undefined} />
+      </>
+    )
+  }
+
+  if (home) {
+    const promptWidth = Math.max(40, Math.min(width - 8, 120))
+    return (
+      <box style={{ flexDirection: "column", flexGrow: 1 }}>
+        <box style={{ flexDirection: "column", flexGrow: 1, alignItems: "center", justifyContent: "center" }}>
+          <Logo />
+          <box style={{ height: 2 }} />
+          {renderControls(promptWidth, `Describe a goal… "${example}"`, [4, Math.max(4, Math.min(12, height - 22))])}
+          <box style={{ height: 3 }} />
+          <text>
+            <span fg={theme.warn}>{"● "}</span>
+            <span fg={theme.text}>{"Tip "}</span>
+            <span fg={theme.muted}>{tip}</span>
+          </text>
+        </box>
+        <Footer left={shortCwd()} right={footerRight} width={width} />
+      </box>
+    )
+  }
+
+  const promptWidth = Math.max(40, width - 4)
+  return (
+    <box style={{ flexDirection: "column", flexGrow: 1 }}>
+      <scrollbox
+        ref={scrollRef}
+        stickyScroll
+        stickyStart="bottom"
+        style={{ flexGrow: 1, paddingLeft: 2, paddingRight: 2, paddingTop: 1 }}
+        focused={false}
+      >
+        {lines.map((line) => (
+          <TranscriptLine key={line.id} line={line} />
+        ))}
+        {running ? (
+          <box style={{ flexDirection: "row", marginTop: 1, paddingLeft: 2, flexShrink: 0 }}>
+            <Spinner kind="dots" />
+            <text fg={theme.text}>{` ${activity || "Working…"}`}</text>
+          </box>
+        ) : null}
+      </scrollbox>
+      <box style={{ flexDirection: "column", paddingLeft: 2, paddingRight: 2, flexShrink: 0 }}>
+        {renderControls(
+          promptWidth,
+          running
+            ? coding
+              ? "The coding agent is writing a test · esc to stop"
+              : `${thinking ? "ForgeQE's agent" : "The browser agent"} is working · esc to stop`
+            : "Ask ForgeQE: a goal, test cases, a test, a pipeline…",
+          [3, Math.max(3, Math.min(10, Math.floor(height / 3)))],
+        )}
+      </box>
+      <Footer left={shortCwd()} right={footerRight} width={width} />
+    </box>
+  )
+}