@capagents/forgeqe 0.0.0-stage → 1.0.0

package/src/run.ts

@@ -0,0 +1,243 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { createRequire } from "node:module"
+import path from "node:path"
+
+import { assertGoalUrlsAllowed, hostAllowed, normalizeHttpUrl } from "./guard.ts"
+import { missingKey } from "./llm.ts"
+import type { AgentEvent, ReplayMode, RunResult } from "./types.ts"
+import type { AppConfig } from "./config.ts"
+import { runEngine } from "./engine/bridge.ts"
+import { MOCK_ENGINE } from "./engine/mock.ts"
+import { ensureEngine } from "./engine/setup.ts"
+import { reportEnv, writeRunReport } from "./report/html.ts"
+import { logEvent } from "./sessionLog.ts"
+import { costOf } from "./usage.ts"
+import { allLogins, redactSecrets } from "./sessionLogins.ts"
+import { browserSkills, rememberChoice } from "./skills/select.ts"
+import { axeTags, DEFAULT_QUALITY, emptyReport, evaluateQuality, readA11y } from "./quality/budgets.ts"
+import { historyFile, recordQuality } from "./quality/history.ts"
+import { compareVisual, engineVisual } from "./quality/visual.ts"
+import { enginePrompts, prompt } from "./prompts.ts"
+import { knowledgeBlock, readKnowledge, relevantKnowledge } from "./knowledge.ts"
+
+export type ExecuteOptions = {
+  config: AppConfig
+  goal: string
+  url?: string
+  headed?: boolean
+  maxSteps?: number
+  outDir?: string
+  /** Overrides memory.replay from forgeqe.yaml. */
+  replay?: ReplayMode
+  /** false runs without page memory. */
+  memory?: boolean
+  /** Steps in the test case this goal came from; the agent then reports a verdict for each. */
+  caseSteps?: number
+  /** A failed or cut-off run's folder (or its name under the runs folder): replay the steps that worked there first. */
+  resumeFrom?: string
+  /** Browser skills the caller chose (empty: none); unset: the engine picks the ones the goal needs. */
+  skills?: string[]
+  /** The repository the run is for: its .forgeqe/skills count as project skills. */
+  repo?: string
+  signal?: AbortSignal
+  onEvent?: (event: AgentEvent) => void
+}
+
+/** The resume.json a failed run, or a run cut off before it finished, left in its folder. */
+export function loadResume(outRoot: string, from: string): Record<string, unknown> {
+  const dir = [path.resolve(from), path.resolve(outRoot, from)].find((d) => existsSync(path.join(d, "resume.json")))
+  if (!dir) {
+    throw new Error(
+      `No steps to resume in ${from}. Only a run that failed or was cut off part of the way leaves resume.json; run the goal without resume_from.`,
+    )
+  }
+  const data = JSON.parse(readFileSync(path.join(dir, "resume.json"), "utf8")) as Record<string, unknown>
+  if (!Array.isArray(data.steps) || !data.steps.length) throw new Error(`${path.join(dir, "resume.json")} has no steps.`)
+  return data
+}
+
+export function runDirectory(outRoot: string, explicit?: string): string {
+  if (explicit) return path.resolve(explicit)
+  const d = new Date()
+  const p = (n: number) => String(n).padStart(2, "0")
+  const stamp = `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`
+  // Created here so runs started in the same second (parallel tool calls, back-to-back monitor rounds) get their own folder.
+  mkdirSync(outRoot, { recursive: true })
+  for (let n = 1; ; n++) {
+    const dir = path.join(outRoot, n === 1 ? stamp : `${stamp}-${n}`)
+    try {
+      mkdirSync(dir)
+      return dir
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err
+    }
+  }
+}
+
+/**
+ * The bridge's hard ceiling for one engine run: the engine's own timeout covers only the agent, so browser start-up,
+ * skill choice, and replaying remembered steps get as long again plus five minutes before the run is stopped.
+ */
+export function engineDeadlineMs(timeoutSeconds: number): number {
+  return (2 * timeoutSeconds + 300) * 1000
+}
+
+/** axe-core's script, installed with ForgeQE; null when it is missing. */
+export function axeCoreScript(): string | null {
+  try {
+    const file = createRequire(import.meta.url).resolve("axe-core/axe.min.js")
+    return existsSync(file) ? file : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Judge the run's accessibility and timings against the budgets, keep them in the quality history, and mark a run that
+ * passed its steps but exceeded a budget. Without budgets nothing fails: the report and the history still have them.
+ */
+export function applyQuality(config: AppConfig, dir: string, result: RunResult, onEvent?: (e: AgentEvent) => void): void {
+  try {
+    const q = config.quality || DEFAULT_QUALITY
+    const visual = q.visual.enabled ? compareVisual(dir, q.visual, q.visual.baselineDir || path.join(path.dirname(config.memory?.dir || config.export.outDir), "visual-baselines"), q.budgets.visual) : null
+    const report = evaluateQuality(dir, q) || (visual ? emptyReport(q) : null)
+    if (!report) return
+    if (visual) {
+      report.visual = visual
+      report.budgets.visual = q.budgets.visual !== undefined || Object.values(q.visual.pages).some((p) => p.maxDiffPercent !== undefined)
+      for (const p of visual.pages.filter((x) => x.over)) report.breaches.push({ kind: "visual", page: p.url, text: `${p.diffPercent}% of the page differs from its baseline (budget ${p.limit}%)${p.resized ? `; size ${p.resized}` : ""}` })
+    }
+    result.quality = report
+    writeFileSync(path.join(dir, "quality.json"), `${JSON.stringify(report, null, 2)}\n`)
+    recordQuality(historyFile(config.export.outDir), report, readA11y(dir), path.basename(dir))
+    if (report.breaches.length) {
+      result.budgetExceeded = report.breaches.map((b) => `${shortPage(b.page)}: ${b.text}`)
+      onEvent?.({ type: "log", level: "warn", text: `Budget exceeded: ${result.budgetExceeded.join("; ")}` })
+    }
+  } catch (err) {
+    onEvent?.({ type: "log", level: "warn", text: `Accessibility and performance not judged: ${(err as Error).message}` })
+  }
+}
+
+function shortPage(url: string): string {
+  try {
+    const u = new URL(url)
+    return `${u.host}${u.pathname}`
+  } catch {
+    return url
+  }
+}
+
+export async function executeRun(opts: ExecuteOptions): Promise<{ result: RunResult; files: string[] }> {
+  const goal = redactSecrets(opts.goal.trim())
+  if (!goal) throw new Error("A goal is required. Pass --goal or type one in the shell.")
+
+  const allowed = opts.config.browser.allowedHosts
+  const blockedGoal = assertGoalUrlsAllowed(goal, allowed)
+  if (blockedGoal) throw new Error(blockedGoal)
+
+  let startUrl: string | undefined
+  const requested = opts.url || opts.config.browser.startUrl
+  if (requested) {
+    const normalized = normalizeHttpUrl(requested)
+    if (!normalized) throw new Error(`Invalid URL: ${requested}`)
+    const blocked = hostAllowed(normalized, allowed)
+    if (blocked) throw new Error(blocked)
+    startUrl = normalized
+  }
+
+  const dir = opts.outDir || runDirectory(opts.config.export.outDir)
+  const maxSteps = opts.maxSteps || opts.config.browser.maxSteps
+  const t0 = Date.now()
+  const withReport = (out: { result: RunResult; files: string[] }) => {
+    out.result.cost = costOf(out.result.usage, opts.config.llm.price)
+    applyQuality(opts.config, dir, out.result, opts.onEvent)
+    logEvent("run.done", { out_dir: dir, status: out.result.status, summary: out.result.summary, usage: out.result.usage, memory: out.result.memory, ...(out.result.skills ? { skills: out.result.skills } : {}) })
+    try {
+      out.files.push(writeRunReport(dir, out.result, reportEnv(opts.config, { url: startUrl, headed: opts.headed }), t0))
+    } catch (err) {
+      opts.onEvent?.({ type: "log", level: "warn", text: `report.html not written: ${(err as Error).message}` })
+    }
+    return out
+  }
+
+  if (opts.config.llm.provider === "mock") {
+    opts.onEvent?.({
+      type: "log",
+      level: "info",
+      text: "Mock profile: synthetic page, no browser or model. Press Tab for a live profile.",
+    })
+    const out = await runEngine({
+      python: process.execPath,
+      command: [process.execPath, MOCK_ENGINE],
+      request: { goal, outDir: dir, llm: opts.config.llm, startUrl, headed: false, maxSteps, allowedHosts: allowed },
+      signal: opts.signal,
+      onEvent: opts.onEvent,
+    })
+    return withReport(out)
+  }
+
+  const missing = missingKey(opts.config.llm)
+  if (missing) throw new Error(missing)
+  const log = (text: string) => opts.onEvent?.({ type: "log", level: "info", text })
+  const python = await ensureEngine(log)
+  // The browser agent's added instructions: forgeqe.yaml's, prompts/browser-extra.md, and the product knowledge that matches the goal.
+  const knowledge = opts.config.knowledge && opts.config.knowledge.browserMaxChars > 0 ? knowledgeBlock(relevantKnowledge(readKnowledge(opts.config.knowledge.dir), goal, opts.config.knowledge.browserMaxChars, 2)) : ""
+  const extend = [opts.config.prompts.guiderails, opts.config.prompts.stepInstruction, prompt("browser-extra"), knowledge]
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .join("\n\n")
+  const env: Record<string, string> = {}
+  const tuning: Record<string, string> = {
+    BROWSER_USE_TIMEOUT_SECONDS: String(opts.config.browser.timeoutSeconds),
+    BROWSER_USE_LOW_VISION_DETAIL: opts.config.browser.visionDetail === "high" ? "false" : "true",
+    BROWSER_USE_USE_JUDGE: opts.config.browser.judge ? "true" : "false",
+  }
+  for (const [k, v] of Object.entries(tuning)) if (!process.env[k]) env[k] = v
+  const mem = opts.config.memory
+  const memory = mem.enabled && opts.memory !== false ? { dir: mem.dir, replay: opts.replay || mem.replay } : undefined
+  const resume = opts.resumeFrom ? loadResume(opts.config.export.outDir, opts.resumeFrom) : undefined
+  if (resume && !memory) throw new Error("resume_from replays remembered steps, so it needs page memory; it is off for this run.")
+  const q = opts.config.quality || DEFAULT_QUALITY
+  const axeScript = opts.config.report.accessibility && q.engine === "axe" ? axeCoreScript() : null
+  if (opts.config.report.accessibility && q.engine === "axe" && !axeScript) opts.onEvent?.({ type: "log", level: "warn", text: "axe-core is not installed with ForgeQE: the built-in accessibility checks run instead." })
+  const axe = axeScript ? { script: axeScript, tags: axeTags(q) } : undefined
+  const skills = browserSkills(opts.config.skills, goal, opts.skills, opts.repo)
+  if (skills.unknown.length) {
+    opts.onEvent?.({ type: "log", level: "warn", text: `No browser skill named ${skills.unknown.join(", ")}; forgeqe skills list shows them.` })
+  }
+  const out = await runEngine({
+    python,
+    request: {
+      goal,
+      outDir: dir,
+      llm: opts.config.llm,
+      startUrl,
+      headed: Boolean(opts.headed) || !opts.config.browser.headless,
+      maxSteps,
+      allowedHosts: allowed,
+      extendSystemMessage: extend || undefined,
+      memory,
+      env,
+      logins: allLogins(opts.config),
+      caseSteps: opts.caseSteps,
+      screenshots: opts.config.report.screenshots,
+      accessibility: opts.config.report.accessibility,
+      network: opts.config.api?.capture !== false,
+      ...(axe ? { axe } : {}),
+      vitals: true,
+      prompts: enginePrompts(),
+      ...(engineVisual(q.visual) ? { visual: engineVisual(q.visual) } : {}),
+      overlay: opts.config.browser.overlay,
+      resume,
+      skills: skills.skills,
+      skillsPick: skills.skillsPick,
+      skillsMaxChars: skills.skillsMaxChars,
+    },
+    signal: opts.signal,
+    onEvent: opts.onEvent,
+    deadlineMs: engineDeadlineMs(opts.config.browser.timeoutSeconds),
+  })
+  rememberChoice(goal, skills.skillsPick, out.result.skills)
+  return withReport(out)
+}

package/src/sessionLog.ts

@@ -0,0 +1,216 @@
+import { spawnSync } from "node:child_process"
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs"
+import os from "node:os"
+import path from "node:path"
+
+import { forgeqeHome } from "./tools.ts"
+
+import type { AppConfig } from "./config.ts"
+import { redactSecrets } from "./sessionLogins.ts"
+import { packageVersion } from "./tui/theme.ts"
+
+/**
+ * One log file per ForgeQE session: what the user asked, ForgeQE's agent's answers and tool calls, every
+ * browser engine event and engine log line, and errors. Secrets are replaced before anything is written.
+ * `--debug` (or FORGEQE_DEBUG=1) also turns on the engine library's debug logging and keeps long values whole.
+ */
+
+const KEEP_LOGS = 30
+const CLIP = 8_000
+const CLIP_DEBUG = 200_000
+const SECRET_ENV = /(^|_)(KEY|TOKEN|SECRET|PASSWORD|PASSWD|PAT|CREDENTIALS?)(_|$)/i
+const SECRET_FIELD = /^(api_?key|password|secret|token|authorization|values|client_secret|totp_secret|totp)$/i
+const RUN_FILES = ["run.json", "steps.json", "trace.md", "resume.json", "workflow.yaml", "handoff.md", "accessibility.json", "network.json", "performance.json", "quality.json", "failure.png", "junit.xml", "heal.md"]
+
+let file: string | null = null
+let debug = false
+const extraSecrets = new Map<string, string>()
+
+export function sessionLogFile(): string | null {
+  return file
+}
+
+export function debugLogging(): boolean {
+  return debug
+}
+
+export function logsDirectory(cfg: AppConfig): string {
+  return cfg.logsDir || path.join(forgeqeHome(), "logs")
+}
+
+function stamp(d = new Date()): string {
+  const p = (n: number) => String(n).padStart(2, "0")
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`
+}
+
+/** Secret values from the environment and llms.json, longest first, with the name that replaces each. */
+function secretValues(): [string, string][] {
+  const out: [string, string][] = [...extraSecrets.entries()]
+  for (const [name, value] of Object.entries(process.env)) {
+    if (value && value.length >= 8 && SECRET_ENV.test(name)) out.push([value, `$${name}`])
+  }
+  return out.sort((a, b) => b[0].length - a[0].length)
+}
+
+/** Text with every known secret replaced: remembered login values, secret environment variables, inline API keys, tokens. */
+export function redactForLog(text: string): string {
+  let out = redactSecrets(text)
+  for (const [value, label] of secretValues()) if (out.includes(value)) out = out.split(value).join(label)
+  // Bearer tokens (Microsoft Entra ID and other JWTs) are never in the environment, so match their shape instead.
+  return out.replace(JWT, "[token]")
+}
+
+const JWT = /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g
+
+function serialize(data: unknown): string {
+  const limit = debug ? CLIP_DEBUG : CLIP
+  const json = JSON.stringify(data, (key, value) => {
+    if (key && SECRET_FIELD.test(key) && value !== null && value !== undefined && value !== "") return "[hidden]"
+    if (typeof value === "string" && value.length > limit) return `${value.slice(0, limit)}…(${value.length - limit} more characters)`
+    return value
+  })
+  return redactForLog(json ?? String(data))
+}
+
+function prune(dir: string): void {
+  const logs = readdirSync(dir)
+    .filter((f) => f.endsWith(".log"))
+    .map((f) => ({ f, t: statSync(path.join(dir, f)).mtimeMs }))
+    .sort((a, b) => b.t - a.t)
+  for (const { f } of logs.slice(KEEP_LOGS)) rmSync(path.join(dir, f), { force: true })
+}
+
+/** Opens this session's log (once per process) and writes what ForgeQE is running with. */
+export function startSessionLog(cfg: AppConfig, opts: { command: string; debug?: boolean; argv?: string[] }): string | null {
+  if (file) return file
+  debug = Boolean(opts.debug)
+  for (const p of Object.values(cfg.profiles || {})) if (p.apiKey && p.apiKey.length >= 6) extraSecrets.set(p.apiKey, "[api key from llms.json]")
+  if (cfg.llm.apiKey && cfg.llm.apiKey.length >= 6) extraSecrets.set(cfg.llm.apiKey, "[api key from llms.json]")
+  try {
+    const dir = logsDirectory(cfg)
+    mkdirSync(dir, { recursive: true })
+    const ignore = path.join(dir, ".gitignore")
+    if (!existsSync(ignore)) writeFileSync(ignore, "# ForgeQE session logs\n*\n")
+    file = path.join(dir, `${stamp()}-${opts.command}.log`)
+    writeFileSync(file, "")
+    prune(dir)
+  } catch {
+    file = null
+    return null
+  }
+  logEvent("session", {
+    forgeqe: packageVersion(),
+    command: opts.command,
+    argv: opts.argv,
+    debug,
+    os: `${os.type()} ${os.release()} ${os.arch()}`,
+    bun: process.versions.bun,
+    node: process.versions.node,
+    cwd: process.cwd(),
+    config: cfg.configPath || null,
+    profile: { name: cfg.activeProfile, provider: cfg.llm.provider, model: cfg.llm.model, code_model: cfg.code?.model },
+    browser: cfg.browser,
+    memory: { enabled: cfg.memory.enabled, replay: cfg.memory.replay, dir: cfg.memory.dir },
+    reports: cfg.export.outDir,
+    logins: cfg.logins.map((l) => ({ name: l.name, domains: l.domains })),
+  })
+  return file
+}
+
+/** One line in the session log; nothing happens when no log is open. */
+export function logEvent(kind: string, data?: unknown): void {
+  if (!file) return
+  try {
+    appendFileSync(file, `${new Date().toISOString()} ${kind}${data === undefined ? "" : ` ${serialize(data)}`}\n`)
+  } catch {
+    // logging never breaks a run
+  }
+}
+
+/** Closes the log; the next startSessionLog opens a new one. For tests. */
+export function endSessionLog(): void {
+  file = null
+  debug = false
+  extraSecrets.clear()
+}
+
+export function recentLogs(cfg: AppConfig, limit = 10): { file: string; size: number; modified: Date }[] {
+  const dir = logsDirectory(cfg)
+  if (!existsSync(dir)) return []
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".log"))
+    .map((f) => {
+      const st = statSync(path.join(dir, f))
+      return { file: path.join(dir, f), size: st.size, modified: st.mtime }
+    })
+    .sort((a, b) => b.modified.getTime() - a.modified.getTime())
+    .slice(0, limit)
+}
+
+/** Run folders a session log mentions (browser runs and suite cases). */
+export function runDirsInLog(text: string): string[] {
+  const dirs = new Set<string>()
+  for (const m of text.matchAll(/"(?:out_dir|runDir|run_dir)":"((?:[^"\\]|\\.)+)"/g)) {
+    try {
+      dirs.add(JSON.parse(`"${m[1]}"`))
+    } catch {
+      // not a path
+    }
+  }
+  return [...dirs].filter((d) => existsSync(path.join(d, "run.json")))
+}
+
+function copyRedacted(from: string, to: string): void {
+  mkdirSync(path.dirname(to), { recursive: true })
+  if (/\.(png|jpe?g|gif|webp|zip|gz)$/i.test(from)) copyFileSync(from, to)
+  else writeFileSync(to, redactForLog(readFileSync(from, "utf8")))
+}
+
+/**
+ * Everything needed to debug a session in one archive: the session log, the run folders it mentions (without
+ * step screenshots unless `shots`), the settings with secrets removed, and the versions in use.
+ */
+export function bundleLogs(cfg: AppConfig, opts: { log?: string; shots?: boolean } = {}): { archive: string; log: string; runs: number } {
+  const log = opts.log || file || recentLogs(cfg, 1)[0]?.file
+  if (!log || !existsSync(log)) throw new Error(`No session log yet in ${logsDirectory(cfg)}. Run forgeqe once, then try again.`)
+  const dir = logsDirectory(cfg)
+  const name = `forgeqe-debug-${stamp()}`
+  const staging = path.join(dir, name)
+  mkdirSync(staging, { recursive: true })
+  copyRedacted(log, path.join(staging, path.basename(log)))
+
+  const text = readFileSync(log, "utf8")
+  const runs = runDirsInLog(text)
+  for (const run of runs) {
+    const target = path.join(staging, "runs", path.basename(path.dirname(run)) + "-" + path.basename(run))
+    const files = opts.shots ? walk(run) : RUN_FILES.map((f) => path.join(run, f)).filter((f) => existsSync(f))
+    for (const f of files) copyRedacted(f, path.join(target, path.relative(run, f)))
+  }
+
+  if (cfg.configPath && existsSync(cfg.configPath)) copyRedacted(cfg.configPath, path.join(staging, "forgeqe.yaml"))
+  const profiles = Object.fromEntries(Object.entries(cfg.profiles || {}).map(([k, p]) => [k, { ...p, apiKey: p.apiKey ? "[hidden]" : undefined }]))
+  writeFileSync(path.join(staging, "profiles.json"), redactForLog(JSON.stringify(profiles, null, 2)))
+  writeFileSync(
+    path.join(staging, "environment.txt"),
+    [
+      `forgeqe ${packageVersion()}`,
+      `os ${os.type()} ${os.release()} ${os.arch()}`,
+      `bun ${process.versions.bun || "-"}  node ${process.versions.node}`,
+      `config ${cfg.configPath || "(none)"}`,
+      `profile ${cfg.activeProfile} ${cfg.llm.provider}/${cfg.llm.model}`,
+      `runs ${runs.length}`,
+    ].join("\n") + "\n",
+  )
+
+  const archive = `${staging}.tar.gz`
+  const tar = spawnSync("tar", ["-czf", archive, "-C", dir, name], { stdio: "ignore" })
+  if (tar.status === 0 && existsSync(archive)) {
+    rmSync(staging, { recursive: true, force: true })
+    return { archive, log, runs: runs.length }
+  }
+  return { archive: staging, log, runs: runs.length }
+}
+
+function walk(dir: string): string[] {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((e) => (e.isDirectory() ? walk(path.join(dir, e.name)) : [path.join(dir, e.name)]))
+}

package/src/sessionLogins.ts

@@ -0,0 +1,94 @@
+import { rmSync } from "node:fs"
+import os from "node:os"
+import path from "node:path"
+
+import { forgeqeHome } from "./tools.ts"
+
+import { loginDomain, type AppConfig, type LoginConfig } from "./config.ts"
+
+/**
+ * Logins remembered for this ForgeQE process from credentials the user gave in a message or a test case.
+ * The values stay in memory: they reach the engine over its stdin and become placeholders the browser model never
+ * sees. The signed-in browser session is saved like any saved login's, so later runs start signed in.
+ */
+export type SessionLogin = LoginConfig & { values: { username?: string; password?: string; totp?: string } }
+
+const store = new Map<string, SessionLogin>()
+
+const envName = (name: string, field: string) => `FORGEQE_${name.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_${field}`
+
+/** An engine domain pattern (scheme and host) from a URL, a host, or a wildcard host such as *.okta.com. */
+function domainOf(raw: string): string {
+  const s = raw.trim()
+  const withScheme = /^[a-z]+:\/\//i.test(s) ? s : `https://${s}`
+  if (!withScheme.includes("*")) return loginDomain(withScheme)
+  const m = /^([a-z]+:\/\/)([^/:?#]+)/i.exec(withScheme)
+  if (!m) throw new Error(`Not a site: ${raw}`)
+  return `${m[1]}${m[2]}`
+}
+
+export function rememberLogin(
+  cfg: AppConfig,
+  input: { name: string; url?: string; domains?: string[]; username?: string; password?: string; totp?: string },
+): SessionLogin {
+  const name = input.name.trim().replace(/[^A-Za-z0-9_-]/g, "_")
+  if (!name) throw new Error("A login needs a name.")
+  if (!input.username && !input.password && !input.totp) throw new Error("Give the username, the password, or both.")
+  const domains = [...new Set([...(input.url ? [input.url] : []), ...(input.domains || [])].filter(Boolean).map(domainOf))]
+  if (!domains.length) throw new Error("Give the site's url, and the sign-in domains (such as login.microsoftonline.com) when sign-in happens elsewhere.")
+  const dir = cfg.sessionsDir || path.join(forgeqeHome(), "sessions")
+  const values = { ...(input.username ? { username: input.username } : {}), ...(input.password ? { password: input.password } : {}), ...(input.totp ? { totp: input.totp } : {}) }
+  const login: SessionLogin = {
+    name,
+    domains,
+    ...(input.url ? { url: input.url } : {}),
+    ...(values.username ? { usernameEnv: envName(name, "USERNAME") } : {}),
+    ...(values.password ? { passwordEnv: envName(name, "PASSWORD") } : {}),
+    ...(values.totp ? { totpEnv: envName(name, "TOTP") } : {}),
+    sessionFile: path.join(dir, `${name}.json`),
+    values,
+  }
+  store.set(name, login)
+  return login
+}
+
+export function sessionLogins(): SessionLogin[] {
+  return [...store.values()]
+}
+
+/** Forget remembered credentials and their saved sessions: one login by name, or all of them when no name is given. */
+export function forgetSessionLogins(name?: string): string[] {
+  const names = name === undefined ? [...store.keys()] : store.has(name) ? [name] : []
+  for (const n of names) {
+    const file = store.get(n)?.sessionFile
+    if (file) rmSync(file, { force: true })
+    store.delete(n)
+  }
+  return names
+}
+
+/** forgeqe.yaml's logins plus this session's; a remembered login replaces a configured one with the same name. */
+export function allLogins(cfg: AppConfig): LoginConfig[] {
+  return [...cfg.logins.filter((l) => !store.has(l.name)), ...store.values()]
+}
+
+/** The remembered values under their env names, for ForgeQE's own runs of tests that read them from the environment. */
+export function sessionLoginEnv(): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const l of store.values()) {
+    if (l.usernameEnv && l.values.username) out[l.usernameEnv] = l.values.username
+    if (l.passwordEnv && l.values.password) out[l.passwordEnv] = l.values.password
+    if (l.totpEnv && l.values.totp) out[l.totpEnv] = l.values.totp
+  }
+  return out
+}
+
+/** Every remembered value in `text` replaced by a mention of its login, so goals and reports never carry them. */
+export function redactSecrets(text: string): string {
+  let out = text
+  const pairs = [...store.values()].flatMap((l) =>
+    (Object.entries(l.values) as [string, string][]).filter(([field, v]) => field !== "username" && v.length >= 4).map(([field, v]) => [v, `(the ${field} of saved login ${l.name})`] as const),
+  )
+  for (const [value, label] of pairs.sort((a, b) => b[0].length - a[0].length)) out = out.split(value).join(label)
+  return out
+}