@capagents/forgeqe 0.0.0-stage → 1.0.1

package/src/mcp/tools.ts

@@ -0,0 +1,810 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import type { AgentEvent, CodeEvent, CodeResult, ReplayMode, RunResult } from "../types.ts"
+import type { Card } from "../card.ts"
+import { privateEnvNames } from "../childEnv.ts"
+import { usageLine } from "../usage.ts"
+import { queryApi } from "../cases/api.ts"
+import { createAdoDashboard, type DashboardWidget } from "../cases/dashboards.ts"
+import { writeAdoWikiPage } from "../cases/wiki.ts"
+import { readConfluence } from "../cases/confluence.ts"
+import { casesFrom, type CaseSelector, type TestCase } from "../cases/index.ts"
+import { saveAdoCases, saveJiraCases, type NewCase } from "../cases/save.ts"
+import { buildHandoff } from "../code/handoff.ts"
+import { latestRunDir, runCodeAgent } from "../code/index.ts"
+import type { OpencodeSession } from "../code/runtime.ts"
+import { runTestCommand } from "../code/testrun.ts"
+import type { AppConfig } from "../config.ts"
+import { clearMemory, memoryFilesFor, memoryFlows, memoryOverview, memoryShow } from "../memory.ts"
+import { executeRun, runDirectory } from "../run.ts"
+import { counts } from "../suite/report.ts"
+import { runSuite, type SuiteEvent, type SuiteResult } from "../suite/run.ts"
+import { COMMAND_TOOLS, TASK_FILE } from "./commands.ts"
+import { PR_TOOLS } from "./prtools.ts"
+import { CASE_TOOLS, checkResult, precheck } from "./casetools.ts"
+import { REPO_TEST_TOOLS } from "./repotests.ts"
+import { API_TOOLS } from "./apitools.ts"
+import { EXPLORE_TOOLS } from "./exploretools.ts"
+import { QUALITY_TOOLS } from "./qualitytools.ts"
+import { CAPABILITY_TOOLS } from "./captools.ts"
+import { NOTIFY_TOOLS } from "./notifytools.ts"
+import { capabilityIndex } from "../capabilities/render.ts"
+import { domainNotes } from "../domain.ts"
+import { readNetwork } from "../api/traffic.ts"
+import { qualityLine } from "../quality/budgets.ts"
+import { knowledgeIndex, readKnowledge } from "../knowledge.ts"
+import { allLogins, sessionLogins } from "../sessionLogins.ts"
+import { catalogLines, loadSkills, skillsFor } from "../skills/registry.ts"
+import { buildCodeSummary, codeCard } from "../summary.ts"
+import { pushBranch, setCiSecret } from "./git.ts"
+import { FAILURE_ACTION, FAILURE_LABEL } from "../cases/failure.ts"
+import { notifiedLine, notifySuite } from "../notify/events.ts"
+
+/** Hosts of the systems ForgeQE reads test cases and work items from: browsing them is a task, never a flow to test. */
+function toolHosts(cfg: AppConfig): string[] {
+  const s = cfg.sources
+  const urls = [s?.ado?.orgUrl, s?.jira?.url, s?.confluence?.url, s?.testrail?.url, s?.zephyr?.url, s?.qtest?.url, s?.xray?.url]
+  const hosts = urls.flatMap((u) => {
+    try {
+      return u ? [new URL(u).hostname.toLowerCase()] : []
+    } catch {
+      return []
+    }
+  })
+  return [...new Set([...hosts, "dev.azure.com", "visualstudio.com"])]
+}
+
+/** Why a browser_run is a task rather than a flow to automate, or "" when it is a test. */
+export function taskReason(purpose: unknown, goal: string, urls: (string | undefined)[], cfg: AppConfig): string {
+  if (purpose === "task") return "the run was a task, not a flow to test"
+  const hosts = toolHosts(cfg)
+  const seen = [...urls, ...(goal.match(/https?:\/\/[^\s"'<>)]+/g) || [])].flatMap((u) => {
+    try {
+      return u ? [new URL(u).hostname.toLowerCase()] : []
+    } catch {
+      return []
+    }
+  })
+  const hit = seen.find((h) => hosts.some((t) => h === t || h.endsWith(`.${t}`)))
+  return hit ? `the run was in ${hit}, a system ForgeQE reads test cases and work items from, not the app under test` : ""
+}
+
+/** The goal a run folder's run.json records, or "" when it has none. */
+function goalOf(runDir: string): string {
+  try {
+    return (JSON.parse(readFileSync(path.join(runDir, "run.json"), "utf8")) as { goal?: string }).goal || ""
+  } catch {
+    return ""
+  }
+}
+
+/** What a tool is doing, for whoever shows it (the shell transcript, or stderr for `forgeqe mcp`). */
+export type ToolEvent =
+  | { type: "run-start"; goal: string; url?: string }
+  | { type: "run-event"; event: AgentEvent }
+  | { type: "run-done"; result?: RunResult; error?: string; files: string[]; runDir: string; ms: number }
+  | { type: "suite-start"; cases: TestCase[]; parallel: number }
+  | { type: "suite-event"; event: SuiteEvent }
+  | { type: "suite-done"; suite: SuiteResult }
+  | { type: "info"; text: string; ok?: boolean }
+  /** What a coding or healing agent started by a tool is doing. */
+  | { type: "agent"; event: CodeEvent }
+  /** write_test hands a passed browser run to the coding agent, and what came of it. */
+  | { type: "code-start"; runDir: string; repo: string; goal: string }
+  | { type: "code-done"; result?: CodeResult; error?: string; ms: number }
+  /** A tool's result to show as a panel (a test written, tests healed, a monitoring round). */
+  | { type: "card"; card: Card }
+
+export type ToolContext = {
+  config: AppConfig
+  /** The repository or folder the agent works in. */
+  cwd: string
+  headed?: boolean
+  maxSteps?: number
+  replay?: ReplayMode
+  memory?: boolean
+  /** Start URL the user pinned for this session. */
+  url?: string
+  signal?: AbortSignal
+  emit?: (e: ToolEvent) => void
+  /** How long this process lives: the shell, one `forgeqe run`, or `forgeqe mcp`. Background monitors need shell or server. */
+  session?: "shell" | "once" | "server"
+  /** Passed browser runs become tests in cwd (the shell and `forgeqe run` without --no-code). */
+  writeTests?: boolean
+  /** Ask the user to do something by hand, then continue (true) or cancel (false). Missing where nobody can answer. */
+  waitForUser?: (prompt: string) => Promise<boolean>
+  /** Ask the user to pick one option; the chosen id, or null when they cancel. Missing where nobody can answer. */
+  ask?: (q: AskQuestion) => Promise<string | null>
+  /** Replaces executeRun in tests. */
+  execute?: typeof executeRun
+  /** Replaces openSession for write_test and heal_tests in tests. */
+  openSession?: (o: any) => Promise<OpencodeSession<any>>
+  /** Replaces write_test's confirming run in tests. */
+  runTest?: typeof runTestCommand
+}
+
+/** `lines`: context shown above the choice (the list being confirmed, sprint dates). */
+export type AskQuestion = { title: string; detail?: string; lines?: string[]; options: { id: string; label: string }[] }
+
+export type McpTool = {
+  name: string
+  description: string
+  inputSchema: Record<string, unknown>
+  run(args: Record<string, any>, ctx: ToolContext): Promise<unknown>
+}
+
+const clip = (s: string | undefined, n: number) => {
+  const t = (s || "").trim()
+  return t.length <= n ? t : `${t.slice(0, n - 1)}…`
+}
+
+const SKILLS_SCHEMA = {
+  type: "array",
+  items: { type: "string" },
+  description:
+    "Names of the browser skills (listed in this session's notes) the goal clearly needs, for example a playbook for the site or widget it uses; [] when none fits. Leave it out to let ForgeQE choose.",
+}
+
+/** The `skills` argument as names; undefined when the caller left it out. */
+function skillNames(raw: unknown): string[] | undefined {
+  if (!Array.isArray(raw)) return undefined
+  return [...new Set(raw.map((n) => String(n).trim()).filter(Boolean))]
+}
+
+const SOURCES_SCHEMA = {
+  type: "array",
+  minItems: 1,
+  description: "Where the test cases are. Several entries mix sources.",
+  items: {
+    type: "object",
+    properties: {
+      source: {
+        type: "string",
+        enum: ["azure_devops", "jira", "xray", "testrail", "zephyr", "qtest", "file", "text"],
+        description:
+          "azure_devops: Test Case work items or a Test Plan. jira: issues. xray: Xray Test issues or a Test Plan. testrail: cases, a run, a plan, or a suite. zephyr: Zephyr Scale test cases, a test cycle, or a folder. qtest: qTest test cases, a test cycle, or a suite. file: .txt/.md/.csv/.yaml/.json/.feature files. text: test case text the user wrote (also cases you wrote from requirements).",
+      },
+      ids: {
+        type: "array",
+        items: { type: "string" },
+        description: "Work item ids (azure_devops), issue keys (jira, xray), case ids like C12 (testrail), keys like SHOP-T3 (zephyr), or test case ids (qtest)",
+      },
+      plan: { type: "string", description: "Test plan id (azure_devops, testrail) or Test Plan issue key (xray)" },
+      suite: { type: "string", description: "Suite id: inside the Azure DevOps plan (omit for every suite), a TestRail suite, or a qTest test suite" },
+      run: { type: "string", description: "testrail: run id; results go to that run" },
+      cycle: { type: "string", description: "zephyr: test cycle key like SHOP-R5. qtest: test cycle id" },
+      folder: { type: "string", description: "zephyr: folder id" },
+      jql: { type: "string", description: "JQL query (jira, xray)" },
+      paths: { type: "array", items: { type: "string" }, description: "Files, relative to the working directory" },
+      text: { type: "string", description: "The test case itself: title on the first line, then steps and expected results" },
+    },
+    required: ["source"],
+  },
+} as const
+
+/** How many of the application's API calls the run recorded. */
+function apiCalls(runDir: string): number {
+  return readNetwork(runDir).filter((c) => !c.third_party).length
+}
+
+function summarizeRun(result: RunResult, runDir: string, files: string[]) {
+  return {
+    status: result.status === "complete" && !result.budgetExceeded?.length ? "passed" : result.status === "fail" || result.status === "complete" ? "failed" : "stopped",
+    ...(result.budgetExceeded?.length ? { budget_exceeded: result.budgetExceeded, meaning_of_budget: "The steps passed, but a page is over an accessibility or performance budget in forgeqe.yaml, so the run fails. A test can still be written for it." } : {}),
+    ...(result.quality ? { quality: qualityLine(result.quality) } : {}),
+    ...(result.outcome === "assertion_failed"
+      ? {
+          outcome: "assertion_failed",
+          meaning: "The steps were done and an expected result does not hold: the test case failed, which is a valid result to report. Do not retry it, change the expectation, or treat it as a ForgeQE problem.",
+          failed_expectations: (result.failedChecks || []).map((c) => ({ expected: c.expected, page_shows: c.actual })),
+        }
+      : {}),
+    summary: result.summary,
+    final_url: result.finalUrl,
+    run_dir: runDir,
+    files: files.map((f) => path.basename(f)),
+    ...(apiCalls(runDir) ? { api_calls: `${apiCalls(runDir)} API calls recorded (network.json): api_contracts from run turns them into API tests` } : {}),
+    tokens: result.usage.input + result.usage.output,
+    usage: usageLine(result.usage, result.cost),
+    memory: result.memory ? { replayed: result.memory.replayed, llm_steps: result.memory.llmSteps, flow: result.memory.flow } : undefined,
+    driver: result.driver,
+    ...(result.skills?.length ? { skills: result.skills } : {}),
+    ...(result.status === "fail" && result.memory?.resume
+      ? {
+          resume: {
+            steps_that_worked: result.memory.resume.lines.map((l, i) => `${i + 1}. ${clip(l, 160)}`),
+            went_wrong_at_step: result.memory.resume.failedAt,
+            next_step:
+              `To retry, call browser_run with resume_from "${runDir}": these steps are replayed without the model and the agent carries on from there. ` +
+              "Keep the same site and values, and say in the goal what to do differently from the failed attempt.",
+          },
+        }
+      : {}),
+  }
+}
+
+export const TOOLS: McpTool[] = [
+  {
+    name: "browser_run",
+    description:
+      "Carry out a goal in a real browser with ForgeQE's browser agent and verify the outcome. The agent picks the site from the goal unless start_url is given. Returns pass/fail, the agent's summary, the steps, and the run folder (run.json, workflow.yaml with ranked locators, trace.md, steps and screenshots, report.html). Takes minutes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        goal: {
+          type: "string",
+          description:
+            "The final instructions for the browser agent: what to do and what to check, in plain language, with every value it needs. Only the decided task; never your own questions, alternatives, or reasoning about it.",
+        },
+        start_url: { type: "string", description: "Page to open first, only when the user named one" },
+        resume_from: {
+          type: "string",
+          description:
+            "run_dir of a failed browser_run that returned resume steps: replay the steps that worked there, without the model, then carry on with this goal",
+        },
+        skills: SKILLS_SCHEMA,
+        purpose: {
+          type: "string",
+          enum: ["test", "task"],
+          description:
+            "test: a user flow of the app under test, to verify and turn into an automated test. task: anything else done in a browser, such as looking up or linking work items, checking a relationship, or reading data from a tool; no test is written for it.",
+        },
+      },
+      required: ["goal", "purpose"],
+    },
+    async run(args, ctx) {
+      const goal = String(args.goal || "").trim()
+      if (!goal) throw new Error("goal is required")
+      const from = args.resume_from ? String(args.resume_from) : ""
+      const resumeFrom = from ? (existsSync(path.resolve(ctx.cwd, from)) ? path.resolve(ctx.cwd, from) : from) : undefined
+      const url = args.start_url ? String(args.start_url) : ctx.url
+      const runDir = runDirectory(ctx.config.export.outDir)
+      const emit = ctx.emit || (() => {})
+      const t0 = Date.now()
+      emit({ type: "run-start", goal, url })
+      try {
+        const { result, files } = await (ctx.execute || executeRun)({
+          config: ctx.config,
+          goal,
+          url,
+          headed: ctx.headed,
+          maxSteps: ctx.maxSteps,
+          outDir: runDir,
+          replay: ctx.replay,
+          memory: ctx.memory,
+          resumeFrom,
+          skills: skillNames(args.skills),
+          repo: ctx.cwd,
+          signal: ctx.signal,
+          onEvent: (event) => emit({ type: "run-event", event }),
+        })
+        emit({ type: "run-done", result, files, runDir, ms: Date.now() - t0 })
+        const summary = summarizeRun(result, runDir, files)
+        const task = taskReason(args.purpose, goal, [url, result.startUrl, result.finalUrl], ctx.config)
+        if (task) {
+          writeFileSync(path.join(runDir, TASK_FILE), `${JSON.stringify({ reason: task }, null, 2)}\n`)
+          return summary
+        }
+        if (ctx.writeTests && result.status === "complete" && result.driver !== "synthetic") {
+          return { ...summary, next_step: `This session turns passed runs into tests: call write_test with run_dir ${runDir} now, before you reply.` }
+        }
+        return summary
+      } catch (err) {
+        emit({ type: "run-done", error: (err as Error).message, files: [], runDir, ms: Date.now() - t0 })
+        throw err
+      }
+    },
+  },
+  {
+    name: "find_test_cases",
+    description:
+      "Read test cases from Azure DevOps, Jira, Xray, TestRail, Zephyr Scale, qTest, files, or text, without running them. Returns each case's id, title, start URL, steps with expected results, and link.",
+    inputSchema: { type: "object", properties: { sources: SOURCES_SCHEMA }, required: ["sources"] },
+    async run(args, ctx) {
+      const cases = await casesFrom(args.sources as CaseSelector[], ctx.config.sources, ctx.cwd)
+      return {
+        count: cases.length,
+        cases: cases.map((c) => ({
+          id: c.id,
+          title: c.title,
+          source: c.source,
+          link: c.url,
+          start_url: c.startUrl,
+          description: clip(c.description, 600) || undefined,
+          preconditions: c.preconditions,
+          steps: c.steps.map((s) => ({ action: clip(s.action, 300), data: s.data, expected: s.expected })),
+        })),
+      }
+    },
+  },
+  {
+    name: "save_test_cases",
+    description:
+      "Save test cases you wrote from a story into Azure DevOps (Test Case work items with steps and expected results, linked to the story as Tests / Tested By, in the story's area and iteration) or Jira (issues of type Test by default, steps in the description, linked to the story). A case whose title matches one already linked to the story is reused, not duplicated. Returns each case's id and link, and shows them as a card.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        system: { type: "string", enum: ["azure_devops", "jira"], description: "Where the story is" },
+        story: { type: "string", description: "The story's work item id (Azure DevOps) or issue key (Jira)" },
+        cases: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              title: { type: "string" },
+              steps: {
+                type: "array",
+                items: { type: "object", properties: { action: { type: "string" }, expected: { type: "string" } }, required: ["action"] },
+              },
+              preconditions: { type: "array", items: { type: "string" } },
+              description: { type: "string" },
+            },
+            required: ["title", "steps"],
+          },
+        },
+        issue_type: { type: "string", description: "Jira only: issue type for the cases (default Test)" },
+        link_type: { type: "string", description: "Jira only: link type to the story (default Relates)" },
+      },
+      required: ["system", "story", "cases"],
+    },
+    async run(args, ctx) {
+      const cases = (Array.isArray(args.cases) ? args.cases : []) as NewCase[]
+      if (!cases.length) throw new Error("cases is empty.")
+      const story = String(args.story || "").trim()
+      if (!story) throw new Error("story is required.")
+      const saved =
+        args.system === "jira"
+          ? await saveJiraCases(ctx.config.sources, story, cases, { issueType: args.issue_type ? String(args.issue_type) : undefined, linkType: args.link_type ? String(args.link_type) : undefined })
+          : await saveAdoCases(ctx.config.sources, Number(story.replace(/^#/, "")), cases)
+      const made = saved.cases.filter((c) => c.created).length
+      const failed = saved.cases.filter((c) => !c.id).length
+      ctx.emit?.({
+        type: "card",
+        card: {
+          status: failed ? "fail" : "ok",
+          title: `Test cases saved for ${saved.story.id}${saved.story.title ? ` ${saved.story.title}` : ""}`,
+          stats: [`${made} created`, saved.cases.length - made - failed ? `${saved.cases.length - made - failed} already linked` : "", failed ? `${failed} failed` : ""].filter(Boolean).join(" · "),
+          body: [
+            `Story     ${saved.story.url}`,
+            "",
+            ...saved.cases.flatMap((c) => (c.id ? [`${c.created ? "+" : "="} ${c.id}  ${c.title}`, `    ${c.url}`, ...(c.error ? [`    ${c.error}`] : [])] : [`✗ ${c.title}: ${c.error}`])),
+          ],
+        },
+      })
+      return {
+        story: saved.story,
+        cases: saved.cases.map((c) => ({ title: c.title, id: c.id || undefined, url: c.url || undefined, created: c.created, error: c.error })),
+        ...(saved.system === "azure_devops" && saved.cases.some((c) => c.id) ? { run_with: { source: "azure_devops", ids: saved.cases.filter((c) => c.id).map((c) => c.id) } } : {}),
+      }
+    },
+  },
+  {
+    name: "run_test_cases",
+    description:
+      "Run test cases in real browsers: each case is one browser goal whose steps are done in order and whose expected results are checked, with a verdict for every step. Writes report.html (steps, screenshots, timings) and junit.xml, posts results back to Azure DevOps, Jira, Xray, TestRail, Zephyr Scale, or qTest unless write_back is false, and files or updates bugs for failures when bugs are set up. In a session that writes tests, each passed case is handed to ForgeQE's coding agent as soon as its browser run ends, and its test is written and run before the next case starts. Returns each case's result, step verdicts, run folder, and test (file, command, status, or why none was written). Takes minutes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sources: SOURCES_SCHEMA,
+        parallel: { type: "integer", minimum: 1, maximum: 8, description: "Browsers at once (default from config)" },
+        write_back: { type: "boolean", description: "Post results to the source system (default from config)" },
+        skills: SKILLS_SCHEMA,
+      },
+      required: ["sources"],
+    },
+    async run(args, ctx) {
+      const all = await casesFrom(args.sources as CaseSelector[], ctx.config.sources, ctx.cwd)
+      // Cases a browser cannot test as written cost a run and fail for the case's sake: checked first.
+      const { checks, skip } = precheck(all, ctx)
+      const cases = all.filter((c) => !skip.has(c.id))
+      if (!cases.length) return { ran: false, reason: "No case can run as written (suite.case_check: block).", check: checkResult(checks) }
+      if (!cases.length) throw new Error("No test cases found.")
+      const parallel = Math.min(Number(args.parallel) || ctx.config.suite.parallel, cases.length)
+      const emit = ctx.emit || (() => {})
+      emit({ type: "suite-start", cases, parallel })
+      // In a session that writes tests, each passed case goes to the coding agent right after its own browser run,
+      // inside the suite, rather than every case being explored first and handed over at the end.
+      const coder: typeof runCodeAgent = async (o) => {
+        const t0 = Date.now()
+        emit({ type: "code-start", runDir: o.runDir, repo: o.repo, goal: goalOf(o.runDir) })
+        try {
+          const r = await runCodeAgent({
+            ...o,
+            onEvent: (event) => emit({ type: "agent", event }),
+            open: ctx.openSession as never,
+            runTest: ctx.runTest,
+          })
+          emit({ type: "code-done", result: r, ms: Date.now() - t0 })
+          emit({ type: "card", card: codeCard(buildCodeSummary(r, Date.now() - t0)) })
+          return r
+        } catch (err) {
+          emit({ type: "code-done", error: (err as Error).message, ms: Date.now() - t0 })
+          throw err
+        }
+      }
+      const suite = await runSuite({
+        config: ctx.writeTests ? { ...ctx.config, suite: { ...ctx.config.suite, code: true } } : ctx.config,
+        cases,
+        ...(ctx.writeTests ? { repo: ctx.cwd, coder } : {}),
+        parallel,
+        writeBack: typeof args.write_back === "boolean" ? args.write_back : undefined,
+        headed: ctx.headed,
+        url: ctx.url,
+        maxSteps: ctx.maxSteps,
+        replay: ctx.replay,
+        memory: ctx.memory,
+        skills: skillNames(args.skills),
+        skillsRepo: ctx.cwd,
+        signal: ctx.signal,
+        execute: ctx.execute,
+        onEvent: (event) => emit({ type: "suite-event", event }),
+      })
+      emit({ type: "suite-done", suite })
+      const c = counts(suite.results)
+      // In the shell people try things out: the team hears about a suite only from runs nobody is watching.
+      const notified = ctx.session === "shell" ? [] : await notifySuite(ctx.config, suite)
+      return {
+        ...(notified.length ? { notified: notifiedLine(notified) } : {}),
+        passed: c.passed,
+        failed: c.failed,
+        errors: c.errors,
+        not_run: c.stopped,
+        stopped: suite.stopped,
+        report: suite.files.html,
+        junit: suite.files.junit,
+        results: suite.results.map((r) => ({
+          id: r.case.id,
+          title: r.case.title,
+          status: r.status,
+          summary: clip(r.summary, 600),
+          steps: r.stepResults?.map((s) => `${s.step}. ${s.status}${s.status === "failed" && s.cause ? ` (cause: ${s.cause})` : ""}${s.actual ? `: ${clip(s.actual, 200)}` : ""}`),
+          ...(r.failure ? { failure: { type: r.failure.type, label: FAILURE_LABEL[r.failure.type], reason: r.failure.reason, what_happens: FAILURE_ACTION[r.failure.type], ...(r.failure.step ? { step: r.failure.step } : {}) } } : {}),
+          ...(r.retried ? { retried: "the first run met an environment problem, so the case ran once more" } : {}),
+          ...(r.bug ? { bug: r.bug } : {}),
+          run_dir: r.runDir,
+          final_url: r.finalUrl,
+          ...(r.code
+            ? {
+                test: {
+                  status: r.code.status,
+                  test_file: r.code.testFile,
+                  test_name: r.code.testName,
+                  command: r.code.command,
+                  attempts: r.code.attempts,
+                  handoff: r.code.handoff,
+                  error: r.code.error,
+                  ...(r.code.knownDefect ? { known_defect: "asserts the correct behaviour, marked as an expected failure until the defect is fixed" } : {}),
+                  ...(r.code.attention ? { needs_attention: `${r.code.attention}/ (README.md there says why and how to pick it up)` } : {}),
+                },
+              }
+            : r.codeSkipped
+              ? { test: { status: "not written", why: r.codeSkipped } }
+              : {}),
+        })),
+        write_back: suite.writeBack,
+        ...(checks.some((c) => c.verdict !== "ready") ? { case_check: checkResult(checks.filter((c) => c.verdict !== "ready")) } : {}),
+        ...(skip.size ? { not_run_as_written: [...skip] } : {}),
+      }
+    },
+  },
+  {
+    name: "run_details",
+    description:
+      "Everything about a browser run needed to write a test for it: goal, result, every step with the value typed (secrets as env var names), and each element's ranked locators with confidence from page memory. Defaults to the latest run.",
+    inputSchema: { type: "object", properties: { run_dir: { type: "string", description: "Run folder from browser_run or run_test_cases" } } },
+    async run(args, ctx) {
+      const dir = args.run_dir ? path.resolve(ctx.cwd, String(args.run_dir)) : latestRunDir(ctx.config.export.outDir)
+      if (!dir || !existsSync(dir)) throw new Error("No run found. Run a goal first.")
+      const h = buildHandoff(dir, ctx.config.memory.dir)
+      return { run_dir: dir, passed: h.success, handoff_file: h.file, handoff: h.markdown }
+    },
+  },
+  {
+    name: "run_test",
+    description:
+      "ForgeQE runs a test command itself (from the working directory, CI=1, no prompts) and returns the exit code, the end of the output, and the browsers the test launched. A test you write only counts as done when this passes with a browser.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        command: { type: "string", description: "Command that runs only the test, non-interactively" },
+        cwd: { type: "string", description: "Folder to run it in, relative to the working directory (default: the working directory)" },
+      },
+      required: ["command"],
+    },
+    async run(args, ctx) {
+      const command = String(args.command || "").trim()
+      if (!command) throw new Error("command is required")
+      const cwd = args.cwd ? path.resolve(ctx.cwd, String(args.cwd)) : ctx.cwd
+      ctx.emit?.({ type: "info", text: `ForgeQE runs: ${command}` })
+      const run = await runTestCommand({ command, cwd, timeoutSeconds: ctx.config.code.testTimeoutSeconds, signal: ctx.signal, hide: privateEnvNames(ctx.config) })
+      const why = run.ok ? `passed in ${Math.round(run.ms / 1000)}s` : run.exitCode === null ? `timed out after ${ctx.config.code.testTimeoutSeconds}s` : `failed, exit ${run.exitCode}`
+      ctx.emit?.({ type: "info", text: `${command.length > 80 ? `${command.slice(0, 79)}…` : command} ${why}`, ok: run.ok })
+      return { passed: run.ok, exit_code: run.exitCode, seconds: Math.round(run.ms / 1000), browsers: run.browsers, output: run.output }
+    },
+  },
+  {
+    name: "page_memory",
+    description:
+      "What ForgeQE's page memory knows: with no target, every host with its pages, elements, and recorded flows; with a host or URL, its elements and best locators with confidence. action flows: the recorded goals (steps: with their steps). action clear: delete what memory knows about a host, or everything; only when the user asks for it.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: { type: "string", description: "Host (booking.com) or page URL" },
+        action: { type: "string", enum: ["show", "flows", "clear"], description: "show (default), flows, or clear" },
+        steps: { type: "boolean", description: "flows: include each flow's steps" },
+      },
+    },
+    async run(args, ctx) {
+      const dir = ctx.config.memory.dir
+      if (args.action === "flows") return memoryFlows(dir, { steps: args.steps === true })
+      if (args.action === "clear") {
+        const files = memoryFilesFor(dir, args.target ? String(args.target) : undefined)
+        clearMemory(files)
+        const text = files.length ? `Deleted ${files.length} memory files${args.target ? ` for ${args.target}` : ""}.` : "Nothing to clear."
+        ctx.emit?.({ type: "info", text, ok: true })
+        return text
+      }
+      return args.target ? memoryShow(dir, String(args.target), { locators: true, limit: 40 }) : memoryOverview(dir)
+    },
+  },
+  {
+    name: "read_confluence",
+    description:
+      "Read Confluence pages as text (requirements, specs, acceptance criteria), by page id or link, or by a CQL search. Tables keep their cells apart with |.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        pages: { type: "array", items: { type: "string" }, description: "Page ids or page links" },
+        cql: { type: "string", description: 'CQL search, e.g. title ~ "checkout" AND type = page, or label = "requirements"' },
+        limit: { type: "integer", minimum: 1, maximum: 25, description: "Most pages to return (default 10)" },
+      },
+    },
+    async run(args, ctx) {
+      const pages = Array.isArray(args.pages) ? args.pages.map(String) : undefined
+      return readConfluence(ctx.config.sources, { pages, cql: args.cql ? String(args.cql) : undefined, limit: Number(args.limit) || undefined })
+    },
+  },
+  {
+    name: "query_api",
+    description:
+      "Read anything from Azure DevOps, Jira, Xray, or Confluence through their APIs with the credentials in ForgeQE's settings: work items, bugs, stories, queries, pipeline runs, issues, JQL searches, Xray tests and executions, Confluence pages and spaces. Use it for what the other tools and connected MCP servers don't cover, or when a system has no MCP server. Read-only: GET requests, WIQL searches for Azure DevOps work items, and GraphQL queries for Xray Cloud.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        system: { type: "string", enum: ["azure_devops", "jira", "xray", "confluence"] },
+        path: {
+          type: "string",
+          description:
+            "azure_devops: REST path under the organization URL, e.g. Shop/_apis/wit/workitems/12?$expand=all (api-version=7.1 is added when missing). jira: REST path under the site URL, e.g. /rest/api/3/search/jql?jql=project%3DSHOP&fields=summary,status (Server/Data Center: /rest/api/2/..., Xray Server: /rest/raven/1.0/...). confluence: REST path under the Confluence URL, e.g. /rest/api/space or /api/v2/pages/123/children (Cloud).",
+        },
+        query: { type: "string", description: "xray (Cloud): a GraphQL query, e.g. { getTests(jql: \"project = SHOP\", limit: 10) { results { jira(fields: [\"key\"]) } } }" },
+        wiql: {
+          type: "string",
+          description:
+            "azure_devops: a WIQL query to search work items (instead of path), e.g. SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @project AND [System.WorkItemType] = 'User Story' ORDER BY [System.ChangedDate] DESC. Returns the first 50 with id, type, title, state, assignee, changed date, and iteration. Use it to find or list work items; the Analytics (_odata) endpoints need a token with the Analytics scope.",
+        },
+        project: { type: "string", description: "azure_devops wiql: the project @project refers to (default: the configured project)" },
+        variables: { type: "object", description: "xray: GraphQL variables" },
+      },
+      required: ["system"],
+    },
+    async run(args, ctx) {
+      return queryApi(ctx.config.sources, { system: args.system, path: args.path, query: args.query, variables: args.variables, wiql: args.wiql, project: args.project })
+    },
+  },
+  {
+    name: "create_ado_dashboard",
+    description:
+      "Create an Azure DevOps dashboard through the API with ForgeQE's credentials, only when the user asks for one. Each list or count widget gets its own shared query (saved under Shared Queries/ForgeQE, updated when one of the same name is already there), then the dashboard is created with a work item list or a count tile for each, plus optional markdown text. Every WIQL query is run first, so a bad query fails before anything is saved. Charts (pie, bar, trend) are not supported here.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project: { type: "string", description: "Project name; the configured project when left out" },
+        team: { type: "string", description: "Team name for a team dashboard; leave out for a project dashboard" },
+        name: { type: "string", description: "Dashboard name" },
+        description: { type: "string" },
+        widgets: {
+          type: "array",
+          minItems: 1,
+          items: {
+            type: "object",
+            properties: {
+              kind: { type: "string", enum: ["list", "count", "markdown"], description: "list (default): the query's work items. count: a tile with how many it returns. markdown: text." },
+              title: { type: "string", description: "Widget title, which also names its saved query" },
+              wiql: {
+                type: "string",
+                description:
+                  "list and count: a flat-list WIQL query whose SELECT columns are the columns shown, e.g. SELECT [System.Id], [System.Title], [System.State], [System.AssignedTo] FROM WorkItems WHERE [System.TeamProject] = @project AND [System.WorkItemType] = 'Bug' ORDER BY [System.State]. For the current sprint, name the team: [System.IterationPath] = @CurrentIteration('[Project]\\\\Team name').",
+              },
+              text: { type: "string", description: "markdown: the text" },
+            },
+          },
+        },
+      },
+      required: ["name", "widgets"],
+    },
+    async run(args, ctx) {
+      const widgets: DashboardWidget[] = (Array.isArray(args.widgets) ? args.widgets : []).map((w: Record<string, unknown>) =>
+        w.kind === "markdown"
+          ? { kind: "markdown", title: w.title ? String(w.title) : undefined, text: String(w.text || "") }
+          : { kind: w.kind === "count" ? "count" : "list", title: String(w.title || ""), wiql: String(w.wiql || "") },
+      )
+      const out = await createAdoDashboard(ctx.config.sources, {
+        project: args.project ? String(args.project) : undefined,
+        team: args.team ? String(args.team) : undefined,
+        name: String(args.name || ""),
+        description: args.description ? String(args.description) : undefined,
+        widgets,
+      })
+      ctx.emit?.({ type: "info", text: `Azure DevOps dashboard "${out.name}" created in ${out.project}${out.team ? ` for ${out.team}` : ""}: ${out.url}`, ok: true })
+      return out
+    },
+  },
+  {
+    name: "write_ado_wiki_page",
+    description:
+      "Create or update an Azure DevOps wiki page through the API with ForgeQE's credentials, only when the user asks for one. When the project has no wiki yet, its project wiki is created first (the Azure DevOps MCP server cannot create a wiki). Missing parent pages are created empty; an existing page at the path is replaced with the new content.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project: { type: "string", description: "Project name; the configured project when left out" },
+        wiki: { type: "string", description: "Wiki name or id; leave out for the project wiki" },
+        path: { type: "string", description: "Page path, e.g. /Release notes/Sprint 12" },
+        content: { type: "string", description: "The page as Markdown" },
+      },
+      required: ["path", "content"],
+    },
+    async run(args, ctx) {
+      const out = await writeAdoWikiPage(ctx.config.sources, {
+        project: args.project ? String(args.project) : undefined,
+        wiki: args.wiki ? String(args.wiki) : undefined,
+        path: String(args.path || ""),
+        content: String(args.content ?? ""),
+      })
+      const text = `Wiki page ${out.path} ${out.created ? "created" : "updated"} in ${out.project}${out.wikiCreated ? ` (created the ${out.wiki} wiki)` : ""}: ${out.url}`
+      ctx.emit?.({ type: "info", text, ok: true })
+      return out
+    },
+  },
+  {
+    name: "push_branch",
+    description:
+      "Push the current commit to a branch on the remote so a pipeline can run it. Refuses the default branch, main, and master, and never forces. This is the only way to push; git push in the shell is blocked.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        branch: { type: "string", description: "Branch to push to, e.g. forgeqe/ci-pipeline" },
+        remote: { type: "string", description: "Remote name (default origin)" },
+      },
+      required: ["branch"],
+    },
+    async run(args, ctx) {
+      const text = await pushBranch(ctx.cwd, String(args.branch || ""), args.remote ? String(args.remote) : undefined)
+      ctx.emit?.({ type: "info", text: text.split("\n")[0], ok: true })
+      return text
+    },
+  },
+  {
+    name: "set_ci_secret",
+    description:
+      "Store one of ForgeQE's environment variables (an API key or token the pipeline needs) as a GitHub Actions secret or an Azure Pipelines secret variable. You give only the name; ForgeQE reads the value from its environment and never shows it to you.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        platform: { type: "string", enum: ["github", "azure_devops"] },
+        name: { type: "string", description: "Environment variable name, which is also the secret name" },
+        repo: { type: "string", description: "github: owner/repo when it is not the repo in the working directory" },
+        pipeline: { type: "string", description: "azure_devops: pipeline name" },
+      },
+      required: ["platform", "name"],
+    },
+    async run(args, ctx) {
+      const ado = ctx.config.sources.ado
+      const text = await setCiSecret(ctx.cwd, {
+        platform: args.platform === "azure_devops" ? "azure_devops" : "github",
+        name: String(args.name || ""),
+        repo: args.repo ? String(args.repo) : undefined,
+        pipeline: args.pipeline ? String(args.pipeline) : undefined,
+        org: ado?.orgUrl,
+        project: ado?.project,
+      })
+      ctx.emit?.({ type: "info", text, ok: true })
+      return text
+    },
+  },
+  ...COMMAND_TOOLS,
+  ...REPO_TEST_TOOLS,
+  ...PR_TOOLS,
+  ...CASE_TOOLS,
+  ...API_TOOLS,
+  ...EXPLORE_TOOLS,
+  ...QUALITY_TOOLS,
+  ...CAPABILITY_TOOLS,
+  ...NOTIFY_TOOLS,
+]
+
+/** The setup the agent should know about: where it works, which systems are configured, and the defaults. */
+/** Product knowledge files, for the agent to read the ones a request needs. */
+function knowledgeNotes(cfg: AppConfig): string {
+  if (!cfg.knowledge) return ""
+  const files = readKnowledge(cfg.knowledge.dir)
+  return files.length
+    ? [`Product knowledge (the team's notes about the product, in ${cfg.knowledge.dir}): read the files a request needs before planning tests, writing test cases, judging results, or answering about the product. The live application wins where they disagree.`, ...knowledgeIndex(files)].join("\n")
+    : `No product knowledge yet: the team can describe the product, roles, rules, and test data in ${cfg.knowledge.dir} (forgeqe init adds templates).`
+}
+
+export function environmentNotes(ctx: Pick<ToolContext, "config" | "cwd" | "url">): string {
+  const { config: cfg } = ctx
+  const s = cfg.sources
+  const systems = [
+    s.ado ? `Azure DevOps: ${s.ado.orgUrl}${s.ado.project ? `, project ${s.ado.project}` : ", every project"} (token in ${s.ado.tokenEnv})` : "",
+    s.jira ? `Jira ${s.jira.cloud ? "Cloud" : "Server/Data Center"}: ${s.jira.url} (${s.jira.cloud ? `${s.jira.emailEnv} + ` : ""}${s.jira.tokenEnv})` : "",
+    s.xray.url && process.env[s.xray.clientIdEnv] ? `Xray Cloud (${s.xray.clientIdEnv}, ${s.xray.clientSecretEnv})` : s.jira && !s.jira.cloud ? "Xray Server/Data Center through the Jira settings" : "",
+    s.testrail ? `TestRail: ${s.testrail.url}${s.testrail.projectId ? `, project ${s.testrail.projectId}` : ""}` : "",
+    s.zephyr ? `Zephyr Scale Cloud${s.zephyr.projectKey ? `, project ${s.zephyr.projectKey}` : ""}` : "",
+    s.qtest ? `qTest: ${s.qtest.url}, project ${s.qtest.projectId}` : "",
+  ].filter(Boolean)
+  const keys = [
+    cfg.llm.apiKeyEnv,
+    s.ado?.tokenEnv,
+    s.jira?.emailEnv,
+    s.jira?.tokenEnv,
+    s.xray.clientIdEnv,
+    s.xray.clientSecretEnv,
+    s.confluence?.emailEnv,
+    s.confluence?.tokenEnv,
+    s.testrail?.emailEnv,
+    s.testrail?.tokenEnv,
+    s.zephyr?.tokenEnv,
+    s.qtest?.tokenEnv,
+    ...cfg.logins.flatMap((l) => [l.usernameEnv, l.passwordEnv, l.totpEnv]),
+    cfg.monitor.alerts.teams?.webhookEnv,
+    cfg.monitor.alerts.email?.usernameEnv,
+    cfg.monitor.alerts.email?.passwordEnv,
+  ].filter((k, i, all): k is string => Boolean(k && process.env[k] && all.indexOf(k) === i))
+  const bugs = s.bugs
+    ? `Failed cases get a ${s.bugs.system === "jira" ? `Jira ${s.bugs.type} in ${s.bugs.project}` : `Azure DevOps ${s.bugs.type}`} when results are posted back; a case still failing gets a comment on its open bug instead of a new one.`
+    : ""
+  const m = cfg.monitor
+  const channels = [m.alerts.teams ? `Teams (${m.alerts.teams.webhookEnv})` : "", m.alerts.email ? `email to ${m.alerts.email.to.join(", ")} via ${m.alerts.email.host}` : ""].filter(Boolean)
+  const monitor = m.checks.length || channels.length
+    ? `Monitoring (monitor: in forgeqe.yaml): ${m.checks.length ? `checks ${m.checks.join(" ")}` : "no checks yet"}, every ${Math.round(m.everyMs / 60_000)} min, alerts to ${channels.length ? channels.join(" and ") : "nobody yet"}.`
+    : ""
+  const browserSkills = skillsFor(loadSkills(cfg.skills, ctx.cwd), "browser")
+  const skills = browserSkills.length
+    ? [`Browser skills (pass the ones a goal needs as skills to browser_run or run_test_cases):`, ...catalogLines(browserSkills)].join("\n")
+    : ""
+  return [
+    `Working directory: ${ctx.cwd}`,
+    `Browser runs are saved under ${cfg.export.outDir}; page memory is in ${cfg.memory.dir}.`,
+    `Test case systems configured: ${systems.length ? systems.join("; ") : "none (files and text still work)"}.`,
+    s.confluence ? `Confluence: ${s.confluence.url}${s.confluence.space ? `, space ${s.confluence.space}` : ""} (read_confluence).` : "",
+    `Sprints (list_sprints, find_tests sprint): ${[s.ado ? "Azure DevOps iterations" : "", s.jira ? "Jira scrum boards" : ""].filter(Boolean).join(" and ") || "none configured; ask the user for dates"}.`,
+    `Suites: ${cfg.suite.parallel} browser(s) at once by default; results ${s.writeBack ? "are" : "are not"} posted back to the source by default.`,
+    bugs,
+    (s.ado || s.jira) && s.saveCases !== false
+      ? "Test cases you write from an Azure DevOps or Jira story are saved there with save_test_cases, linked to the story, unless the user says not to."
+      : (s.ado || s.jira)
+        ? "Test cases you write from a story are not saved anywhere unless the user asks (sources.save_cases is false)."
+        : "",
+    allLogins(cfg).length
+      ? `Saved logins (the browser agent signs in with them and reuses the session; never ask the user for these passwords or put them in goals): ${allLogins(cfg).map((l) => `${l.name} for ${l.domains.join(", ")}${sessionLogins().some((s) => s.name === l.name) ? " (remembered this session)" : ""}`).join("; ")}.`
+      : "",
+    `Test commands time out after ${cfg.code.testTimeoutSeconds}s; give up on a test after ${cfg.code.maxAttempts} failed runs.`,
+    cfg.code.testCommand ? `The repository's test command (code.test_command): ${cfg.code.testCommand}` : "",
+    monitor,
+    cfg.notify
+      ? `Notification channels (post to them with notify only when the user asks; each also gets its automatic events from runs outside the shell): ${cfg.notify.channels.map((c) => `${c.name} (${[c.teams ? "Teams" : "", c.email ? "email" : ""].filter(Boolean).join(" and ")}; automatic: ${c.on.join(", ") || "none"})`).join("; ")}.`
+      : "",
+    `Browser model profile: ${cfg.activeProfile} (${cfg.llm.provider}/${cfg.llm.deployment || cfg.llm.model}).`,
+    keys.length ? `Set in ForgeQE's environment (names only, usable with set_ci_secret): ${keys.join(", ")}.` : "",
+    ctx.url ? `The user pinned this start URL for browser runs: ${ctx.url}` : "",
+    skills,
+    domainNotes(cfg),
+    knowledgeNotes(cfg),
+    capabilityIndex(cfg),
+  ]
+    .filter(Boolean)
+    .join("\n")
+}