@capagents/forgeqe 0.0.0-stage → 1.0.0

package/src/notify/notice.ts

@@ -0,0 +1,177 @@
+import { existsSync } from "node:fs"
+import os from "node:os"
+import path from "node:path"
+
+import nodemailer from "nodemailer"
+
+import type { EmailConfig, MonitorAlerts } from "../config.ts"
+
+/**
+ * One notification, whatever it is about (a monitor round, a suite, a release verdict, an evaluation), and how it
+ * looks in Teams (an Adaptive Card, which incoming webhooks and Workflows webhooks both accept) and in email.
+ */
+
+export type Status = "good" | "bad" | "warn"
+export type Link = { title: string; url: string }
+
+export type NoticeItem = { line: string; status?: Status; details?: string[]; links?: Link[] }
+
+export type Notice = {
+  /** What sent it, before the title: "ForgeQE monitor", "ForgeQE suite". */
+  source: string
+  title: string
+  status: Status
+  /** One line under the title: when, how many, where. */
+  subtitle: string
+  items: NoticeItem[]
+  /** Buttons under the card (Open report, Open build) and links at the end of the email. */
+  actions?: Link[]
+  /** A last line for what has no link, e.g. the report's path on the machine that ran it. */
+  note?: string
+  /** Email only: files to attach, such as failure screenshots. */
+  attachments?: { filename: string; path: string }[]
+}
+
+export type Sent = { channel: "teams" | "email"; ok: boolean; error?: string }
+
+const CARD_COLOR: Record<Status, string> = { good: "Good", bad: "Attention", warn: "Warning" }
+const MAIL_COLOR: Record<Status, string> = { good: "#067647", bad: "#b42318", warn: "#b54708" }
+
+export function teamsCard(n: Notice): Record<string, unknown> {
+  const body: Record<string, unknown>[] = [
+    { type: "TextBlock", text: `${n.source}: ${n.title}`, weight: "Bolder", size: "Medium", wrap: true, color: CARD_COLOR[n.status] },
+    { type: "TextBlock", text: n.subtitle, isSubtle: true, spacing: "None", wrap: true },
+  ]
+  for (const i of n.items) {
+    body.push({
+      type: "Container",
+      separator: true,
+      items: [
+        { type: "TextBlock", text: i.line, weight: "Bolder", wrap: true, ...(i.status ? { color: CARD_COLOR[i.status] } : {}) },
+        ...(i.details || []).map((text) => ({ type: "TextBlock", text, wrap: true, isSubtle: true, spacing: "Small" })),
+        ...(i.links?.length ? [{ type: "TextBlock", text: i.links.map((l) => `[${l.title}](${l.url})`).join(" · "), spacing: "Small", wrap: true }] : []),
+      ],
+    })
+  }
+  if (n.note) body.push({ type: "TextBlock", text: n.note, isSubtle: true, wrap: true, size: "Small" })
+  return {
+    type: "message",
+    attachments: [
+      {
+        contentType: "application/vnd.microsoft.card.adaptive",
+        contentUrl: null,
+        content: {
+          $schema: "http://adaptivecards.io/schemas/adaptive-card.json",
+          type: "AdaptiveCard",
+          version: "1.4",
+          msteams: { width: "Full" },
+          body,
+          ...(n.actions?.length ? { actions: n.actions.map((a) => ({ type: "Action.OpenUrl", title: a.title, url: a.url })) } : {}),
+        },
+      },
+    ],
+  }
+}
+
+const esc = (s: string) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;")
+
+export function noticeEmail(n: Notice): { subject: string; text: string; html: string; attachments: { filename: string; path: string }[] } {
+  const text = [
+    n.subtitle,
+    "",
+    ...n.items.flatMap((i) => [i.line, ...(i.details || []).map((d) => `    ${d}`), ...(i.links || []).map((l) => `    ${l.title}: ${l.url}`)]),
+    "",
+    ...(n.actions || []).map((a) => `${a.title}: ${a.url}`),
+    n.note || "",
+  ]
+    .filter((l, idx, all) => l !== "" || (idx > 0 && all[idx - 1] !== ""))
+    .join("\n")
+    .trim()
+  const rows = n.items
+    .map((i) => {
+      const color = i.status ? MAIL_COLOR[i.status] : "#111"
+      const details = (i.details || []).map((d) => `<div style="color:#555">${esc(d)}</div>`).join("")
+      const links = i.links?.length ? `<div>${i.links.map((l) => `<a href="${esc(l.url)}">${esc(l.title)}</a>`).join(" · ")}</div>` : ""
+      return `<tr><td style="padding:8px 0;border-top:1px solid #eee"><div style="color:${color};font-weight:600">${esc(i.line)}</div>${details}${links}</td></tr>`
+    })
+    .join("")
+  const actions = n.actions?.length ? `<p>${n.actions.map((a) => `<a href="${esc(a.url)}">${esc(a.title)}</a>`).join(" · ")}</p>` : ""
+  const note = n.note ? `<p style="color:#555">${esc(n.note)}</p>` : ""
+  const html = `<div style="font-family:-apple-system,Segoe UI,Roboto,sans-serif;font-size:14px"><h2 style="margin:0 0 4px;color:${MAIL_COLOR[n.status]}">${esc(`${n.source}: ${n.title}`)}</h2><p style="color:#555;margin:0 0 12px">${esc(n.subtitle)}</p><table style="border-collapse:collapse;width:100%">${rows}</table>${actions}${note}</div>`
+  return { subject: `[ForgeQE] ${n.title}`, text, html, attachments: (n.attachments || []).filter((a) => existsSync(a.path)) }
+}
+
+export type Mailer = { sendMail(mail: Record<string, unknown>): Promise<unknown> }
+
+export function smtpTransport(cfg: EmailConfig): Mailer {
+  const user = process.env[cfg.usernameEnv]
+  const pass = process.env[cfg.passwordEnv]
+  return nodemailer.createTransport({
+    host: cfg.host,
+    port: cfg.port,
+    secure: cfg.secure,
+    ...(user ? { auth: { user, pass: pass || "" } } : {}),
+    connectionTimeout: 20_000,
+    greetingTimeout: 20_000,
+    socketTimeout: 30_000,
+  })
+}
+
+export async function sendTeams(webhook: string, n: Notice, fetcher: typeof fetch = fetch): Promise<void> {
+  const res = await fetcher(webhook, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(teamsCard(n)),
+    signal: AbortSignal.timeout(20_000),
+  })
+  if (!res.ok) {
+    const text = (await res.text().catch(() => "")).replace(/\s+/g, " ").slice(0, 200)
+    throw new Error(`the Teams webhook answered ${res.status}${text ? `: ${text}` : ""}`)
+  }
+}
+
+export async function sendEmail(cfg: EmailConfig, n: Notice, transport: Mailer = smtpTransport(cfg)): Promise<void> {
+  const c = noticeEmail(n)
+  const from = cfg.from || process.env[cfg.usernameEnv] || `forgeqe@${os.hostname()}`
+  await transport.sendMail({ from, to: cfg.to.join(", "), subject: c.subject, text: c.text, html: c.html, attachments: c.attachments })
+}
+
+export type SendDeps = { fetch?: typeof fetch; mailer?: (cfg: EmailConfig) => Mailer }
+
+/** Send to every channel of `to`; one that fails does not stop the others, and no secret reaches an error. */
+export async function sendNotice(to: MonitorAlerts, n: Notice, deps: SendDeps = {}): Promise<Sent[]> {
+  const sent: Sent[] = []
+  if (to.teams) {
+    const url = process.env[to.teams.webhookEnv]
+    if (!url) sent.push({ channel: "teams", ok: false, error: `${to.teams.webhookEnv} is not set` })
+    else {
+      try {
+        await sendTeams(url, n, deps.fetch)
+        sent.push({ channel: "teams", ok: true })
+      } catch (err) {
+        // The webhook URL is a secret; errors from fetch can contain it.
+        sent.push({ channel: "teams", ok: false, error: ((err as Error).message || String(err)).split(url).join("<webhook>") })
+      }
+    }
+  }
+  if (to.email) {
+    try {
+      await sendEmail(to.email, n, deps.mailer ? deps.mailer(to.email) : undefined)
+      sent.push({ channel: "email", ok: true })
+    } catch (err) {
+      const pass = process.env[to.email.passwordEnv]
+      const msg = (err as Error).message || String(err)
+      sent.push({ channel: "email", ok: false, error: pass ? msg.split(pass).join("<password>") : msg })
+    }
+  }
+  return sent
+}
+
+/** "screenshot of SHOP-12": a file name safe for an email attachment. */
+export function attachmentName(id: string, suffix: string): string {
+  return `${id.replace(/[^A-Za-z0-9._-]+/g, "-")}-${suffix}`
+}
+
+export function failureShot(runDir: string | undefined, id: string): { filename: string; path: string } | null {
+  return runDir ? { filename: attachmentName(id, "failure.png"), path: path.join(runDir, "failure.png") } : null
+}

package/src/prices.ts

@@ -0,0 +1,175 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import { forgeqeHome } from "./tools.ts"
+
+/**
+ * Models' list prices, from two public price lists: models.dev (the list the agent runtime itself uses) and LiteLLM's
+ * model_prices_and_context_window.json, which also has Azure's Data Zone prices. ForgeQE keeps the few fields it needs
+ * for the providers it supports in ~/.forgeqe/prices.json and refreshes it once a day; nothing about a run is sent,
+ * the lists are plain downloads. A price in llms.json always wins (a negotiated or enterprise rate).
+ */
+
+export const MODELS_DEV_URL = "https://models.dev/api.json"
+export const LITELLM_URL = "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json"
+const MAX_AGE_MS = 24 * 3600_000
+const FETCH_TIMEOUT_MS = 15_000
+
+/** Per million tokens, in US dollars. `above` is the price once one request's input passes `tokens`. */
+export type ListPrice = {
+  input: number
+  output: number
+  cacheRead?: number
+  cacheWrite?: number
+  above?: { tokens: number; input: number; output: number; cacheRead?: number }
+  source: "models.dev" | "LiteLLM"
+}
+
+type PriceFile = { fetchedAt: string; sources: string[]; models: Record<string, ListPrice> }
+
+/** Providers ForgeQE's profiles use, as the lists name them. */
+const PROVIDERS: Record<string, string[]> = {
+  openai: ["openai"],
+  azure: ["azure", "openai"],
+  anthropic: ["anthropic"],
+  gemini: ["google"],
+  google: ["google"],
+  mistral: ["mistral"],
+  deepseek: ["deepseek"],
+  openrouter: ["openrouter"],
+}
+
+const file = () => process.env.FORGEQE_PRICES_FILE || path.join(forgeqeHome(), "prices.json")
+const offline = () => /^(0|off|false|no)$/i.test(process.env.FORGEQE_PRICES || "")
+
+async function getJson(url: string): Promise<unknown> {
+  const res = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) })
+  if (!res.ok) throw new Error(`${url}: ${res.status}`)
+  return res.json()
+}
+
+const perM = (perToken: unknown) => (typeof perToken === "number" && Number.isFinite(perToken) ? Math.round(perToken * 1e6 * 1e6) / 1e6 : undefined)
+
+/** models.dev: { provider: { models: { id: { cost: { input, output, cache_read, cache_write, tiers } } } } }, already per million. */
+export function fromModelsDev(data: unknown): Record<string, ListPrice> {
+  const out: Record<string, ListPrice> = {}
+  const wanted = new Set(Object.values(PROVIDERS).flat())
+  for (const [provider, entry] of Object.entries((data || {}) as Record<string, { models?: Record<string, { cost?: Record<string, any> }> }>)) {
+    if (!wanted.has(provider)) continue
+    for (const [id, model] of Object.entries(entry?.models || {})) {
+      const c = model?.cost
+      if (!c || typeof c.input !== "number" || typeof c.output !== "number") continue
+      const tier = Array.isArray(c.tiers) ? c.tiers.find((t: any) => t?.tier?.type === "context" && Number(t.tier.size) > 0) : undefined
+      out[`${provider}/${id.toLowerCase()}`] = {
+        input: c.input,
+        output: c.output,
+        ...(typeof c.cache_read === "number" ? { cacheRead: c.cache_read } : {}),
+        ...(typeof c.cache_write === "number" ? { cacheWrite: c.cache_write } : {}),
+        ...(tier ? { above: { tokens: Number(tier.tier.size), input: tier.input, output: tier.output, ...(typeof tier.cache_read === "number" ? { cacheRead: tier.cache_read } : {}) } } : {}),
+        source: "models.dev",
+      }
+    }
+  }
+  return out
+}
+
+/** LiteLLM: { "azure/eu/gpt-5.4": { input_cost_per_token, output_cost_per_token, cache_read_input_token_cost, … } }, per token. */
+export function fromLiteLLM(data: unknown): Record<string, ListPrice> {
+  const out: Record<string, ListPrice> = {}
+  const wanted = new Set(Object.values(PROVIDERS).flat())
+  for (const [key, e] of Object.entries((data || {}) as Record<string, Record<string, unknown>>)) {
+    const input = perM(e?.input_cost_per_token)
+    const output = perM(e?.output_cost_per_token)
+    if (input === undefined || output === undefined) continue
+    const provider = String(e.litellm_provider || key.split("/")[0])
+    const name = key.includes("/") ? key : `${provider}/${key}`
+    if (!wanted.has(name.split("/")[0])) continue
+    const cacheRead = perM(e.cache_read_input_token_cost)
+    const cacheWrite = perM(e.cache_creation_input_token_cost)
+    const aboveKey = Object.keys(e).find((k) => /^input_cost_per_token_above_(\d+)k_tokens$/.test(k))
+    const aboveTokens = aboveKey ? Number(/_(\d+)k_/.exec(aboveKey)![1]) * 1000 : 0
+    const sfx = aboveTokens ? `_above_${aboveTokens / 1000}k_tokens` : ""
+    out[name.toLowerCase()] = {
+      input,
+      output,
+      ...(cacheRead !== undefined ? { cacheRead } : {}),
+      ...(cacheWrite !== undefined ? { cacheWrite } : {}),
+      ...(aboveTokens && perM(e[`input_cost_per_token${sfx}`]) !== undefined && perM(e[`output_cost_per_token${sfx}`]) !== undefined
+        ? {
+            above: {
+              tokens: aboveTokens,
+              input: perM(e[`input_cost_per_token${sfx}`])!,
+              output: perM(e[`output_cost_per_token${sfx}`])!,
+              ...(perM(e[`cache_read_input_token_cost${sfx}`]) !== undefined ? { cacheRead: perM(e[`cache_read_input_token_cost${sfx}`]) } : {}),
+            },
+          }
+        : {}),
+      source: "LiteLLM",
+    }
+  }
+  return out
+}
+
+let loaded: PriceFile | null | undefined
+
+function readFile(): PriceFile | null {
+  if (loaded !== undefined) return loaded
+  try {
+    loaded = JSON.parse(readFileSync(file(), "utf8")) as PriceFile
+  } catch {
+    loaded = null
+  }
+  return loaded
+}
+
+/** Download both lists and keep what ForgeQE needs; models.dev wins where both have a model. Returns what was saved. */
+export async function refreshPrices(get: (url: string) => Promise<unknown> = getJson): Promise<PriceFile | null> {
+  const [dev, lite] = await Promise.allSettled([get(MODELS_DEV_URL).then(fromModelsDev), get(LITELLM_URL).then(fromLiteLLM)])
+  const sources = [dev.status === "fulfilled" ? "models.dev" : "", lite.status === "fulfilled" ? "LiteLLM" : ""].filter(Boolean)
+  if (!sources.length) return null
+  const models = { ...(lite.status === "fulfilled" ? lite.value : {}), ...(dev.status === "fulfilled" ? dev.value : {}) }
+  const data: PriceFile = { fetchedAt: new Date().toISOString(), sources, models }
+  mkdirSync(path.dirname(file()), { recursive: true })
+  const tmp = `${file()}.${process.pid}`
+  writeFileSync(tmp, JSON.stringify(data))
+  renameSync(tmp, file())
+  loaded = data
+  return data
+}
+
+/**
+ * Make sure there is a price list: the first time, wait (a few seconds at most) for one; after that, refresh a list
+ * older than a day in the background. Never throws; offline or with FORGEQE_PRICES=off it uses what it has.
+ */
+export async function ensurePrices(): Promise<void> {
+  if (offline()) return
+  const have = existsSync(file()) ? readFile() : null
+  const stale = !have || Date.now() - Date.parse(have.fetchedAt) > MAX_AGE_MS
+  if (!stale) return
+  const job = refreshPrices().catch(() => null)
+  if (!have) await Promise.race([job, new Promise((r) => setTimeout(r, 8_000))])
+}
+
+/** "Global" (the default), or "data_zone" for an Azure Data Zone deployment, which costs about 10% more. */
+export type DeploymentType = "global" | "data_zone"
+
+/** The list price of a profile's model, or null when neither list has it. */
+export function listPrice(provider: string, model: string, deployment: DeploymentType = "global", prices: Record<string, ListPrice> | undefined = readFile()?.models): ListPrice | null {
+  if (!prices) return null
+  const ids = [model.toLowerCase(), model.toLowerCase().replace(/-\d{4}-\d{2}-\d{2}$/, "")]
+  const keys: string[] = []
+  if (provider === "azure" && deployment === "data_zone") for (const id of ids) keys.push(`azure/eu/${id}`, `azure/us/${id}`)
+  for (const p of PROVIDERS[provider] || [provider]) for (const id of ids) keys.push(`${p}/${id}`)
+  for (const k of keys) if (prices[k]) return prices[k]
+  return null
+}
+
+/** When the list was fetched, for cost notes ("list price, models.dev, 2026-10-06"). */
+export function pricesDate(): string | undefined {
+  return readFile()?.fetchedAt?.slice(0, 10)
+}
+
+/** Forget the loaded list (tests, or after the home folder changed). */
+export function resetPrices() {
+  loaded = undefined
+}

package/src/print.ts

@@ -0,0 +1,54 @@
+import { briefText, shows, stepIntent, type Detail } from "./detail.ts"
+import type { AgentEvent } from "./types.ts"
+
+const c = {
+  dim: (s: string) => `\x1b[2m${s}\x1b[0m`,
+  cyan: (s: string) => `\x1b[36m${s}\x1b[0m`,
+  green: (s: string) => `\x1b[32m${s}\x1b[0m`,
+  red: (s: string) => `\x1b[31m${s}\x1b[0m`,
+  yellow: (s: string) => `\x1b[33m${s}\x1b[0m`,
+  magenta: (s: string) => `\x1b[35m${s}\x1b[0m`,
+}
+
+export function formatEvent(event: AgentEvent, color = true, detail: Detail = "brief"): string | null {
+  const paint = (fn: (s: string) => string, text: string) => (color ? fn(text) : text)
+  if (event.type !== "done" && !shows(event, detail)) return null
+  switch (event.type) {
+    case "log":
+      return event.level === "error"
+        ? paint(c.red, event.text)
+        : event.level === "warn"
+          ? paint(c.yellow, event.text)
+          : paint(c.dim, event.text)
+    case "step":
+      return paint(
+        c.dim,
+        `step ${event.step}  ${[event.source === "memory" ? "(memory)" : event.category, event.title || "untitled", event.url].filter(Boolean).join("  ")}`,
+      )
+    case "memory":
+      return paint(c.magenta, `↻ ${event.text}`)
+    case "thought":
+      return paint(c.cyan, detail === "full" ? `  ${event.text}` : stepIntent(event.step, event.text, detail))
+    case "outcome":
+      return `  ${event.ok ? paint(c.green, "ok") : paint(c.red, "fail")}  ${briefText(event.text, detail)}`
+    case "usage":
+      return null
+    case "done":
+      return `${event.result.status}: ${event.result.summary}`
+    case "code":
+      switch (event.kind) {
+        case "info":
+          return paint(c.magenta, `▸ ${event.text}`)
+        case "tool":
+          return event.ok ? paint(c.dim, `  ⚙ ${event.text}`) : paint(c.yellow, `  ⚙ ${event.text}`)
+        case "say":
+          return paint(c.cyan, `  ${event.text}`)
+        case "test":
+          return event.ok ? paint(c.green, `✓ ${event.text}`) : paint(c.red, `✗ ${event.text}`)
+        default:
+          return null
+      }
+    default:
+      return null
+  }
+}

package/src/privacy.ts

@@ -0,0 +1,35 @@
+/**
+ * Environment for every process ForgeQE starts (the ForgeQE engine, the agent runtime, the repo's test command) that
+ * turns off usage telemetry, cloud sync, update checks, and trace export.
+ */
+export const NO_TELEMETRY_ENV: Record<string, string> = {
+  // engine library: PostHog product telemetry, cloud sync, and the LiteLLM price-list download
+  ANONYMIZED_TELEMETRY: "false",
+  BROWSER_USE_CLOUD_SYNC: "false",
+  BROWSER_USE_CALCULATE_COST: "false",
+  // agent runtime: auto-update, session sharing, and the models.dev catalog download (the bundled catalog is used)
+  OPENCODE_DISABLE_AUTOUPDATE: "1",
+  OPENCODE_DISABLE_SHARE: "1",
+  OPENCODE_DISABLE_MODELS_FETCH: "1",
+  // OpenTelemetry SDKs, and tools a repo's test command may start
+  OTEL_SDK_DISABLED: "true",
+  DO_NOT_TRACK: "1",
+  NEXT_TELEMETRY_DISABLED: "1",
+  NUXT_TELEMETRY_DISABLED: "1",
+  ASTRO_TELEMETRY_DISABLED: "1",
+  GATSBY_TELEMETRY_DISABLED: "1",
+  STORYBOOK_DISABLE_TELEMETRY: "1",
+  TURBO_TELEMETRY_DISABLED: "1",
+  NG_CLI_ANALYTICS: "false",
+  DOTNET_CLI_TELEMETRY_OPTOUT: "1",
+  CYPRESS_CRASH_REPORTS: "0",
+}
+
+/** `env` with telemetry off and OTLP exporters removed, so no process sends traces anywhere. */
+export function withoutTelemetry(env: Record<string, string | undefined>): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const [k, v] of Object.entries(env)) {
+    if (typeof v === "string" && !k.startsWith("OTEL_EXPORTER_OTLP_")) out[k] = v
+  }
+  return { ...out, ...NO_TELEMETRY_ENV }
+}

package/src/prompts.ts

@@ -0,0 +1,165 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs"
+import path from "node:path"
+
+import { basedOnOlder, copyState } from "./managed.ts"
+
+/**
+ * Every prompt ForgeQE's agents use lives in a markdown file: prompts/<name>.md in ForgeQE, with YAML frontmatter
+ * (name, description, used_by) and the prompt as the body. A project changes one by editing its copy in
+ * .forgeqe/prompts/ (forgeqe init puts them there), or ~/.forgeqe/prompts/ for every project. The first of those
+ * that has an edited copy wins; an unedited copy keeps following ForgeQE's built-in prompt. {{> name}} includes
+ * another prompt (resolved the same way).
+ */
+
+export const PROMPTS_DIR = path.resolve(import.meta.dir, "..", "prompts")
+const INCLUDE = /\{\{>\s*([a-z0-9-]+)\s*\}\}/g
+
+/** Folders with the project's and the user's prompts, highest precedence first (set when forgeqe.yaml is loaded). */
+let overrideDirs: { dir: string; source: string }[] = []
+
+export function setPromptDirs(dirs: { dir?: string; source: string }[]): void {
+  const seen = new Set<string>()
+  overrideDirs = dirs
+    .filter((d): d is { dir: string; source: string } => Boolean(d.dir))
+    .map((d) => ({ dir: path.resolve(d.dir), source: d.source }))
+    .filter((d) => !seen.has(d.dir) && Boolean(seen.add(d.dir)))
+}
+
+export function promptDirs(): { dir: string; source: string }[] {
+  return [...overrideDirs]
+}
+
+export type PromptSource = "built-in" | "project" | "user"
+
+export type PromptInfo = {
+  name: string
+  description: string
+  usedBy: string
+  source: PromptSource | string
+  file: string
+  /** An edited copy whose built-in prompt changed since the copy was made. */
+  outdated: boolean
+}
+
+function parse(text: string): { meta: Record<string, string>; body: string } {
+  const src = text.replace(/^/, "").replace(/\r\n/g, "\n")
+  if (!src.startsWith("---\n")) return { meta: {}, body: src.trim() }
+  const end = src.indexOf("\n---", 4)
+  if (end < 0) return { meta: {}, body: src.trim() }
+  const meta: Record<string, string> = {}
+  for (const line of src.slice(4, end).split("\n")) {
+    const m = line.match(/^([a-z_]+):\s*(.*)$/)
+    if (!m) continue
+    let v = m[2].trim()
+    if (v.startsWith('"')) {
+      try {
+        v = JSON.parse(v)
+      } catch {}
+    }
+    meta[m[1]] = v
+  }
+  return { meta, body: src.slice(end + 4).replace(/^[^\n]*\n/, "").trim() }
+}
+
+/** Where a prompt comes from: the first edited (or hand-made) copy in an override folder, else the built-in file. */
+export function promptFile(name: string): { file: string; source: string; outdated: boolean } {
+  const key = `${name}.md`
+  const builtin = path.join(PROMPTS_DIR, key)
+  for (const { dir, source } of overrideDirs) {
+    const state = copyState(dir, key)
+    if (state === "edited" || state === "own") return { file: path.join(dir, key), source, outdated: basedOnOlder(dir, key, builtin) }
+  }
+  return { file: builtin, source: "built-in", outdated: false }
+}
+
+const cache = new Map<string, { at: number; body: string }>()
+
+function body(file: string): string {
+  let at = 0
+  try {
+    at = Bun.file(file).lastModified
+  } catch {}
+  const hit = cache.get(file)
+  if (hit && hit.at === at) return hit.body
+  const b = parse(readFileSync(file, "utf8")).body
+  cache.set(file, { at, body: b })
+  return b
+}
+
+/** A prompt's text, with its includes expanded. */
+export function prompt(name: string, seen: string[] = []): string {
+  if (seen.includes(name)) throw new Error(`Prompt ${name} includes itself (${[...seen, name].join(" → ")}).`)
+  const { file } = promptFile(name)
+  if (!existsSync(file)) throw new Error(`No prompt named "${name}" (${file}).`)
+  return body(file).replace(INCLUDE, (_, inner: string) => prompt(inner, [...seen, name]))
+}
+
+/** Every prompt ForgeQE has, with where each comes from now. */
+export function listPrompts(): PromptInfo[] {
+  return readdirSync(PROMPTS_DIR)
+    .filter((f) => f.endsWith(".md") && f !== "README.md")
+    .sort()
+    .map((f) => {
+      const name = f.replace(/\.md$/, "")
+      const { meta } = parse(readFileSync(path.join(PROMPTS_DIR, f), "utf8"))
+      const where = promptFile(name)
+      return { name, description: meta.description || "", usedBy: meta.used_by || "", source: where.source, file: where.file, outdated: where.outdated }
+    })
+}
+
+/** Edited prompts based on an older built-in: worth a look after updating ForgeQE. */
+export function promptWarnings(): string[] {
+  return listPrompts()
+    .filter((p) => p.outdated)
+    .map((p) => `Your prompt ${p.name} (${p.file}) is based on an older version of ForgeQE's; forgeqe prompts diff ${p.name} shows what changed.`)
+}
+
+/** The browser engine's prompts (browser-*.md), resolved, for the engine to use instead of its own copies. */
+export function enginePrompts(): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const f of readdirSync(PROMPTS_DIR)) {
+    const name = f.replace(/\.md$/, "")
+    if (!f.endsWith(".md") || !name.startsWith("browser-") || name === "browser-extra") continue
+    out[name] = prompt(name)
+  }
+  return out
+}
+
+/** The built-in text of a prompt (without includes expanded), for comparing with an edited copy. */
+export function builtinPrompt(name: string): string {
+  return parse(readFileSync(path.join(PROMPTS_DIR, `${name}.md`), "utf8")).body
+}
+
+/** Lines of `a` and `b` that differ, as "- " (only in a) and "+ " (only in b), with a line of context around each change. */
+export function lineDiff(a: string, b: string): string[] {
+  const x = a.split("\n")
+  const y = b.split("\n")
+  const n = x.length
+  const m = y.length
+  const lcs: number[][] = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0))
+  for (let i = n - 1; i >= 0; i--) for (let j = m - 1; j >= 0; j--) lcs[i][j] = x[i] === y[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1])
+  const ops: string[] = []
+  let i = 0
+  let j = 0
+  while (i < n || j < m) {
+    if (i < n && j < m && x[i] === y[j]) {
+      ops.push(`  ${x[i]}`)
+      i++
+      j++
+    } else if (i < n && (j >= m || lcs[i + 1][j] >= lcs[i][j + 1])) ops.push(`- ${x[i++]}`)
+    else ops.push(`+ ${y[j++]}`)
+  }
+  const keep = new Set<number>()
+  ops.forEach((o, k) => {
+    if (!o.startsWith("  ")) for (const d of [-1, 0, 1]) keep.add(k + d)
+  })
+  const out: string[] = []
+  let last = -2
+  ops.forEach((o, k) => {
+    if (!keep.has(k)) return
+    if (k > last + 1 && out.length) out.push("  …")
+    out.push(o)
+    last = k
+  })
+  return out
+}