@capagents/forgeqe 0.0.0-stage → 1.0.0

package/src/code/notes.ts

@@ -0,0 +1,75 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+/**
+ * What Scribe learned about a repository in an earlier job, and the tests earlier jobs wrote there, so the next job
+ * starts from them instead of reading the repository again. Kept with page memory, one entry per repository.
+ */
+
+export const NOTES_FILE = "scribe-notes.json"
+/** Notes older than this are read again from the repository. */
+const MAX_AGE_DAYS = 30
+const MAX_TESTS = 15
+
+export type WrittenTest = { goal: string; test_file: string; command: string; changed: string[]; at: string }
+export type RepoNotes = { notes: string; at: string; tests: WrittenTest[] }
+
+type NotesFile = { repos: Record<string, RepoNotes> }
+
+function load(memoryDir: string): NotesFile {
+  try {
+    const data = JSON.parse(readFileSync(path.join(memoryDir, NOTES_FILE), "utf8")) as NotesFile
+    return data && typeof data.repos === "object" && data.repos ? data : { repos: {} }
+  } catch {
+    return { repos: {} }
+  }
+}
+
+function store(memoryDir: string, data: NotesFile): void {
+  try {
+    mkdirSync(memoryDir, { recursive: true })
+    writeFileSync(path.join(memoryDir, NOTES_FILE), `${JSON.stringify(data, null, 2)}\n`)
+  } catch {
+    // Notes save a later job some reading; without them it reads the repository.
+  }
+}
+
+/** The repository's notes, unless there are none or they are too old to trust. */
+export function readNotes(memoryDir: string, repo: string, now = Date.now()): RepoNotes | null {
+  const n = load(memoryDir).repos[repo]
+  if (!n?.notes?.trim()) return null
+  const age = (now - Date.parse(n.at)) / 86_400_000
+  return Number.isFinite(age) && age <= MAX_AGE_DAYS ? { ...n, tests: n.tests || [] } : null
+}
+
+export function saveNotes(memoryDir: string, repo: string, notes: string, now = new Date()): void {
+  const data = load(memoryDir)
+  const text = notes.trim()
+  if (!text) return
+  data.repos[repo] = { notes: text, at: now.toISOString(), tests: data.repos[repo]?.tests || [] }
+  store(memoryDir, data)
+}
+
+export function addWrittenTest(memoryDir: string, repo: string, test: Omit<WrittenTest, "at">, now = new Date()): void {
+  const data = load(memoryDir)
+  const n = data.repos[repo]
+  if (!n) return
+  const tests = (n.tests || []).filter((t) => t.test_file !== test.test_file || t.goal !== test.goal)
+  n.tests = [...tests, { ...test, at: now.toISOString() }].slice(-MAX_TESTS)
+  store(memoryDir, data)
+}
+
+/** The notes as the first message's section. */
+export function notesSection(n: RepoNotes): string {
+  const lines = [
+    `## What earlier jobs learned about this repository (${n.at.slice(0, 10)})`,
+    "",
+    n.notes,
+  ]
+  if (n.tests.length) {
+    lines.push("", "Tests earlier jobs wrote here (extend them or their page objects when this flow overlaps):")
+    for (const t of n.tests) lines.push(`- ${t.test_file} for "${t.goal.replace(/\s+/g, " ").slice(0, 120)}"; command: ${t.command}; files: ${t.changed.join(", ")}`)
+  }
+  lines.push("", "Start from these notes instead of reading the repository again: read only the files this test uses or changes, and read a file before you edit or reuse it, since it may have changed.")
+  return lines.join("\n")
+}

package/src/code/profile.ts

@@ -0,0 +1,226 @@
+import { readdirSync, readFileSync, statSync } from "node:fs"
+import path from "node:path"
+
+/**
+ * What ForgeQE reads from a repository before Scribe starts, without a model: the test stack, the settings files
+ * and the browser values in them (headless, channel, the test id attribute), the base classes, the page objects and
+ * their methods, one page object in full as the style to follow, and how one test is run. Scribe starts from this
+ * instead of discovering it with dozens of file reads, and the traps in it (a settings file that forces headless, a
+ * redefined test id attribute) are visible before the first run rather than after a failed one.
+ */
+
+export type RepoProfile = {
+  stack: string[]
+  settings: { file: string; values: Record<string, string> }[]
+  testIdAttribute?: { value: string; file: string }
+  baseClasses: { name: string; file: string; members: string[] }[]
+  pageObjects: { name: string; file: string; members: string[] }[]
+  example?: { file: string; content: string }
+  oneTest: string[]
+}
+
+const SKIP_DIRS = new Set(["node_modules", ".git", "bin", "obj", "dist", "build", "out", ".forgeqe", ".venv", "venv", "__pycache__", "coverage", "artifacts", "test-results", "playwright-report", ".next", "target"])
+const MAX_FILES = 4000
+const MAX_READ = 200_000
+const PAGE_DIRS = /(^|\/)(pages|page-?objects|pom|components|flows|screens)(\/|$)/i
+const MAX_MEMBERS = 14
+const MAX_CLASSES = 25
+
+function walk(repo: string): string[] {
+  const out: string[] = []
+  const visit = (dir: string) => {
+    if (out.length >= MAX_FILES) return
+    let entries: string[] = []
+    try {
+      entries = readdirSync(dir)
+    } catch {
+      return
+    }
+    for (const name of entries) {
+      if (out.length >= MAX_FILES) return
+      const full = path.join(dir, name)
+      let st
+      try {
+        st = statSync(full)
+      } catch {
+        continue
+      }
+      if (st.isDirectory()) {
+        if (!SKIP_DIRS.has(name) && !name.startsWith(".")) visit(full)
+      } else if (st.size <= MAX_READ) out.push(path.relative(repo, full).split(path.sep).join("/"))
+    }
+  }
+  visit(repo)
+  return out
+}
+
+const read = (repo: string, rel: string) => {
+  try {
+    return readFileSync(path.join(repo, rel), "utf8")
+  } catch {
+    return ""
+  }
+}
+
+/** Public and protected member signatures of a class body, one line each. */
+function members(source: string, lang: "cs" | "ts" | "py"): string[] {
+  const lines = source.split("\n").map((l) => l.trim())
+  const pick =
+    lang === "cs"
+      ? lines.filter((l) => /^(public|protected)\s/.test(l) && !/\b(class|record|struct|interface|enum)\b/.test(l))
+      : lang === "ts"
+        ? lines.filter((l) => /^(async\s+)?[a-zA-Z_]\w*\s*\(.*\)\s*(:\s*[^={]+)?\{?$/.test(l) && !/^(if|for|while|switch|return|catch)\b/.test(l))
+        : lines.filter((l) => /^(async\s+)?def\s+[a-zA-Z]\w*\(/.test(l) && !/^def\s+_/.test(l))
+  return [...new Set(pick.map((l) => l.replace(/\s*(=>.*|\{.*|:\s*$)$/, "").replace(/\s+/g, " ").slice(0, 160)))].slice(0, MAX_MEMBERS)
+}
+
+const XML_KEYS = ["BrowserName", "Headless", "Channel", "TestIdAttribute", "ExpectTimeout", "SlowMo", "Locale", "TimezoneId"]
+const JSON_KEYS = ["Headless", "Channel", "Browser", "BrowserName", "Locale", "TimezoneId", "UserAgent", "ViewportWidth", "ViewportHeight", "BaseUrl", "TestIdAttribute"]
+const TS_KEYS = ["headless", "channel", "locale", "timezoneId", "testIdAttribute", "baseURL", "viewport", "userAgent"]
+
+function settingValues(rel: string, text: string): Record<string, string> {
+  const values: Record<string, string> = {}
+  if (/\.runsettings$/i.test(rel)) {
+    for (const k of XML_KEYS) {
+      const m = text.match(new RegExp(`<${k}>([^<]*)</${k}>`, "i"))
+      if (m) values[k] = m[1].trim()
+    }
+  } else if (/\.json$/i.test(rel)) {
+    for (const k of JSON_KEYS) {
+      const m = text.match(new RegExp(`"${k}"\\s*:\\s*("[^"]*"|[\\w.-]+)`))
+      if (m) values[k] = m[1].replace(/^"|"$/g, "")
+    }
+  } else {
+    for (const k of TS_KEYS) {
+      const m = text.match(new RegExp(`\\b${k}\\s*:\\s*([^,\\n}]+)`))
+      if (m) values[k] = m[1].trim()
+    }
+  }
+  return values
+}
+
+export function buildProfile(repo: string): RepoProfile | null {
+  const files = walk(repo)
+  if (!files.length) return null
+  const profile: RepoProfile = { stack: [], settings: [], baseClasses: [], pageObjects: [], oneTest: [] }
+
+  // Stack: test frameworks and their versions.
+  const csproj = files.filter((f) => f.endsWith(".csproj"))
+  const testProjects: string[] = []
+  for (const f of csproj) {
+    const text = read(repo, f)
+    const pkgs = [...text.matchAll(/<PackageReference\s+Include="([^"]+)"\s+Version="([^"]+)"/g)].map((m) => `${m[1]} ${m[2]}`)
+    const interesting = pkgs.filter((p) => /playwright|nunit|xunit|mstest|shouldly|fluentassertions|reqnroll|specflow|selenium/i.test(p) && !/analyzers|adapter|collector/i.test(p))
+    if (/Microsoft\.NET\.Test\.Sdk/.test(text)) testProjects.push(f)
+    if (interesting.length) profile.stack.push(`${f}: ${interesting.join(", ")}`)
+  }
+  const pkgJson = files.filter((f) => /(^|\/)package\.json$/.test(f))
+  for (const f of pkgJson) {
+    try {
+      const doc = JSON.parse(read(repo, f)) as { dependencies?: Record<string, string>; devDependencies?: Record<string, string>; scripts?: Record<string, string> }
+      const deps = { ...doc.dependencies, ...doc.devDependencies }
+      const interesting = Object.entries(deps).filter(([n]) => /playwright|cypress|webdriverio|jest|vitest|mocha/.test(n))
+      if (interesting.length) profile.stack.push(`${f}: ${interesting.map(([n, v]) => `${n} ${v}`).join(", ")}`)
+      if (doc.scripts?.test) profile.stack.push(`${f} test script: ${doc.scripts.test}`)
+    } catch {
+      /* not JSON */
+    }
+  }
+  const pyDeps = files.filter((f) => /(^|\/)(pyproject\.toml|requirements[^/]*\.txt)$/.test(f))
+  for (const f of pyDeps) {
+    const hits = read(repo, f).match(/(pytest-playwright|playwright|pytest|selenium)[^\s"',]*/g)
+    if (hits?.length) profile.stack.push(`${f}: ${[...new Set(hits)].join(", ")}`)
+  }
+
+  // Settings files and the browser values in them.
+  const settingFiles = files.filter((f) => /\.runsettings$/i.test(f) || /(^|\/)appsettings[^/]*\.json$/i.test(f) || /(^|\/)playwright\.config\.(ts|js|mjs|cjs)$/.test(f))
+  for (const f of settingFiles) {
+    const values = settingValues(f, read(repo, f))
+    if (Object.keys(values).length) profile.settings.push({ file: f, values })
+  }
+
+  // A redefined test id attribute changes what getByTestId finds.
+  for (const s of profile.settings) {
+    const v = s.values.TestIdAttribute || s.values.testIdAttribute
+    if (v) {
+      profile.testIdAttribute = { value: v.replace(/^['"]|['"]$/g, ""), file: s.file }
+      break
+    }
+  }
+  const sources = files.filter((f) => /\.(cs|ts|js|py)$/.test(f) && !/\.d\.ts$/.test(f))
+  if (!profile.testIdAttribute) {
+    for (const f of sources) {
+      const m = read(repo, f).match(/(?:SetTestIdAttribute|setTestIdAttribute|set_test_id_attribute)\(\s*["']([^"']+)["']/)
+      if (m) {
+        profile.testIdAttribute = { value: m[1], file: f }
+        break
+      }
+    }
+  }
+
+  // Base classes and page objects.
+  const pages: { name: string; file: string; members: string[]; size: number }[] = []
+  for (const f of sources) {
+    const lang = f.endsWith(".cs") ? "cs" : f.endsWith(".py") ? "py" : "ts"
+    const text = read(repo, f)
+    const isBase = lang === "cs" ? /\babstract\s+class\s+\w+|class\s+Base\w*|:\s*(PageTest|ContextTest|BrowserTest)\b/.test(text) : /\bclass\s+Base\w*|test\.extend\(|@pytest\.fixture/.test(text)
+    const name = (text.match(/\bclass\s+(\w+)/) || [])[1] || path.basename(f).replace(/\.\w+$/, "")
+    const isPage = PAGE_DIRS.test(f) || /(Page|Component|Flow)\.(cs|ts|js|py)$/.test(f) || /\.page\.(ts|js)$/.test(f)
+    if (isBase && profile.baseClasses.length < MAX_CLASSES && !/tests?\//i.test(f.replace(/^src\//, ""))) {
+      profile.baseClasses.push({ name, file: f, members: members(text, lang) })
+    } else if (isPage && !/(test|spec)s?\b/i.test(path.basename(f)) && pages.length < MAX_CLASSES) {
+      pages.push({ name, file: f, members: members(text, lang), size: text.length })
+    }
+  }
+  profile.pageObjects = pages.map(({ size: _size, ...p }) => p)
+  // The style to follow: a page object of typical size, in full.
+  const examples = pages.filter((p) => p.size > 400 && p.size < 6000 && p.members.length >= 2).sort((a, b) => a.size - b.size)
+  const example = examples[Math.floor(examples.length / 2)]
+  if (example) profile.example = { file: example.file, content: read(repo, example.file) }
+
+  // How one test is run.
+  for (const p of testProjects) {
+    const runsettings = profile.settings.filter((s) => s.file.endsWith(".runsettings")).map((s) => s.file)
+    profile.oneTest.push(`dotnet test ${p} --filter "FullyQualifiedName~<Namespace>.<Class>.<Method>"${runsettings.length ? `  (settings files: ${runsettings.join(", ")}; add --settings <file> for the one whose browser values the test needs)` : ""}`)
+  }
+  if (files.some((f) => /(^|\/)playwright\.config\.(ts|js|mjs|cjs)$/.test(f))) profile.oneTest.push('npx playwright test <file> -g "<test title>"')
+  if (files.some((f) => /(^|\/)conftest\.py$/.test(f)) || pyDeps.length) profile.oneTest.push("pytest <file>::<test_name>")
+  // Only a recognised browser test stack is enough to start from; otherwise Scribe reads the repository itself.
+  const browserStack = testProjects.length > 0 || profile.stack.some((s) => /playwright|cypress|selenium|webdriverio/i.test(s))
+  return browserStack ? profile : null
+}
+
+/** The profile as the opening section of Scribe's first prompt. */
+export function profileSection(p: RepoProfile): string {
+  const lines = [
+    "## This repository, as ForgeQE read it",
+    "",
+    "ForgeQE read these from the files, without guessing. Start from them: read another file only when the test needs something they do not give.",
+    "",
+  ]
+  if (p.stack.length) lines.push("Test stack:", ...p.stack.map((s) => `- ${s}`), "")
+  if (p.oneTest.length) lines.push("One test is run with:", ...p.oneTest.map((s) => `- ${s}`), "")
+  if (p.settings.length) {
+    lines.push("Browser settings in the repository (a settings file the command passes wins over the defaults):")
+    for (const s of p.settings) lines.push(`- ${s.file}: ${Object.entries(s.values).map(([k, v]) => `${k}=${v}`).join(", ")}`)
+    lines.push("")
+  }
+  if (p.testIdAttribute) {
+    lines.push(
+      `Test ids: ${p.testIdAttribute.file} sets the test id attribute to "${p.testIdAttribute.value}", so getByTestId looks for ${p.testIdAttribute.value}="…", not data-testid. Use the handoff's attribute selectors ([data-testid="…"]) as given.`,
+      "",
+    )
+  }
+  if (p.baseClasses.length) {
+    lines.push("Base classes and fixtures:")
+    for (const c of p.baseClasses) lines.push(`- ${c.name} (${c.file})${c.members.length ? `: ${c.members.join("; ")}` : ""}`)
+    lines.push("")
+  }
+  if (p.pageObjects.length) {
+    lines.push("Page objects, components, and flows:")
+    for (const c of p.pageObjects) lines.push(`- ${c.name} (${c.file})${c.members.length ? `: ${c.members.join("; ")}` : ""}`)
+    lines.push("")
+  }
+  if (p.example) lines.push(`A page object to follow for style (${p.example.file}):`, "", "```", p.example.content.trimEnd(), "```", "")
+  return lines.join("\n").trimEnd()
+}

package/src/code/prompt.ts

@@ -0,0 +1,303 @@
+import type { CodeReview } from "../types.ts"
+import type { Handoff } from "./handoff.ts"
+import type { Stall } from "./runtime.ts"
+import { prompt } from "../prompts.ts"
+
+/** How every agent with skills uses them; the runtime lists the skills it may load. */
+export const skillRule = () => prompt("skill-rule")
+
+/** Rules for any test ForgeQE's agents write or change: the coding agent and the healing agent both follow them. */
+export const testRules = () => prompt("test-rules")
+
+/** System prompt of Scribe, the coding agent ForgeQE defines for writing tests. */
+export const testAgentPrompt = () => prompt("test-agent")
+
+export const RESULT_SCHEMA = {
+  type: "object",
+  properties: {
+    status: {
+      type: "string",
+      enum: ["passed", "blocked"],
+      description:
+        "passed: the test is written and ready for ForgeQE to run. blocked (last resort): the application cannot be reached, or still refuses after the test's browser matches ForgeQE's",
+    },
+    blocked_reason: {
+      type: "string",
+      description: "Only when blocked: what you compared between the test's browser and ForgeQE's, and what you saw (error or page text, screenshot or trace path)",
+    },
+    remote_browser: {
+      type: "string",
+      description: "Only when the repository's tests drive a browser on another machine (Selenium Grid, a cloud browser service, a container): where it runs",
+    },
+    test_file: { type: "string", description: "Path of the new or updated test, relative to the repository root" },
+    test_name: { type: "string", description: "The test's full name as the framework reports it, e.g. 'ADO-2236 Contact form submits' or 'tests/test_login.py::test_valid_user'" },
+    command: {
+      type: "string",
+      description:
+        "Shell command, run from the repository root, that runs only this test non-interactively and exits non-zero on failure",
+    },
+    reused: {
+      type: "array",
+      items: { type: "string" },
+      description: "Existing page objects, fixtures, helpers, or config the test reuses (paths or names)",
+    },
+    changed: { type: "array", items: { type: "string" }, description: "Files created or modified" },
+    notes: { type: "string", description: "Anything the user should know, in one or two sentences" },
+  },
+  required: ["test_file", "command"],
+} as const
+
+export type AgentReport = {
+  status?: "passed" | "blocked"
+  blocked_reason?: string
+  remote_browser?: string
+  test_file?: string
+  test_name?: string
+  command?: string
+  reused?: string[]
+  changed?: string[]
+  notes?: string
+}
+
+/** While ForgeQE replays the steps in Playwright, Scribe learns the repository, without changing anything yet. */
+export function preparePrompt(goal: string, checking = true): string {
+  return [
+    checking
+      ? "ForgeQE's browser agent completed a flow in a real browser, and ForgeQE is now checking its steps in Playwright. The flow and that check's result come in the next message."
+      : "ForgeQE's browser agent completed a flow in a real browser. The flow comes in the next message.",
+    `The flow's goal: ${goal}`,
+    "Meanwhile, learn this repository's test setup as your instructions describe: the framework and its config, how one test is run, the page objects, fixtures, and helpers this goal would use, and where the browser is configured. Do not create or change files, and do not build or run tests yet.",
+    "Reply with notes a later job on this repository can start from without reading it again, in at most 25 lines: the language, test framework and versions; the exact command that runs one test; where tests, page objects, flows, fixtures, and test data live, and the base classes and helpers tests use; where and how the browser is configured; and the conventions (naming, attributes and categories, assertion library, async style).",
+  ].join("\n")
+}
+
+/** A test this case already has, which now fails: the job updates it instead of writing a new one. */
+export type ExistingTest = { testFile: string; command: string; output: string; why: string }
+
+function existingSection(e: ExistingTest): string[] {
+  return [
+    "## The test this case already has",
+    "",
+    `This test case already has a test: ${e.testFile}, run with: ${e.command}`,
+    e.why,
+    "ForgeQE ran it before this job. The end of its output:",
+    "",
+    "```",
+    e.output.split("\n").slice(-40).join("\n"),
+    "```",
+    "",
+    "Update that test, and the page objects it uses, to match the verified run below: change only what no longer matches. Do not write a new test file. Report its path as test_file.",
+    "",
+  ]
+}
+
+export function firstPrompt(handoff: Handoff, opts: { liveBrowserDir?: string; liveOn?: boolean; notes?: string; profile?: string; existing?: ExistingTest } = {}): string {
+  const live = opts.liveBrowserDir
+    ? opts.liveOn
+      ? `Your live_browser_* tools are on because the replay failed at a step; use them on that step's page. They save snapshots and screenshots in ${opts.liveBrowserDir}.`
+      : `Your live_browser_* tools are switched on if a test failure repeats; they save snapshots and screenshots in ${opts.liveBrowserDir}.`
+    : ""
+  return [
+    opts.existing
+      ? `Update the existing test for the flow below so it passes again. When it is updated, give the structured result; ForgeQE then runs it.`
+      : `Write a test in this repository for the flow below, reusing the repository's existing test code. When it is written, give the structured result; ForgeQE then runs it.`,
+    "",
+    ...(opts.existing ? existingSection(opts.existing) : []),
+    ...(opts.profile ? [opts.profile, ""] : []),
+    ...(opts.notes ? [opts.notes, ""] : []),
+    handoff.markdown,
+    "",
+    `(The same handoff is saved at ${handoff.file}; you do not need to read it again.)`,
+    ...(live ? [live] : []),
+  ].join("\n")
+}
+
+/** A failed run's output for a prompt, with where its full output and the page at the failure were saved. */
+type FailureFiles = { log?: string; pageSnapshot?: string; context?: string[] }
+
+function failureBlock(exitCode: number | null, output: string, files: FailureFiles = {}): string[] {
+  const how = exitCode === null ? "timed out" : `exited with code ${exitCode}`
+  return [
+    `It ${how}. The output (the failure message first; long output shortened):`,
+    "",
+    "```",
+    output,
+    "```",
+    ...(files.log ? [`Full output: ${files.log}`] : []),
+    ...(files.pageSnapshot ? [`The page at the failure, as Playwright saw it (roles and accessible names; search it for the element you need): ${files.pageSnapshot}`] : []),
+    ...(files.context?.length ? ["", "Compare these before changing code:", ...files.context] : []),
+  ]
+}
+
+const GIVE_RESULT = "Then give the structured result again; ForgeQE runs the test."
+
+/** A file the job changed, with its current contents when it is small enough to inline. */
+export type ChangedFile = { path: string; content?: string }
+
+/**
+ * The first prompt of a fresh session for the next attempt. Each attempt starts a new session so the model is not
+ * sent every earlier attempt's tool calls again: this brief carries what matters from them instead.
+ */
+export function nextAttemptPrompt(opts: {
+  handoff: Handoff
+  notes?: string
+  testFile?: string
+  command?: string
+  changed: ChangedFile[]
+  attempts: string[]
+  /** What to do now: the fix, review, or no-browser prompt for the latest run. */
+  task: string
+  liveBrowserDir?: string
+  liveOn?: boolean
+}): string {
+  const files = opts.changed.map((f) =>
+    f.content === undefined ? `- ${f.path} (read it if you need it)` : [`### ${f.path}`, "", "```", f.content.trimEnd(), "```"].join("\n"),
+  )
+  const live = opts.liveBrowserDir && opts.liveOn ? `Your live_browser_* tools are on; they save snapshots and screenshots in ${opts.liveBrowserDir}.` : ""
+  return [
+    "You are continuing a test-writing job in a new session. The earlier attempts' conversation is not here; this message carries what matters from it. Do not re-read the repository broadly: the notes, the handoff, and the files below are the state of the job. Read another file only when the fix needs it.",
+    "",
+    ...(opts.notes ? [opts.notes, ""] : []),
+    handoff(opts.handoff),
+    "",
+    "## The job so far",
+    "",
+    ...(opts.testFile ? [`Test file: ${opts.testFile}`] : []),
+    ...(opts.command ? [`Command ForgeQE runs: ${opts.command}`] : []),
+    "",
+    "Attempts, in order (what was run and how it ended):",
+    ...opts.attempts.map((a) => `- ${a}`),
+    "",
+    "Files this job created or changed, as they are now:",
+    "",
+    ...files,
+    "",
+    "## Now",
+    "",
+    opts.task,
+    ...(live ? ["", live] : []),
+  ].join("\n")
+}
+
+const handoff = (h: Handoff) => [h.markdown, "", `(The same handoff is saved at ${h.file}.)`].join("\n")
+
+/** Said with the next prompt when the live browser has just been switched on. */
+export const LIVE_ON_NOTE = "Your live_browser_* tools are now on: look at the step it fails at there before changing code."
+
+export function stallPrompt(stall: Stall, liveBrowser: boolean): string {
+  return [
+    `ForgeQE stopped your turn: you ran this command ${stall.count} times and it failed every time.`,
+    "```",
+    stall.command,
+    "```",
+    "Last part of its output:",
+    "```",
+    stall.output,
+    "```",
+    liveBrowser
+      ? "Do not run it again as it is. Open the step it fails at in your live_browser_* tools, see what the page shows and does there (snapshot, screenshot, console, network), and change the approach to fit what you see."
+      : "Do not run it again as it is. Find out what the page shows and does at the step it fails at, and change the approach to fit what you see.",
+    `If the page cannot do what the handoff did, even though its browser matches ForgeQE's, give status blocked with the step, what you tried, and what the page showed. Otherwise finish the test. ${GIVE_RESULT}`,
+  ].join("\n")
+}
+
+/**
+ * What ForgeQE saw the test's browser do differently from the run's browser (from the processes the test started):
+ * headless where the run was headed or the other way round, Chromium where the run used Chrome. Empty when they match.
+ */
+export function browserMismatch(run: { headless?: boolean; channel?: string } | undefined, browsers: string[], command: string): string {
+  if (!run || !browsers.length) return ""
+  const headless = browsers.every((b) => b.endsWith("(headless)"))
+  const headed = browsers.every((b) => !b.endsWith("(headless)"))
+  const differences: string[] = []
+  if (run.headless === false && headless) differences.push("it ran headless, but the run that passed used a visible (headed) browser")
+  if (run.headless === true && headed) differences.push("it ran a visible browser, but the run that passed was headless")
+  if (/^chrome/i.test(run.channel || "") && browsers.every((b) => !/chrome/i.test(b))) differences.push(`it launched ${browsers[0]}, but the run that passed used Google Chrome`)
+  if (!differences.length) return ""
+  const settings = command.match(/--settings\s+(\S+)|--config[= ](\S+)|-c\s+(\S+\.(?:json|ts|js|ya?ml))/)
+  const where = settings ? ` Your command passes ${settings[1] || settings[2] || settings[3]}: a value there overrides the repository's other settings.` : ""
+  return [
+    "",
+    `ForgeQE watched the browser your test started (${browsers.join(", ")}): ${differences.join("; ")}. The setting you made is not the one in effect for this command.${where} Make the run's setting the effective one for this test (the file or environment variable that wins for this command), then run it again. Sites serve another version of the page, or a bot challenge, to a browser set up differently.`,
+  ].join("\n")
+}
+
+export function fixPrompt(attempt: number, command: string, exitCode: number | null, output: string, files: FailureFiles = {}): string {
+  return [
+    `ForgeQE ran your test and it failed (attempt ${attempt}). Command: ${command}`,
+    ...failureBlock(exitCode, output, files),
+    "",
+    `Fix what the failure names: the test, a page object, config, or the environment, keeping to your rules. If the test's browser got a different page than ForgeQE's did, follow "When the test's page differs from what ForgeQE saw" first. ${GIVE_RESULT} Status blocked is only for an application that still refuses once the test's browser matches ForgeQE's.`,
+  ].join("\n")
+}
+
+export function repeatedFailurePrompt(times: number, command: string, exitCode: number | null, output: string, files: FailureFiles = {}): string {
+  return [
+    `ForgeQE ran your test and it failed exactly as the last time (${times} times in a row), apart from numbers such as timings and line numbers: your last change did not change the failure. Command: ${command}`,
+    ...failureBlock(exitCode, output, files),
+    "",
+    "Before changing code again, look at the step it fails at: what the page shows there, what is open over it, and the console errors and failed requests while it runs. Then change the approach to fit what you see. If it fails the same way once more, ForgeQE stops the job.",
+    `If the page cannot do what the handoff did, even though the test's browser matches ForgeQE's, give status blocked with the step, what you tried, and what the page showed. ${GIVE_RESULT}`,
+  ].join("\n")
+}
+
+export function noBrowserPrompt(command: string): string {
+  return [
+    `ForgeQE ran your test and it exited 0, but no browser started while it ran. Command: ${command}`,
+    "A passing exit code is not enough: the test must drive the application in a browser through the repository's test framework, as the verified run did. Check that the command runs the test you wrote (a filter that matches nothing also exits 0) and that the test opens the browser.",
+    `Fix it. ${GIVE_RESULT} If this repository's tests drive a browser on another machine (Selenium Grid, a cloud browser service, a container), say where in remote_browser.`,
+  ].join("\n")
+}
+
+export function blockedChallengePrompt(handoff: Handoff): string {
+  return [
+    "ForgeQE's browser completed this flow on the same application from this machine, so a refusal usually comes from how the test's browser is set up.",
+    `Before reporting blocked, follow "When the test's page differs from what ForgeQE saw" and compare the test's browser with the one in the handoff (${handoff.file}, section "Browser ForgeQE used"): user agent, navigator.webdriver, headless, channel and version, failed requests and CORS errors, headers the framework adds, console errors. Change the repository's browser configuration to match.`,
+    "Then give the structured result with status passed, and ForgeQE runs the test. If the page still refuses after matching every point, give status blocked with what you compared and what you saw.",
+  ].join("\n")
+}
+
+export type ReviewIssue = CodeReview["issues"][number]
+
+export function reviewFixPrompt(summary: string, issues: ReviewIssue[]): string {
+  return [
+    "ForgeQE's run of your test passed, but a reviewer checked your change against the goal and the test rules and did not approve it:",
+    summary,
+    "",
+    ...issues.map((i, n) => `${n + 1}. ${i.file ? `${i.file}: ` : ""}${i.problem}${i.fix ? ` Fix: ${i.fix}` : ""}`),
+    "",
+    `Fix each point, keeping to your rules. A point about a file you did not create or change in this job is not yours to fix: leave the file as it is and say so in notes. ${GIVE_RESULT}`,
+  ].join("\n")
+}
+
+/** The test works and tests the goal; the reviewer found only coding-standard issues: one round to fix them. */
+export function standardsFixPrompt(issues: ReviewIssue[]): string {
+  return [
+    "ForgeQE's run of your test passed, and the reviewer agrees it tests what the goal asks. It found these coding-standard issues:",
+    "",
+    ...issues.map((i, n) => `${n + 1}. ${i.file ? `${i.file}: ` : ""}${i.problem}${i.fix ? ` Fix: ${i.fix}` : ""}`),
+    "",
+    "Fix them without changing what the test does: keep its steps, locators, waits, and assertions. Test data (users, values, expected texts) belongs in the test and goes to page object methods as parameters; credentials come from the environment variables the handoff names. Change only what these points need.",
+    `${GIVE_RESULT} If the change breaks the test, ForgeQE keeps the version that passed.`,
+  ].join("\n")
+}
+
+export const RESUMED_NOTE =
+  "ForgeQE stopped before this job finished (it was closed, the machine restarted, or the connection dropped), and this is the same session again. Your earlier messages are above, and the files you wrote are still in the repository: check them before changing anything, and do not start over."
+
+/** The first message when Scribe's session is reopened after it had started on the test. */
+export function carryOnPrompt(liveOn: boolean): string {
+  return [
+    RESUMED_NOTE,
+    "Carry on from where you stopped: finish the test and give the structured result with test_file and command; ForgeQE then runs it.",
+    ...(liveOn ? [LIVE_ON_NOTE] : []),
+  ].join("\n\n")
+}
+
+export function restoredNote(paths: string[]): string {
+  return `ForgeQE put back files that existed before this job, which you removed or reverted: ${paths.join(", ")}. They are the user's work or ForgeQE's; leave them as they are.`
+}
+
+export function missingCommandPrompt(): string {
+  return "Your result did not include a test file and a command that runs it. Finish the test and give the structured result with test_file and command; ForgeQE then runs it."
+}