@capagents/forgeqe 1.3.1 → 2.0.0

package/src/mcp/desktoptools.ts

@@ -0,0 +1,334 @@
+import type { DesktopEvent, DesktopResult } from "../desktop/bridge.ts"
+import { mkdirSync } from "node:fs"
+import path from "node:path"
+
+import { engineValidate, proposeEdit, writeEdit } from "../desktop/edit.ts"
+import { allowedWorkflow, checkApp, checkDesktopConfig, checkVariables, desktopOutDir, exploreGoal, hasModel, privateDesktopSecrets, recordByHand, recordingNotes, replayWorkflow, visionProblem } from "../desktop/run.ts"
+import { NOT_WINDOWS, desktopDoctor } from "../desktop/setup.ts"
+import { activeEnvironment, environmentBrief, exportEnvironment, withEnvironment } from "../environments.ts"
+import type { McpTool, ToolContext } from "./tools.ts"
+
+/** The apps of the test environments, and Windows thick-client apps (docs/DESKTOP.md): explore a goal, replay a saved workflow. */
+
+const clip = (s: string | undefined, n: number) => {
+  const t = (s || "").trim()
+  return t.length <= n ? t : `${t.slice(0, n - 1)}…`
+}
+
+function onWindows(platform: string = process.platform): string | null {
+  return platform === "win32" ? null : NOT_WINDOWS
+}
+
+export function stepEvents(ctx: ToolContext): (e: DesktopEvent) => void {
+  return (e) => {
+    if (e.type === "step") ctx.emit?.({ type: "info", text: `${e.ok ? "✓" : "✗"} ${e.index} ${e.op}${e.healed_target ? " (healed)" : ""}${e.error ? `: ${clip(e.error, 200)}` : ""}`, ok: e.ok })
+    else if (e.type === "log" && e.text && e.level !== "debug") ctx.emit?.({ type: "info", text: clip(e.text, 300), ...(e.level === "error" ? { ok: false } : {}) })
+  }
+}
+
+/** Ask the user before the desktop's mouse and keyboard are taken over; where ForgeQE cannot ask, the caller confirms. */
+export async function confirmed(ctx: ToolContext, args: Record<string, any>, title: string, detail: string): Promise<{ go: true } | { go: false; answer: Record<string, unknown> }> {
+  if (ctx.ask) {
+    const choice = await ctx.ask({
+      title,
+      detail,
+      options: [
+        { id: "start", label: "Start" },
+        { id: "no", label: "Don't start" },
+      ],
+    })
+    return choice === "start" ? { go: true } : { go: false, answer: { ran: false, reason: "The user chose not to start it." } }
+  }
+  if (args.confirmed === true) return { go: true }
+  return {
+    go: false,
+    answer: {
+      ran: false,
+      needs_confirmation: true,
+      what: `${title} ${detail}`,
+      next_step: "Tell the user this takes over the desktop's mouse and keyboard, and call again with confirmed: true only after they agree.",
+    },
+  }
+}
+
+export function stepSummary(r: DesktopResult) {
+  return (r.steps || []).map((s) => ({ index: s.index, op: s.op, ok: s.ok, ...(s.error ? { error: clip(s.error, 300) } : {}), ...(s.healed_target ? { healed_to: s.healed_target } : {}) }))
+}
+
+export const DESKTOP_TOOLS: McpTool[] = [
+  {
+    name: "test_apps",
+    description:
+      "The test environments (env.yaml) and the apps in one: web apps with their URL, Windows desktop apps, and mobile apps, each with what it is for, plus the environment's variables and the secrets its workflows may type, and which apps can run on this machine. Call it first for any request that names an app or an environment, and to plan a scenario that moves between apps (e.g. order on the web shop, invoice in the desktop billing app): pick the apps by their descriptions, never invent a URL or path.",
+    inputSchema: {
+      type: "object",
+      properties: { env: { type: "string", description: "An environment by name (default: the active one)" } },
+    },
+    async run(args, ctx) {
+      const cfg = withEnvironment(ctx.config, args.env ? String(args.env) : undefined)
+      const env = activeEnvironment(cfg)
+      const windows = process.platform === "win32"
+      const doc = windows ? desktopDoctor() : undefined
+      const apps = env
+        ? Object.values(env.apps).map((a) => ({
+            name: a.name,
+            kind: a.kind,
+            ...(a.description ? { description: a.description } : {}),
+            ...(a.url ? { url: a.url } : {}),
+            ...(a.path ? { path: a.path } : {}),
+            ...(a.platform ? { platform: a.platform, app_id: a.appId } : {}),
+            ...(a.login ? { login: a.login } : {}),
+            usable_here: a.kind === "desktop" ? windows : true,
+            ...(a.kind === "desktop" && !windows ? { why_not: NOT_WINDOWS } : {}),
+            tool:
+              a.kind === "web"
+                ? "browser_run with app"
+                : a.kind === "desktop"
+                  ? "desktop_explore / desktop_record / desktop_replay with app"
+                  : a.kind === "mobile"
+                    ? "mobile_explore / mobile_replay with app (Appium or Maestro); mobile_maestro for the team's Maestro flows"
+                    : "API tests (run_api_scenarios, run_api_contracts)",
+          }))
+        : []
+      // desktop.apps in forgeqe.yaml itself, outside any environment.
+      const extraDesktop = Object.keys(cfg.desktop.apps).filter((n) => !env?.apps[n])
+      return {
+        environment: env ? { name: env.name, ...(env.description ? { description: env.description } : {}) } : null,
+        environments: cfg.environments ? Object.values(cfg.environments.all).map((e) => ({ name: e.name, ...(e.description ? { description: e.description } : {}), active: e.name === env?.name })) : [],
+        apps,
+        ...(extraDesktop.length ? { other_desktop_apps: extraDesktop } : {}),
+        variables: env?.variables || {},
+        secrets: cfg.desktop.secrets,
+        ...(cfg.mobile.secrets.length ? { mobile_secrets: cfg.mobile.secrets } : {}),
+        refused_secrets: privateDesktopSecrets(cfg),
+        windows,
+        desktop_engine_ready: Boolean(doc?.ready),
+        desktop_explore_ready: Boolean(doc?.ufo),
+        ...(!cfg.environments ? { next_step: "No environments are configured: tell the user to run forgeqe init (it writes env.yaml) and list their apps there." } : apps.length || extraDesktop.length ? {} : { next_step: `Environment ${env?.name || ""} has no apps: tell the user to add them to ${cfg.environments.file}.` }),
+      }
+    },
+  },
+  {
+    name: "use_environment",
+    description:
+      "Switch the test environment (env.yaml) for the rest of this session: every later browser run, test case run, API test, desktop run, and the tests ForgeQE runs (FORGEQE_APP_*_URL) use it. Use when the user says to work in another environment (\"now in UAT\"); for a single call, pass env to that tool instead.",
+    inputSchema: {
+      type: "object",
+      properties: { env: { type: "string", description: "The environment's name, from test_apps" } },
+      required: ["env"],
+    },
+    line: (args) => `environment ${String(args.env || "")}`,
+    async run(args, ctx) {
+      const name = String(args.env || "").trim()
+      if (!name) throw new Error("env is required.")
+      const switched = withEnvironment(ctx.config, name)
+      // The session shares this config object: later tool calls see the new environment.
+      Object.assign(ctx.config, switched)
+      exportEnvironment(ctx.config)
+      process.env.FORGEQE_ENV = name
+      ctx.emit?.({ type: "info", text: `Environment: ${name}`, ok: true })
+      return { environment: name, brief: environmentBrief(ctx.config, "agent") }
+    },
+  },
+  {
+    name: "desktop_explore",
+    description:
+      "Carry out a goal in a Windows desktop app (from test_apps) with UFO² on this machine's desktop, and save it as a replayable workflow with checks of the outcome. Asks the user first. Returns the workflow, steps, checks, values shown at the end (for the next app of a scenario), and the report. Windows only; needs a vision model.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        goal: { type: "string", description: "What to do in the app, in the user's words" },
+        app: { type: "string", description: "A desktop app's name, from test_apps" },
+        name: { type: "string", description: "A name for the workflow" },
+        env: { type: "string", description: "The test environment (default: the active one)" },
+        confirmed: { type: "boolean", description: "Only where ForgeQE cannot ask: the user agreed" },
+      },
+      required: ["goal", "app"],
+    },
+    line: (args) => `desktop explore ${String(args.app || "")}: ${clip(String(args.goal || ""), 80)}`,
+    async run(args, ctx) {
+      const notHere = onWindows()
+      if (notHere) return { ran: false, reason: notHere }
+      const goal = String(args.goal || "").trim()
+      const app = String(args.app || "").trim()
+      if (!goal || !app) throw new Error("goal and app are required.")
+      const cfg = withEnvironment(ctx.config, args.env ? String(args.env) : undefined)
+      checkDesktopConfig(cfg, true)
+      checkApp(cfg, app)
+      const problem = visionProblem(cfg.activeProfile, cfg.llm)
+      if (problem) return { ran: false, reason: problem }
+      const ok = await confirmed(ctx, args, `UFO² will control this desktop's mouse and keyboard in ${app} to: ${clip(goal, 200)}.`, "It acts in that app's windows only (no shell commands). Use a test machine and a test account.")
+      if (!ok.go) return ok.answer
+      const outDir = desktopOutDir(cfg, "explore")
+      const { result, report } = await exploreGoal({ cfg, goal, app, name: args.name ? String(args.name) : undefined, outDir, signal: ctx.signal, onEvent: stepEvents(ctx), log: (t) => ctx.emit?.({ type: "info", text: t }) })
+      return {
+        ran: true,
+        ok: result.ok,
+        workflow: result.workflow || undefined,
+        recorded_steps: result.recorded ?? 0,
+        checks: result.checks ?? 0,
+        values: result.values && Object.keys(result.values).length ? result.values : undefined,
+        not_recorded: result.skipped?.length ? result.skipped : undefined,
+        refused: result.refused?.length ? result.refused.map((r) => r.action) : undefined,
+        ufo_judged_done: result.ufo_complete ?? undefined,
+        error: result.error || undefined,
+        report,
+        next_step: result.workflow
+          ? `Offer desktop_replay with workflow ${result.workflow} to check it runs without a model.${(result.checks ?? 0) === 0 ? " It has no checks of the outcome: say so, and suggest adding expect steps." : ""}`
+          : "Say what UFO did and did not do; suggest a clearer goal or checking the app's controls with Inspect.exe.",
+      }
+    },
+  },
+  {
+    name: "desktop_replay",
+    description:
+      "Replay a desktop workflow in its Windows app with no model, checking its expect steps. A moved control is healed with one model call and reported, never written. Asks the user first. Returns each step's result, heals, and the report. Windows only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workflow: { type: "string", description: "The workflow file, in the working or reports folder" },
+        variables: { type: "object", additionalProperties: { type: "string" }, description: "Values for its {{name}} variables" },
+        heal: { type: "boolean", description: "Heal a moved control (default: desktop.heal)" },
+        env: { type: "string", description: "The test environment (default: the active one)" },
+        confirmed: { type: "boolean", description: "Only where ForgeQE cannot ask: the user agreed" },
+      },
+      required: ["workflow"],
+    },
+    line: (args) => `desktop replay ${String(args.workflow || "")}`,
+    async run(args, ctx) {
+      const notHere = onWindows()
+      if (notHere) return { ran: false, reason: notHere }
+      const cfg = withEnvironment(ctx.config, args.env ? String(args.env) : undefined)
+      checkDesktopConfig(cfg, false)
+      const workflow = allowedWorkflow(String(args.workflow || ""), [ctx.cwd, cfg.export.outDir])
+      const variables = checkVariables(args.variables)
+      const ok = await confirmed(ctx, args, `ForgeQE will replay ${workflow} on this desktop's mouse and keyboard.`, "It starts the workflow's app from forgeqe.yaml and acts in its windows only.")
+      if (!ok.go) return ok.answer
+      const heal = (args.heal === undefined ? cfg.desktop.heal : args.heal === true) && hasModel(cfg)
+      const outDir = desktopOutDir(cfg, "replay")
+      const { result, report } = await replayWorkflow({ cfg, workflow, variables, heal, outDir, signal: ctx.signal, onEvent: stepEvents(ctx), log: (t) => ctx.emit?.({ type: "info", text: t }) })
+      return {
+        ran: true,
+        ok: result.ok,
+        stopped: result.stopped || undefined,
+        steps: stepSummary(result),
+        total: result.total,
+        heals: result.heals?.length ? result.heals : undefined,
+        error: result.error || undefined,
+        report,
+        next_step: result.heals?.length
+          ? `Tell the user which locators were healed; they can write them into the workflow with: forgeqe desktop replay "${workflow}" --accept-heals`
+          : result.ok
+            ? undefined
+            : "Say which step failed and why, from its error and the report's screenshot.",
+      }
+    },
+  },
+  {
+    name: "desktop_record",
+    description:
+      "Record a desktop workflow by hand, with no model: ForgeQE starts the Windows app and saves the user's clicks, typing and keys as workflow.yaml. Ctrl+Shift+F11 over a control adds a check of its text; Ctrl+Shift+F12 finishes. Passwords are saved as {{secret:NAME}}. Asks the user first. Windows only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        app: { type: "string", description: "A desktop app's name, from test_apps" },
+        name: { type: "string", description: "A name for the workflow" },
+        env: { type: "string", description: "The test environment (default: the active one)" },
+        confirmed: { type: "boolean", description: "Only where ForgeQE cannot ask: the user agreed" },
+      },
+      required: ["app"],
+    },
+    line: (args) => `desktop record ${String(args.app || "")}`,
+    async run(args, ctx) {
+      const notHere = onWindows()
+      if (notHere) return { ran: false, reason: notHere }
+      const app = String(args.app || "").trim()
+      if (!app) throw new Error("app is required.")
+      const cfg = withEnvironment(ctx.config, args.env ? String(args.env) : undefined)
+      checkDesktopConfig(cfg, false)
+      checkApp(cfg, app)
+      const ok = await confirmed(
+        ctx,
+        args,
+        `ForgeQE will start ${app} and record what you do in it.`,
+        "Do the steps yourself. Ctrl+Shift+F11 over a control adds a check of what it shows; Ctrl+Shift+F12 or closing the app finishes. Only clicks and keys in the app's own windows are recorded; password fields are saved as secret names, never as what you type.",
+      )
+      if (!ok.go) return ok.answer
+      const outDir = desktopOutDir(cfg, "record")
+      const onEvent = (e: DesktopEvent) => {
+        if (e.type === "recorded") ctx.emit?.({ type: "info", text: `● ${e.index} ${e.op}${e.keys ? ` ${e.keys}` : ""}${e.target ? ` ${clip(String(e.target.name || e.target.automation_id || ""), 60)}` : ""}` })
+        else stepEvents(ctx)(e)
+      }
+      const { result, report } = await recordByHand({ cfg, app, name: args.name ? String(args.name) : undefined, outDir, signal: ctx.signal, onEvent, log: (t) => ctx.emit?.({ type: "info", text: t }) })
+      const notes = recordingNotes(cfg, result)
+      return {
+        ran: true,
+        ok: result.ok,
+        workflow: result.workflow || undefined,
+        recorded_steps: result.recorded ?? 0,
+        checks: result.checks ?? 0,
+        steps: (result.steps || []).map((s) => ({ index: s.index, op: s.op, ...(s.target ? { target: s.target } : {}) })),
+        not_recorded: result.skipped?.length ? result.skipped : undefined,
+        secrets: result.secrets?.length ? result.secrets : undefined,
+        stopped_by: result.stopped_by || undefined,
+        notes: notes.length ? notes : undefined,
+        error: result.error || undefined,
+        report,
+        next_step: result.workflow ? `Show the steps, pass on the notes, and offer desktop_replay with workflow ${result.workflow}.` : "Say nothing was recorded, and why (the error), and offer to start again.",
+      }
+    },
+  },
+  {
+    name: "desktop_edit_workflow",
+    description:
+      "Change a desktop or mobile workflow after a failed replay or on request: timeout, retries, a wait_for step, a dialog to dismiss, a healed target, a text, steps, variables. Step numbers are the replay report's. Validated; the user sees the diff and is asked before it is written.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workflow: { type: "string", description: "The workflow file, in the working or reports folder" },
+        reason: { type: "string", description: "Why, in one sentence for the user" },
+        changes: {
+          type: "array",
+          description:
+            'In order: {op:"set"|"unset", field:"timeout"|"retries", value?, step?} (no step: the workflow); {op:"set_step", step, field, value} (field: target, text, value, keys, seconds, direction, gone, image, tolerance, ignore, note, timeout, retries); {op:"add_dismiss", target}; {op:"insert_step", before|after, step}; {op:"remove_step", step}; {op:"set_variable", name, value}.',
+          items: { type: "object" },
+        },
+        confirmed: { type: "boolean", description: "Only where ForgeQE cannot ask: the user agreed to the diff" },
+      },
+      required: ["workflow", "changes"],
+    },
+    line: (args) => `desktop edit ${String(args.workflow || "")}`,
+    async run(args, ctx) {
+      const cfg = ctx.config
+      const workflow = allowedWorkflow(String(args.workflow || ""), [ctx.cwd, cfg.export.outDir])
+      let edit
+      try {
+        edit = await proposeEdit(workflow, args.changes, ctx.validateDesktopWorkflow || engineValidate)
+      } catch (e) {
+        return { written: false, error: (e as Error).message, next_step: "Fix the changes (the error says which) and call again; nothing was written." }
+      }
+      if (edit.before === edit.after) return { written: false, reason: "The changes leave the workflow as it is." }
+      const reason = clip(String(args.reason || ""), 300)
+      const shown = { workflow, changes: edit.summary, diff: edit.diff }
+      if (ctx.ask) {
+        const choice = await ctx.ask({
+          title: `Change ${path.basename(workflow)}?`,
+          detail: reason || undefined,
+          lines: [...edit.summary.map((l) => `• ${l}`), "", ...edit.diff.slice(0, 80)],
+          options: [
+            { id: "write", label: "Yes, write the change" },
+            { id: "no", label: "No, leave the workflow as it is" },
+          ],
+        })
+        if (choice !== "write") return { ...shown, written: false, reason: "The user chose not to change the workflow." }
+      } else if (args.confirmed !== true) {
+        return { ...shown, written: false, needs_confirmation: true, next_step: "Show the user this diff, and call again with the same changes and confirmed: true only after they agree." }
+      }
+      const backupDir = path.join(cfg.export.outDir, "desktop-edits")
+      mkdirSync(backupDir, { recursive: true })
+      const backup = writeEdit(workflow, edit, backupDir)
+      ctx.emit?.({ type: "info", text: `Updated ${workflow}`, ok: true })
+      return { ...shown, written: true, backup, next_step: `Offer desktop_replay with workflow ${workflow} to check the fix.` }
+    },
+  },
+]

package/src/mcp/mobiletools.ts

@@ -0,0 +1,132 @@
+import { allowedWorkflow, checkVariables, visionProblem } from "../desktop/run.ts"
+import { withEnvironment } from "../environments.ts"
+import { checkMobileApp, checkMobileConfig, exploreMobile, hasModel, maestroFlowFiles, mobileOutDir, replayMobile, runMaestroFlows } from "../mobile/run.ts"
+import { confirmed, stepEvents, stepSummary } from "./desktoptools.ts"
+import type { McpTool } from "./tools.ts"
+
+/** Android and iOS apps (docs/MOBILE.md): explore a goal through Appium, replay a workflow on Appium or Maestro, run the team's Maestro flows. */
+
+const clip = (s: string | undefined, n: number) => {
+  const t = (s || "").trim()
+  return t.length <= n ? t : `${t.slice(0, n - 1)}…`
+}
+
+export const MOBILE_TOOLS: McpTool[] = [
+  {
+    name: "mobile_explore",
+    description:
+      "Carry out a goal in an Android or iOS app (from test_apps) through Appium, and save it as a replayable workflow with checks of the outcome. Asks the user first. Returns the workflow, steps, checks, values shown at the end (for the next app of a scenario), and the report. Needs Appium and a vision model.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        goal: { type: "string", description: "What to do in the app, in the user's words" },
+        app: { type: "string", description: "A mobile app's name, from test_apps" },
+        name: { type: "string", description: "A name for the workflow" },
+        env: { type: "string", description: "The test environment (default: the active one)" },
+        confirmed: { type: "boolean", description: "Only where ForgeQE cannot ask: the user agreed" },
+      },
+      required: ["goal", "app"],
+    },
+    line: (args) => `mobile explore ${String(args.app || "")}: ${clip(String(args.goal || ""), 80)}`,
+    async run(args, ctx) {
+      const goal = String(args.goal || "").trim()
+      const app = String(args.app || "").trim()
+      if (!goal || !app) throw new Error("goal and app are required.")
+      const cfg = withEnvironment(ctx.config, args.env ? String(args.env) : undefined)
+      checkMobileConfig(cfg)
+      checkMobileApp(cfg, app)
+      if (!hasModel(cfg)) return { ran: false, reason: "No model is set up in llms.json; explore needs one. Replay and Maestro flows need none." }
+      const problem = visionProblem(cfg.activeProfile, cfg.llm)
+      if (problem) return { ran: false, reason: problem.replace("the desktop agent", "the mobile agent") }
+      const ok = await confirmed(ctx, args, `The mobile agent will operate ${app} on the device to: ${clip(goal, 200)}.`, `Through Appium at ${cfg.mobile.appium.url}. Use a test device and a test account.`)
+      if (!ok.go) return ok.answer
+      const outDir = mobileOutDir(cfg, "explore")
+      const { result, report } = await exploreMobile({ cfg, goal, app, name: args.name ? String(args.name) : undefined, outDir, signal: ctx.signal, onEvent: stepEvents(ctx), log: (t) => ctx.emit?.({ type: "info", text: t }) })
+      return {
+        ran: true,
+        ok: result.ok,
+        workflow: result.workflow || undefined,
+        recorded_steps: result.recorded ?? 0,
+        checks: result.checks ?? 0,
+        values: result.values && Object.keys(result.values).length ? result.values : undefined,
+        error: result.error || undefined,
+        report,
+        next_step: result.workflow
+          ? `Offer mobile_replay with workflow ${result.workflow} (driver appium or maestro).${(result.checks ?? 0) === 0 ? " It has no checks of the outcome: say so." : ""}`
+          : "Say what was and was not done; suggest a clearer goal.",
+      }
+    },
+  },
+  {
+    name: "mobile_replay",
+    description:
+      "Replay a mobile workflow (forgeqe-mobile-v1) with no model: on Appium step by step (a moved control is healed and reported, never written), or on Maestro. Asks the user first. Returns each step's result and the report.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workflow: { type: "string", description: "The workflow file, in the working or reports folder" },
+        variables: { type: "object", additionalProperties: { type: "string" }, description: "Values for its {{name}} variables" },
+        driver: { type: "string", enum: ["appium", "maestro"], description: "Default: mobile.driver" },
+        heal: { type: "boolean", description: "Appium: heal a moved control (default: mobile.heal)" },
+        env: { type: "string", description: "The test environment (default: the active one)" },
+        confirmed: { type: "boolean", description: "Only where ForgeQE cannot ask: the user agreed" },
+      },
+      required: ["workflow"],
+    },
+    line: (args) => `mobile replay ${String(args.workflow || "")}`,
+    async run(args, ctx) {
+      const cfg = withEnvironment(ctx.config, args.env ? String(args.env) : undefined)
+      checkMobileConfig(cfg)
+      const workflow = allowedWorkflow(String(args.workflow || ""), [ctx.cwd, cfg.export.outDir])
+      const variables = checkVariables(args.variables)
+      const driver = args.driver === undefined ? cfg.mobile.driver : args.driver
+      if (driver !== "appium" && driver !== "maestro") throw new Error("driver must be appium or maestro.")
+      const ok = await confirmed(ctx, args, `ForgeQE will replay ${workflow} on the device with ${driver}.`, "It starts the workflow's app from the environment or forgeqe.yaml mobile.apps and acts in it only.")
+      if (!ok.go) return ok.answer
+      const heal = args.heal === undefined ? cfg.mobile.heal : args.heal === true
+      const outDir = mobileOutDir(cfg, "replay")
+      const { result, report } = await replayMobile({ cfg, workflow, variables, heal, driver, outDir, signal: ctx.signal, onEvent: stepEvents(ctx), log: (t) => ctx.emit?.({ type: "info", text: t }) })
+      return {
+        ran: true,
+        ok: result.ok,
+        driver,
+        steps: stepSummary(result),
+        total: result.total,
+        heals: result.heals?.length ? result.heals : undefined,
+        error: result.error || undefined,
+        report,
+        next_step: result.heals?.length
+          ? "Tell the user which locators were healed; desktop_edit_workflow (set_step target) writes them into the workflow when they agree."
+          : result.ok
+            ? undefined
+            : "Say which step failed and why. When the app was slow or a dialog was in the way, fix the workflow with desktop_edit_workflow (it edits mobile workflows too).",
+      }
+    },
+  },
+  {
+    name: "mobile_maestro",
+    description:
+      "Run the team's own Maestro flows (files or folders in the working folder). Each is checked first: only UI commands pass (no scripts, JavaScript, AI commands or file writes). Asks the user first. Returns each flow's result.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        flows: { type: "array", items: { type: "string" }, description: "Flow files or folders" },
+        env: { type: "string", description: "The test environment (default: the active one)" },
+        confirmed: { type: "boolean", description: "Only where ForgeQE cannot ask: the user agreed" },
+      },
+      required: ["flows"],
+    },
+    line: (args) => `maestro ${Array.isArray(args.flows) ? args.flows.join(" ") : ""}`,
+    async run(args, ctx) {
+      const cfg = withEnvironment(ctx.config, args.env ? String(args.env) : undefined)
+      checkMobileConfig(cfg)
+      if (!Array.isArray(args.flows) || !args.flows.length || !args.flows.every((f: unknown) => typeof f === "string")) throw new Error("flows must be a list of files or folders.")
+      const flows = maestroFlowFiles(args.flows as string[], ctx.cwd)
+      const ok = await confirmed(ctx, args, `ForgeQE will run ${flows.length} Maestro flow${flows.length === 1 ? "" : "s"} on the device.`, "Each is checked against the allowlist first.")
+      if (!ok.go) return ok.answer
+      const outDir = mobileOutDir(cfg, "maestro")
+      const { result, report } = await runMaestroFlows({ cfg, flows, root: ctx.cwd, outDir, signal: ctx.signal, onEvent: stepEvents(ctx), log: (t) => ctx.emit?.({ type: "info", text: t }) })
+      return { ran: true, ok: result.ok, flows: result.flows || [], checked: result.checked?.length, error: result.error || undefined, report }
+    },
+  },
+]

package/src/mcp/reporttools.ts

@@ -84,9 +84,24 @@ ${body}
 `
 }
 
-/** The summary as HTML, with raw HTML in it shown as text so a report can never run script. */
+/** The summary as HTML, with raw HTML in it shown as text and only web links kept, so a report can never run script. */
 export function summaryHtml(markdown: string): string {
-  return Bun.markdown.html(markdown.replace(/<(?=[A-Za-z/!?])/g, "&lt;"))
+  const html = Bun.markdown.html(markdown.replace(/<(?=[A-Za-z/!?])/g, "&lt;"))
+  return html.replace(/\s(href|src)="([^"]*)"/g, (whole, _attr: string, value: string) => (linkAllowed(value) ? whole : ""))
+}
+
+const codePoint = (n: number) => (n <= 0x10ffff ? String.fromCodePoint(n) : "")
+
+/** A link a report may keep: http(s), mailto, or one with no scheme (an anchor or a relative path). */
+function linkAllowed(attr: string): boolean {
+  const url = attr
+    .replace(/&#x([0-9a-f]+);?/gi, (_, h: string) => codePoint(parseInt(h, 16)))
+    .replace(/&#(\d+);?/g, (_, d: string) => codePoint(Number(d)))
+    .replace(/&quot;/g, '"')
+    .replace(/&amp;/g, "&")
+    .replace(/[\u0000-\u0020\u007f]/g, "")
+  const scheme = /^([^/?#]*?):/.exec(url)?.[1]
+  return !scheme || /^(?:https?|mailto)$/i.test(scheme)
 }
 
 const MAX_ROWS = 5000

package/src/mcp/repotests.ts

@@ -5,6 +5,10 @@ import { privateEnvNames } from "../childEnv.ts"
 import { findSprint, listSprints, recentSprints, sprintLabel, type Sprint } from "../cases/sprints.ts"
 import { findTests, loadSelection, resultsCard, runSelection, selectionCard, type TestRange } from "../code/find.ts"
 import { CAUSE_TEXT, flakyReport, matchTest, RELEASE_AFTER, setQuarantine } from "../code/history.ts"
+import { containersOf, startOrder } from "../containers/config.ts"
+import { ensureServices, findRuntime } from "../containers/run.ts"
+import { containerTestRunner } from "../containers/tests.ts"
+import { containerExec } from "./containertools.ts"
 import type { McpTool, ToolContext } from "./tools.ts"
 
 const clip = (s: string | undefined, n: number) => {
@@ -144,6 +148,7 @@ export const REPO_TEST_TOOLS: McpTool[] = [
         selection_id: { type: "string", description: "From find_tests" },
         confirmed: { type: "boolean", description: "Only where ForgeQE cannot ask: the user agreed to run this list" },
         timeout_seconds: { type: "number", description: "Stop the run after this many seconds (default: code.test_timeout_seconds)" },
+        in_container: { type: "boolean", description: "Run them in containers.tests' image (Docker or Podman), with its services started first. Default: true when forgeqe.yaml sets containers.tests" },
       },
       required: ["selection_id"],
     },
@@ -151,10 +156,16 @@ export const REPO_TEST_TOOLS: McpTool[] = [
       const sel = loadSelection(ctx.config, String(args.selection_id))
       const n = sel.tests.length
       if (!n) return { ran: false, reason: "The selection has no tests." }
+      const tc = containersOf(ctx.config).tests
+      const inContainer = args.in_container === undefined ? Boolean(tc) : args.in_container === true
+      if (inContainer && !tc) return { ran: false, reason: "containers.tests is not set in forgeqe.yaml: it names the image the tests run in (docs/CONTAINERS.md)." }
+      const runtime = inContainer ? findRuntime(ctx.config) : null
+      if (inContainer && !runtime) return { ran: false, reason: "Docker or Podman is not on PATH, so the tests cannot run in a container. Run them on this machine with in_container: false, or install one." }
+      const where = inContainer && tc ? ` in a container (${tc.image}${tc.services.length ? `, with ${tc.services.join(", ")}` : ""})` : ""
       const what = `${n} test${n === 1 ? "" : "s"}`
       if (ctx.ask) {
         const choice = await ctx.ask({
-          title: `Run ${what}?`,
+          title: `Run ${what}${where}?`,
           detail: sel.runCommand,
           lines: [`Selected for "${sel.request}":`, ...sel.tests.slice(0, 20).map((t) => `  • ${t.name}`), ...(n > 20 ? [`  and ${n - 20} more`] : [])],
           options: [
@@ -169,12 +180,20 @@ export const REPO_TEST_TOOLS: McpTool[] = [
           needs_confirmation: true,
           tests: sel.tests.map((t) => t.name),
           run_command: sel.runCommand,
+          ...(where ? { where: where.trim() } : {}),
           next_step: "Show the user this list and ask whether to run it; call run_tests again with confirmed: true only after they say yes.",
         }
       }
-      ctx.emit?.({ type: "agent", event: { type: "code", kind: "info", text: `ForgeQE runs ${what}: ${sel.runCommand}` } })
+      ctx.emit?.({ type: "agent", event: { type: "code", kind: "info", text: `ForgeQE runs ${what}${where}: ${sel.runCommand}` } })
       const timeout = Number(args.timeout_seconds) > 0 ? Number(args.timeout_seconds) : ctx.config.code.testTimeoutSeconds
-      const r = await runSelection({ selection: sel, timeoutSeconds: timeout, signal: ctx.signal, runTest: ctx.runTest, hide: privateEnvNames(ctx.config), flaky: ctx.config.flaky })
+      let runTest = ctx.runTest
+      if (inContainer && tc && runtime) {
+        const rt = { cfg: ctx.config, runtime, exec: containerExec(), ...(ctx.signal ? { signal: ctx.signal } : {}), log: (text: string) => ctx.emit?.({ type: "info" as const, text }) }
+        const svc = await ensureServices(rt, startOrder(containersOf(ctx.config).services, tc.services))
+        if (svc.failed) return { ran: false, reason: `${svc.failed.service} did not start: ${svc.failed.error}`, logs: svc.failed.logs }
+        runTest = containerTestRunner(rt, sel.repo, [sel.dir])
+      }
+      const r = await runSelection({ selection: sel, timeoutSeconds: timeout, signal: ctx.signal, runTest, hide: privateEnvNames(ctx.config), flaky: ctx.config.flaky })
       ctx.emit?.({ type: "card", card: resultsCard(r, ctx.cwd) })
       const failed = r.tests.filter((t) => t.status === "failed")
       return {

package/src/mcp/routing.ts

@@ -1,14 +1,16 @@
 import { CAPABILITIES, type Capability } from "../capabilities/registry.ts"
 import { prompt } from "../prompts.ts"
+import type { CapabilityScope } from "./scope.ts"
 import type { McpTool } from "./tools.ts"
 
 /**
  * What ForgeQE's agent carries on every model call, and what it gets only when a task needs it.
  *
- * Every model call sends the system prompt and the tool definitions again. Tools stay listed in full: their
- * descriptions are how the agent chooses a tool and plans the task, and their arguments are needed for any call, so a
- * tool listed in one line cost an extra model call each time (measured: more tokens, not fewer). The playbook is
- * what moves: the sections of brain.md that a capability owns (`playbook`) leave the system prompt, an index of them
+ * Every model call sends the system prompt and the tool definitions again. A tool the agent has stays listed in full:
+ * its description is how the agent chooses a tool and plans the task, and its arguments are needed for any call, so a
+ * tool listed in one line cost an extra model call each time (measured: more tokens, not fewer). Which tools a turn
+ * has is the scope's job (src/mcp/scope.ts): the core capabilities and the ones the request is about. The playbook is
+ * what moves within them: the sections of brain.md that a capability owns (`playbook`) leave the system prompt, an index of them
  * stays, and the first result of one of the capability's tools in a session (or of a tool in `alsoAfter`) carries the
  * section. The `playbook` tool reads one before that. A section no capability owns stays in the system prompt, so a
  * section renamed in a team's own copy of brain.md is never lost.
@@ -84,7 +86,7 @@ export const brainParts = (): BrainParts => splitBrain(prompt("brain"))
  * Routing for one agent session: which playbooks it was given, and what goes with a result. The playbook text is read
  * once, when the session starts, like the system prompt.
  */
-export function createRouter(tools: McpTool[], opts: { caps?: Capability[]; brain?: string } = {}) {
+export function createRouter(tools: McpTool[], opts: { caps?: Capability[]; brain?: string; scope?: CapabilityScope } = {}) {
   const caps = opts.caps || CAPABILITIES
   const parts = splitBrain(opts.brain ?? prompt("brain"), caps)
   const given = new Set<string>()
@@ -100,8 +102,11 @@ export function createRouter(tools: McpTool[], opts: { caps?: Capability[]; brai
 
   return {
     parts,
+    /** Which tools each turn of this session gets (src/mcp/scope.ts); absent when every tool is always given. */
+    scope: opts.scope,
     /** What goes after an error of a tool: the playbooks of its capability this session has not had yet. */
     after(name: string): string {
+      opts.scope?.used(name)
       return block(give(playbooksFor(name)))
     },
     /**
@@ -109,6 +114,7 @@ export function createRouter(tools: McpTool[], opts: { caps?: Capability[]; brai
      * whatever reads it; appended to any other text.
      */
     attach(name: string, text: string): string {
+      opts.scope?.used(name)
       const books = give(playbooksFor(name))
       if (!books.length) return text
       const playbook = `Obey it for this task:\n\n${books.map((b) => b.text).join("\n\n")}`