@capagents/forgeqe 0.0.0-stage → 1.0.1

package/src/mcp/commands.ts

@@ -0,0 +1,421 @@
+import { existsSync, readFileSync } from "node:fs"
+import path from "node:path"
+
+import { docsContents, readDocs } from "../capabilities/docs.ts"
+import { noAgentModel } from "../llm.ts"
+import { latestRunDir } from "../code/index.ts"
+import { runCodeAgent } from "../code/loop.ts"
+import { parseDuration, reloadLogins, replayMode, type AppConfig } from "../config.ts"
+import { engineDoctor, ensureEngine } from "../engine/setup.ts"
+import { runHeal } from "../heal/loop.ts"
+import { healCard } from "../heal/report.ts"
+import { initWorkspace } from "../init.ts"
+import { clearLogins, describeLogins, signIn } from "../logins.ts"
+import { forgetSessionLogins, rememberLogin, sessionLogins } from "../sessionLogins.ts"
+import { backgroundMonitors, startBackgroundMonitor, stopBackgroundMonitors } from "../monitor/background.ts"
+import { roundCard, runMonitor, sendTestAlert, type RoundResult } from "../monitor/run.ts"
+import { readState } from "../monitor/state.ts"
+import { findSkill, loadSkills, skillBody, type Skill, type SkillAgent } from "../skills/registry.ts"
+import { ignoredNote, newSkill } from "../skills/scaffold.ts"
+import { buildCodeSummary, codeCard } from "../summary.ts"
+import { externalMcp } from "./external.ts"
+import type { McpTool, ToolContext } from "./tools.ts"
+
+const clip = (s: string | undefined, n: number) => {
+  const t = (s || "").trim()
+  return t.length <= n ? t : `…${t.slice(-(n - 1))}`
+}
+
+/** Marks a browser_run that was a task (a lookup in a tool), not a flow to automate; write_test refuses such runs. */
+export const TASK_FILE = "task.json"
+
+const inCwd = (ctx: ToolContext, p: unknown) => (p ? path.resolve(ctx.cwd, String(p)) : ctx.cwd)
+
+function readJson(file: string): unknown {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"))
+  } catch {
+    return null
+  }
+}
+
+function needsModel(cfg: AppConfig, what: string) {
+  const why = noAgentModel(cfg.llm, cfg.code.model, what)
+  if (why) throw new Error(why)
+}
+
+function hhmm(d: Date | string): string {
+  const t = new Date(d)
+  return `${String(t.getHours()).padStart(2, "0")}:${String(t.getMinutes()).padStart(2, "0")}`
+}
+
+function every(ms: number): string {
+  return ms % 3_600_000 === 0 ? `${ms / 3_600_000}h` : ms % 60_000 === 0 ? `${ms / 60_000}m` : `${Math.round(ms / 1000)}s`
+}
+
+function channels(cfg: AppConfig): string[] {
+  const a = cfg.monitor.alerts
+  return [a.teams ? `Teams (${a.teams.webhookEnv})` : "", a.email ? `email to ${a.email.to.join(", ")}` : ""].filter(Boolean)
+}
+
+/** monitor: from forgeqe.yaml with the tool's every/replay, and check references resolved from the working directory. */
+function monitorSetup(args: Record<string, any>, ctx: ToolContext): { cfg: AppConfig; checks: string[] } {
+  const m = { ...ctx.config.monitor }
+  if (args.every) {
+    m.everyMs = parseDuration(args.every, "every")
+    if (m.everyMs < 10_000) throw new Error("every must be at least 10s.")
+  }
+  if (args.replay) m.replay = replayMode(args.replay)
+  const refs: string[] = Array.isArray(args.checks) && args.checks.length ? args.checks.map(String) : m.checks
+  if (!refs.length) throw new Error("No checks: pass checks, or set monitor.checks in forgeqe.yaml.")
+  const checks = refs.map((r) => (existsSync(path.resolve(ctx.cwd, r)) ? path.resolve(ctx.cwd, r) : r))
+  return { cfg: { ...ctx.config, monitor: m }, checks }
+}
+
+function roundSummary(r: RoundResult) {
+  return {
+    passed: r.suite ? r.suite.results.filter((x) => x.status === "passed").length : 0,
+    total: r.suite?.results.length ?? 0,
+    error: r.error,
+    stopped: r.stopped || undefined,
+    failing: r.failing.map((f) => ({ id: f.id, title: f.title, since: f.since, rounds: f.failures, alerted: Boolean(f.alertedAt), summary: clip(f.summary, 300) })),
+    alerts: r.alerts.map((a) => ({ kind: a.kind, id: a.id, title: a.title })),
+    sent: r.sent,
+    report: r.suite?.files.html,
+  }
+}
+
+/** The CLI's commands as tools, so ForgeQE's agent (and any MCP client) can do everything the CLI does. */
+export const COMMAND_TOOLS: McpTool[] = [
+  {
+    name: "write_test",
+    description:
+      "Turn a passed browser run into a test in a repository with ForgeQE's coding agent (forgeqe code): it studies the repository's framework, page objects, fixtures, and helpers, writes the test to fit, and ForgeQE runs the test itself until it passes in a browser and a read-only reviewer approves it against the goal, or the attempts run out. Returns the test file, the command that runs only that test, whether ForgeQE's own run passed, the browser it ran in, and the review. Takes minutes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        run_dir: { type: "string", description: "Run folder from browser_run or run_test_cases (default: the latest run)" },
+        repo: { type: "string", description: "Repository to write the test in, relative to the working directory (default: the working directory)" },
+      },
+    },
+    async run(args, ctx) {
+      const cfg = ctx.config
+      needsModel(cfg, "the coding agent")
+      const runDir = args.run_dir ? path.resolve(ctx.cwd, String(args.run_dir)) : latestRunDir(cfg.export.outDir)
+      if (!runDir || !existsSync(runDir)) throw new Error("No run found. Run a goal first.")
+      const task = readJson(path.join(runDir, TASK_FILE)) as { reason?: string } | null
+      if (task) throw new Error(`No test is written for this run: ${task.reason || "it was a task, not a flow to test"}.`)
+      const t0 = Date.now()
+      const repo = inCwd(ctx, args.repo)
+      const goal = (readJson(path.join(runDir, "run.json")) as { goal?: string } | null)?.goal || ""
+      ctx.emit?.({ type: "code-start", runDir, repo, goal })
+      let r
+      try {
+        r = await runCodeAgent({
+          config: cfg,
+          repo,
+          runDir,
+          signal: ctx.signal,
+          onEvent: (event) => ctx.emit?.({ type: "agent", event }),
+          open: ctx.openSession as never,
+          runTest: ctx.runTest,
+        })
+      } catch (err) {
+        ctx.emit?.({ type: "code-done", error: (err as Error).message, ms: Date.now() - t0 })
+        throw err
+      }
+      ctx.emit?.({ type: "code-done", result: r, ms: Date.now() - t0 })
+      ctx.emit?.({ type: "card", card: codeCard(buildCodeSummary(r, Date.now() - t0)) })
+      return {
+        status: r.status,
+        test_file: r.testFile,
+        command: r.command,
+        attempts: `${r.attempts}/${r.maxAttempts}`,
+        reused: r.reused,
+        changed: r.changed,
+        notes: r.notes || undefined,
+        browsers: r.browsers,
+        review: r.review,
+        output: r.status === "passed" ? undefined : clip(r.output, 4000),
+      }
+    },
+  },
+  {
+    name: "heal_tests",
+    description:
+      "Fix a repository's broken tests (forgeqe heal): ForgeQE runs the test command; for each failing test a healing agent re-runs its flow in the real browser, updates the test's steps and locators when the flow still works (the app changed), or reports an app bug and leaves the test alone when the browser fails at the same step. It never deletes, skips, or loosens a test. ForgeQE re-runs every healed test and then the whole command itself. Returns each test's verdict, the files changed, and heal.md. Takes minutes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        command: { type: "string", description: "Command that runs the tests, e.g. npx playwright test tests/checkout (default: code.test_command, or the healing agent finds it)" },
+        repo: { type: "string", description: "Repository, relative to the working directory (default: the working directory)" },
+      },
+    },
+    async run(args, ctx) {
+      needsModel(ctx.config, "the healing agent")
+      const r = await runHeal({
+        config: ctx.config,
+        repo: inCwd(ctx, args.repo),
+        command: args.command ? String(args.command) : undefined,
+        headed: ctx.headed,
+        maxSteps: ctx.maxSteps,
+        url: ctx.url,
+        signal: ctx.signal,
+        onEvent: (event) => ctx.emit?.({ type: "agent", event }),
+        onTool: (e) => ctx.emit?.(e),
+        open: ctx.openSession as never,
+        execute: ctx.execute,
+      })
+      ctx.emit?.({ type: "card", card: healCard(r, ctx.cwd) })
+      return {
+        status: r.status,
+        command: r.command,
+        tests: r.tests.map((t) => ({ name: t.name, file: t.file, verdict: t.status, confirmed_by_forgeqe: Boolean(t.verified), reason: t.reason })),
+        changed: r.changed,
+        notes: r.notes || undefined,
+        report: path.join(r.dir, "heal.md"),
+        output: r.status === "failed" ? clip(r.after?.output, 4000) : undefined,
+      }
+    },
+  },
+  {
+    name: "monitor",
+    description:
+      "Scheduled checks with Teams and email alerts (forgeqe monitor; settings under monitor: in forgeqe.yaml). round: run the checks once now, update which are failing, and alert on what changed. start: run rounds every interval in the background while this ForgeQE session stays open; each round is shown as it finishes. stop: stop background monitors. status: which checks are failing and since when, and what runs in the background. test_alerts: send a sample alert to every channel.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["round", "start", "stop", "status", "test_alerts"] },
+        checks: {
+          type: "array",
+          items: { type: "string" },
+          description: "Test case sources as forgeqe suite takes them: files or folders, jira:SHOP-1,SHOP-2, jira:jql=<query>, ado:plan=12/suite=34, xray:plan=SHOP-100, testrail:run=45, zephyr:cycle=SHOP-R5, qtest:cycle=88 (default: monitor.checks)",
+        },
+        every: { type: "string", description: "Interval between rounds, e.g. 5m, 15m, 1h (default: monitor.every)" },
+        replay: { type: "string", enum: ["verify", "trust", "off"], description: "Page memory replay (default: monitor.replay)" },
+      },
+      required: ["action"],
+    },
+    async run(args, ctx) {
+      const action = String(args.action)
+      const outDir = ctx.config.monitor.outDir
+      if (action === "stop") {
+        const stopped = await stopBackgroundMonitors()
+        for (const m of stopped) ctx.emit?.({ type: "info", text: `Monitor stopped after ${m.rounds} round${m.rounds === 1 ? "" : "s"}: ${m.checks.join(" ")}`, ok: true })
+        return { stopped: stopped.map((m) => ({ checks: m.checks, rounds: m.rounds, out_dir: m.outDir })) }
+      }
+      if (action === "status") {
+        const state = readState(outDir)
+        return {
+          settings: { checks: ctx.config.monitor.checks, every: every(ctx.config.monitor.everyMs), fail_after: ctx.config.monitor.failAfter, alerts: channels(ctx.config), out_dir: outDir },
+          checks: Object.entries(state.checks).map(([id, s]) => ({ id, title: s.title, status: s.status, since: s.since, failing_rounds: s.failures || undefined, alerted_at: s.alertedAt })),
+          last_round: state.updatedAt,
+          background: backgroundMonitors().map((m) => ({
+            checks: m.checks,
+            every: every(m.everyMs),
+            started: m.startedAt.toISOString(),
+            rounds: m.rounds,
+            next_round: m.nextAt?.toISOString(),
+            last: m.last ? roundSummary(m.last) : undefined,
+          })),
+        }
+      }
+      if (action === "test_alerts") {
+        if (!channels(ctx.config).length) throw new Error("No alert channels are set up. Add monitor.alerts.teams or monitor.alerts.email to forgeqe.yaml.")
+        const sent = await sendTestAlert(ctx.config)
+        for (const s of sent) ctx.emit?.({ type: "info", text: s.ok ? `Test alert sent to ${s.channel === "teams" ? "Teams" : "email"}` : `${s.channel === "teams" ? "Teams" : "Email"}: ${s.error}`, ok: s.ok })
+        return { sent }
+      }
+      const { cfg, checks } = monitorSetup(args, ctx)
+      if (action === "start") {
+        if (ctx.session !== "shell" && ctx.session !== "server") {
+          throw new Error("A background monitor would stop when this command exits. Use forgeqe monitor (in a service or tmux), or forgeqe monitor --once from cron or a scheduled pipeline.")
+        }
+        startBackgroundMonitor({ config: cfg, checks, headed: ctx.headed, url: ctx.url, execute: ctx.execute, cwd: ctx.cwd, onCard: (card) => ctx.emit?.({ type: "card", card }) })
+        ctx.emit?.({ type: "info", text: `Monitoring ${checks.map((c) => path.relative(ctx.cwd, c) || c).join(" ")} every ${every(cfg.monitor.everyMs)} until ForgeQE closes`, ok: true })
+        return { started: true, checks, every: every(cfg.monitor.everyMs), replay: cfg.monitor.replay, alerts: channels(cfg), out_dir: outDir, note: "The first round runs now. The monitor stops when this ForgeQE session closes." }
+      }
+      if (action !== "round") throw new Error(`Unknown action "${action}".`)
+      const bg = backgroundMonitors().find((m) => m.outDir === outDir)
+      if (bg) throw new Error(`A background monitor is running in ${outDir}${bg.nextAt ? `; its next round is at ${hhmm(bg.nextAt)}` : ""}. Use status, or stop it first.`)
+      let result: RoundResult | undefined
+      await runMonitor({
+        config: cfg,
+        checks,
+        once: true,
+        headed: ctx.headed,
+        url: ctx.url,
+        signal: ctx.signal,
+        execute: ctx.execute,
+        onEvent: (event) => ctx.emit?.({ type: "suite-event", event }),
+        onRound: (r) => {
+          result = r
+        },
+      })
+      ctx.emit?.({ type: "card", card: roundCard(result!, undefined, ctx.cwd) })
+      return roundSummary(result!)
+    },
+  },
+  {
+    name: "logins",
+    description:
+      "Saved logins. remember: credentials the user gave in a message or a test case become a login for this ForgeQE session; the browser agent signs in with the exact values (typed from placeholders, never shown to the browser model or written to reports), the signed-in session is saved, and later runs start signed in. Call it before the first browser run or run_test_cases that needs them, and never put the credentials in a goal. list: logins from forgeqe.yaml and this session, with their sites and saved sessions. sign_in: open a visible browser where the user signs in by hand (single sign-on, captcha, security key) and ForgeQE saves the session; the user confirms in ForgeQE when done. clear: forget a saved session (and a remembered login's credentials).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["list", "remember", "sign_in", "clear"] },
+        name: { type: "string", description: "Login name: from forgeqe.yaml, or a short name for remember such as dynamics" },
+        url: { type: "string", description: "remember: the site the user signs in to. sign_in: page to open instead of the login's url" },
+        domains: {
+          type: "array",
+          items: { type: "string" },
+          description: "remember: every other host the sign-in happens on, e.g. login.microsoftonline.com for Microsoft sign-in, accounts.google.com, *.okta.com",
+        },
+        username: { type: "string", description: "remember: exactly as given, without surrounding quotes or the sentence's punctuation" },
+        password: { type: "string", description: "remember: exactly as given, without surrounding quotes or the sentence's punctuation" },
+        totp_secret: { type: "string", description: "remember: an authenticator secret (base32), when given" },
+        all: { type: "boolean", description: "clear: every saved session" },
+      },
+      required: ["action"],
+    },
+    async run(args, ctx) {
+      const action = String(args.action)
+      if (action === "remember") {
+        if (!args.name) throw new Error("remember needs a name.")
+        const login = rememberLogin(ctx.config, {
+          name: String(args.name),
+          url: args.url ? String(args.url) : undefined,
+          domains: Array.isArray(args.domains) ? args.domains.map(String) : undefined,
+          username: args.username ? String(args.username) : undefined,
+          password: args.password ? String(args.password) : undefined,
+          totp: args.totp_secret ? String(args.totp_secret) : undefined,
+        })
+        const text = `Remembered login ${login.name} for ${login.domains.join(", ")} for this session`
+        ctx.emit?.({ type: "info", text, ok: true })
+        return {
+          remembered: login.name,
+          domains: login.domains,
+          has: Object.keys(login.values),
+          session_file: login.sessionFile,
+          next_step: `Browser goals for this site say "sign in with the saved login ${login.name}" and never contain the credentials; the browser agent types them itself. Later runs reuse the signed-in session.`,
+          env_names_for_tests: [login.usernameEnv, login.passwordEnv, login.totpEnv].filter(Boolean),
+        }
+      }
+      reloadLogins(ctx.config)
+      if (action === "list") {
+        const remembered = sessionLogins()
+        const extra = remembered.map((l) => `${l.name}  ${l.domains.join(", ")}\n  credentials  remembered for this session (${Object.keys(l.values).join(", ")})\n  session      ${l.sessionFile}`)
+        const base = ctx.config.logins.length || !remembered.length ? describeLogins(ctx.config) : ""
+        return [base, ...extra].filter(Boolean).join("\n\n")
+      }
+      if (action === "clear") {
+        const forgotten = forgetSessionLogins(args.all === true ? undefined : args.name ? String(args.name) : "")
+        const configured = args.all === true || ctx.config.logins.some((l) => l.name === args.name)
+        const cleared = configured || !forgotten.length ? clearLogins(ctx.config, args.name ? String(args.name) : undefined, args.all === true) : ""
+        const text = [cleared, forgotten.length ? `Forgot the remembered credentials for ${forgotten.join(", ")}.` : ""].filter(Boolean).join(" ")
+        ctx.emit?.({ type: "info", text, ok: true })
+        return text
+      }
+      if (action !== "sign_in") throw new Error(`Unknown action "${action}".`)
+      const name = args.name ? String(args.name) : undefined
+      if (!ctx.waitForUser) throw new Error(`Signing in by hand needs someone at ForgeQE's terminal: run forgeqe login ${name || "<name>"}.`)
+      const r = await signIn(ctx.config, name, {
+        url: args.url ? String(args.url) : undefined,
+        signal: ctx.signal,
+        log: (text) => ctx.emit?.({ type: "info", text }),
+        wait: ctx.waitForUser,
+      })
+      ctx.emit?.({ type: "info", text: r.text.split("\n")[0], ok: r.status === "saved" })
+      return r
+    },
+  },
+  {
+    name: "forgeqe_setup",
+    description:
+      "ForgeQE's own setup. profiles: the model profiles in llms.json and which is active. mcp_servers: the MCP servers ForgeQE's settings give its agent, and why any are skipped. docs: ForgeQE's documentation (README and HOW_TO_USE): without sections, its contents (every section's id and heading); with sections, those sections' exact text, and a top-level section also lists its subsections' ids. Read the contents, pick the sections a question needs, then read them; use it to answer how ForgeQE works or is configured. install_engine: install or repair the browser engine (Python, its libraries, Chrome); force reinstalls. init: create forgeqe.yaml and llms.json in a folder, with editable copies of the agents' prompts (.forgeqe/prompts), skills (.forgeqe/skills), and product knowledge templates (.forgeqe/knowledge). skills: list the skills each agent can use (op list), read one (op show), or create one in .forgeqe/skills (op new, only when the user asks for a skill).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["profiles", "mcp_servers", "docs", "install_engine", "init", "skills"] },
+        op: { type: "string", enum: ["list", "show", "new"], description: "skills: what to do (default list)" },
+        name: { type: "string", description: "skills show/new: the skill's name, lowercase words joined by hyphens, e.g. dynamics-date-picker" },
+        description: { type: "string", description: "skills new: when the skill applies (repository, framework, site, or task), one or two sentences; agents choose skills by it" },
+        agents: { type: "array", items: { type: "string", enum: ["forgeqe", "scribe", "browser"] }, description: "skills new: who uses it: scribe for test-writing conventions, browser for how to drive a site or widget, forgeqe for request workflows (default forgeqe and scribe)" },
+        body: { type: "string", description: "skills new: the instructions, as Markdown: short imperative rules, concrete names, paths, and commands" },
+        user: { type: "boolean", description: "skills new: save in ~/.forgeqe/skills for every project instead of this project's .forgeqe/skills" },
+        sections: { type: "array", items: { type: "string" }, description: "docs: section ids from the contents, e.g. HOW_TO_USE.md#api-and-contract-tests" },
+        force: { type: "boolean", description: "install_engine: reinstall. init: overwrite existing files" },
+        dir: { type: "string", description: "init: folder, relative to the working directory (default: the working directory)" },
+        profile: { type: "string", description: "init: active profile to write (default: the llms.json default)" },
+      },
+      required: ["action"],
+    },
+    async run(args, ctx) {
+      const cfg = ctx.config
+      switch (String(args.action)) {
+        case "profiles":
+          return {
+            active: cfg.activeProfile,
+            config: cfg.configPath,
+            profiles: Object.entries(cfg.profiles).map(([name, p]) => ({ name, provider: p.provider, model: p.deployment || p.model, active: name === cfg.activeProfile })),
+            note: "The user switches profiles with Tab or /profile in the shell, or --profile.",
+          }
+        case "mcp_servers": {
+          const { servers, skipped } = externalMcp(cfg)
+          return {
+            servers: servers.map((s) => {
+              const c = s.config as { type: string; command?: string[]; url?: string }
+              return { name: s.name, label: s.label, runs: c.type === "local" ? c.command?.join(" ") : c.url }
+            }),
+            skipped: skipped.map((s) => ({ label: s.label, why: s.why })),
+          }
+        }
+        case "docs":
+          return Array.isArray(args.sections) && args.sections.length ? readDocs(args.sections.map(String)) : { contents: docsContents() }
+        case "install_engine": {
+          const python = await ensureEngine((text) => ctx.emit?.({ type: "info", text }), { force: args.force === true })
+          const doc = engineDoctor(python)
+          if (!doc.browser_use) throw new Error(`The engine check failed for ${python}: ${doc.error}`)
+          ctx.emit?.({ type: "info", text: `Engine ready (${doc.browser_use})`, ok: true })
+          return { python: `${python} (${doc.python})`, engine: doc.browser_use, browser: doc.executable_path || doc.channel }
+        }
+        case "init": {
+          const dir = inCwd(ctx, args.dir)
+          const r = initWorkspace(dir, { force: args.force === true, profile: args.profile ? String(args.profile) : undefined })
+          for (const f of r.created) ctx.emit?.({ type: "info", text: `created ${f}`, ok: true })
+          return { dir, created: r.created, notes: r.notes }
+        }
+        case "skills": {
+          const reg = loadSkills(cfg.skills, ctx.cwd)
+          const op = args.op ? String(args.op) : "list"
+          if (op === "list") {
+            if (!cfg.skills.enabled) return { enabled: false, note: "Skills are turned off in forgeqe.yaml (skills: false)." }
+            const row = (s: Skill) => ({ name: s.name, description: s.description, agents: s.agents, source: s.source, ...(s.overrides ? { replaces: s.overrides } : {}) })
+            return {
+              skills: reg.skills.map(row),
+              disabled: reg.disabled.map((s) => s.name),
+              problems: reg.problems,
+              folders: { project: cfg.skills.projectDir, user: cfg.skills.userDir },
+            }
+          }
+          const name = String(args.name || "").trim()
+          if (!name) throw new Error(`skills ${op} needs a name.`)
+          if (op === "show") {
+            const skill = findSkill(reg, name)
+            if (!skill) throw new Error(`No skill named "${name}". Skills: ${reg.skills.map((s) => s.name).join(", ") || "none"}.`)
+            return { name, description: skill.description, agents: skill.agents, source: skill.source, file: skill.file, disabled: reg.disabled.includes(skill), instructions: skillBody(skill) }
+          }
+          if (op !== "new") throw new Error(`Unknown skills op "${op}".`)
+          const root = args.user === true ? cfg.skills.userDir : cfg.skills.projectDir
+          const agents = Array.isArray(args.agents) ? args.agents.map(String) : []
+          const file = newSkill(root, { name, description: String(args.description || ""), agents: agents as SkillAgent[], body: args.body ? String(args.body) : undefined })
+          ctx.emit?.({ type: "info", text: `created ${file}`, ok: true })
+          const ignored = args.user === true ? null : ignoredNote(file)
+          return { file, note: `Agents pick it up in their next session (a new ForgeQE session, or the next run or test).${ignored ? ` ${ignored}` : ""}` }
+        }
+        default:
+          throw new Error(`Unknown action "${String(args.action)}".`)
+      }
+    },
+  },
+]

package/src/mcp/exploretools.ts

@@ -0,0 +1,129 @@
+import path from "node:path"
+
+import type { Card } from "../card.ts"
+import { planCharters, type Charter } from "../explore/charters.ts"
+import { exploreCharters, explorationCard, fileConfirmed, proposedCases, saveExploration } from "../explore/run.ts"
+import { readStory } from "../explore/story.ts"
+import { allLogins } from "../sessionLogins.ts"
+import { addUsage } from "../usage.ts"
+import type { McpTool } from "./tools.ts"
+
+const MAX_CHARTERS = 12
+const charters_ = (n: number) => `${n} exploratory charter${n === 1 ? "" : "s"}`
+
+export function planCard(storyLabel: string, charters: Charter[], notes?: string): Card {
+  const body: string[] = []
+  for (const c of charters) {
+    body.push(`▸ ${c.id} ${c.title}  · ${c.category.replace("_", " ")}${c.role ? ` · as ${c.role}` : ""}${c.changesData ? " · changes data" : ""}`)
+    body.push(`    ${c.mission}`)
+    c.steps.forEach((s, i) => body.push(`    ${i + 1}. ${s.action}${s.data ? ` (${s.data})` : ""} → ${s.expected}`))
+  }
+  if (notes) body.push("", notes)
+  return { status: "info", title: `${charters_(charters.length)} for ${storyLabel}`, body }
+}
+
+/** Exploratory testing of a story. */
+export const EXPLORE_TOOLS: McpTool[] = [
+  {
+    name: "explore_story",
+    description:
+      "Exploratory testing of a user story in real browsers, beyond its scripted test cases. Reads the story (Azure DevOps or Jira: description, acceptance criteria, feature and epic, the test cases that already script it; or the story's text), plans charters (other paths and data, edge cases, invalid input, boundaries, role differences, refresh/back/double submit, what must not happen), shows them and asks before running, then runs each charter in the browser (as its role's saved login) and judges each expected result on the page. A possible defect runs a second time and counts only when it happens again. Returns confirmed defects, observations (not reproduced, browser errors, what the agent noticed), and proposed test cases; files bugs for confirmed defects only, after the user agrees. Takes several minutes: one browser run per charter.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        story: { type: "string", description: "The story: ado:123, an Azure DevOps or Jira link, a Jira key (SHOP-12), or the story's text with its acceptance criteria" },
+        url: { type: "string", description: "The page where the feature starts" },
+        charters: { type: "integer", description: `How many charters (default 6, at most ${MAX_CHARTERS}): each is one browser run, two for a possible defect` },
+        roles: { type: "array", items: { type: "string" }, description: "Saved logins (logins: in forgeqe.yaml) to compare as roles. Default: every saved login when there are two or more" },
+        focus: { type: "string", description: "What to concentrate on, when the user says (e.g. 'validation of the address form', 'what a viewer can do')" },
+        file_bugs: { type: "boolean", description: "Where nobody can be asked: file bugs for confirmed defects without asking" },
+      },
+      required: ["story"],
+    },
+    async run(args, ctx) {
+      const emit = ctx.emit || (() => {})
+      const ref = String(args.story || "").trim()
+      if (!ref) throw new Error("story is required.")
+      const story = await readStory(ctx.config, ref)
+      const label = story.id === "story" ? `"${story.title}"` : `${story.id} ${story.title}`
+      emit({ type: "info", text: `Story ${label}: ${story.acceptance ? "acceptance criteria read" : "no acceptance criteria"}, ${story.scripted.length} scripted test case${story.scripted.length === 1 ? "" : "s"}${story.parents.length ? `, under ${story.parents.map((p) => p.id).join(" > ")}` : ""}` })
+      for (const e of story.errors) emit({ type: "info", text: `Not read: ${e}`, ok: false })
+      const logins = allLogins(ctx.config).map((l) => l.name)
+      const roles = (Array.isArray(args.roles) ? args.roles.map(String) : logins.length >= 2 ? logins : []).filter((r) => logins.includes(r))
+      const count = Math.max(1, Math.min(MAX_CHARTERS, Number(args.charters) || 6))
+      const url = args.url ? String(args.url) : ctx.url
+      if (args.focus) story.description = `${story.description}\n\nFocus of this session: ${String(args.focus)}`.trim()
+      const plan = await planCharters({ config: ctx.config, story, count, roles, url, cwd: ctx.cwd, signal: ctx.signal, onEvent: (event) => emit({ type: "agent", event }), open: ctx.openSession })
+      emit({ type: "card", card: planCard(label, plan.charters, plan.notes) })
+      let charters = plan.charters
+      if (ctx.ask) {
+        const writes = charters.filter((c) => c.changesData).length
+        const answer = await ctx.ask({
+          title: `Run ${charters_(charters.length)}?`,
+          detail: `${charters.length} browser run${charters.length === 1 ? "" : "s"}${url ? ` from ${url}` : ""}, and one more for each possible defect.${writes ? ` ${writes} create or change data: use a test environment.` : ""}`,
+          options: [
+            { id: "all", label: "Run them" },
+            ...(writes && writes < charters.length ? [{ id: "safe", label: "Only those that change no data" }] : []),
+            { id: "cancel", label: "Cancel" },
+          ],
+        })
+        if (answer === null || answer === "cancel") return { cancelled: true, charters: charters.map((c) => c.title), reason: "The user did not run the charters." }
+        if (answer === "safe") charters = charters.filter((c) => !c.changesData)
+      }
+      const dir = path.join(ctx.config.export.outDir, "explore", `${new Date().toISOString().replace(/[-:]/g, "").replace(/\..*/, "").replace("T", "-")}-${(story.id === "story" ? story.title : story.id).toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 40)}`)
+      const results = await exploreCharters({
+        config: ctx.config,
+        story,
+        charters,
+        dir,
+        url,
+        headed: ctx.headed,
+        maxSteps: ctx.maxSteps,
+        signal: ctx.signal,
+        execute: ctx.execute,
+        events: {
+          onRunStart: (c, _goal, repro) => emit({ type: "run-start", goal: `${c.id} ${repro ? "again, to confirm: " : ""}${c.title}${c.role ? ` (as ${c.role})` : ""}`, url }),
+          onRunEvent: (_c, event) => emit({ type: "run-event", event }),
+          onRunDone: (_c, r) => emit({ type: "run-done", result: r.result, error: r.error, files: [], runDir: r.runDir, ms: r.ms }),
+          onInfo: (text) => emit({ type: "info", text }),
+        },
+      })
+      const confirmed = results.filter((r) => r.status === "defect")
+      let bugs: Awaited<ReturnType<typeof fileConfirmed>> = []
+      if (confirmed.length && ctx.config.sources.bugs) {
+        const yes = ctx.ask
+          ? (await ctx.ask({
+              title: `File ${confirmed.length} bug${confirmed.length === 1 ? "" : "s"} for the confirmed defects?`,
+              detail: `In ${ctx.config.sources.bugs.system === "jira" ? "Jira" : "Azure DevOps"}. Each happened on two runs. Observations that did not reproduce are not filed.`,
+              lines: confirmed.map((r) => `• ${r.charter.title}: ${r.failure?.reason || ""}`.slice(0, 200)),
+              options: [
+                { id: "yes", label: "File them" },
+                { id: "no", label: "Not now" },
+              ],
+            })) === "yes"
+          : args.file_bugs === true
+        if (yes) bugs = await fileConfirmed(ctx.config, story, results)
+      }
+      const proposed = proposedCases(results)
+      const browser = results.reduce((u, r) => addUsage(u, r.usage), { input: 0, output: 0 })
+      const x = { dir, story, results, proposed, bugs, usage: { plan: plan.usage, browser } }
+      const report = saveExploration(x)
+      emit({ type: "card", card: explorationCard({ ...x, report }, ctx.cwd) })
+      return {
+        story: { id: story.id, system: story.system, title: story.title, url: story.url },
+        confirmed_defects: confirmed.map((r) => ({ charter: r.charter.title, what: r.failure?.reason, run_dir: r.runDir, repro_run_dir: r.reproRunDir })),
+        not_reproduced: results.filter((r) => r.status === "not_reproduced").map((r) => ({ charter: r.charter.title, what: r.observations[0] })),
+        could_not_explore: results.filter((r) => r.status === "could_not_explore").map((r) => ({ charter: r.charter.title, why: r.failure ? `${r.failure.type}: ${r.failure.reason}` : r.summary })),
+        observations: results.flatMap((r) => r.observations.map((o) => `${r.charter.id}: ${o}`)).slice(0, 30),
+        bugs: bugs.length ? bugs : undefined,
+        bugs_not_set_up: confirmed.length && !ctx.config.sources.bugs ? "No bug tracker is set up (bugs: in forgeqe.yaml), so no bugs were filed." : undefined,
+        proposed_test_cases: proposed.map(({ from, kind, ...c }) => ({ ...c, from_charter: from, kind })),
+        report,
+        next_step:
+          story.system === "text"
+            ? "Report the confirmed defects and observations. Offer to save the proposed test cases once the user names the story they belong to."
+            : `Report the confirmed defects (with their bugs) and observations. Offer to save the proposed test cases to the story with save_test_cases (system ${story.system === "ado" ? "azure_devops" : "jira"}, story ${story.system === "ado" ? story.id.replace(/^ADO-/, "") : story.id}), after the user picks which.`,
+      }
+    },
+  },
+]