@capagents/forgeqe 1.1.4 → 1.1.6

package/src/code/handoff.ts

@@ -6,6 +6,8 @@ import YAML from "yaml"
 import { caseMarkdown } from "../cases/goal.ts"
 import type { TestCase } from "../cases/types.ts"
 import { findPage, readPages, type MemoryElement, type MemoryPage } from "../memory.ts"
+import { describeMatches, exampleTest, membersLocating, outline, outlines, sameElement, type CodeGraph } from "./graph/graph.ts"
+import { fromMemory, type LocatorRef } from "./graph/locators.ts"
 import { replayOptions, replaySection, type Replay } from "./replay.ts"
 import { sliceFor } from "./slices.ts"
 
@@ -194,7 +196,7 @@ function stepLines(step: Step, n: number): string[] {
 }
 
 /** The steps in order, each group led by the browser agent's note from the step that performed it. */
-function stepsSection(steps: Step[], slices: Map<number, string[]> = new Map()): string[] {
+function stepsSection(steps: Step[], slices: Map<number, string[]> = new Map(), links: Map<number, string[]> = new Map()): string[] {
   if (!steps.length) return ["(no recorded steps)"]
   const lines: string[] = []
   let last = ""
@@ -202,7 +204,7 @@ function stepsSection(steps: Step[], slices: Map<number, string[]> = new Map()):
     const note = step.note || ""
     if (note && note !== last) lines.push(`> Browser agent: ${note}`)
     last = note
-    lines.push(...stepLines(step, i + 1), ...(slices.get(i + 1) || []))
+    lines.push(...stepLines(step, i + 1), ...(links.get(i + 1) || []), ...(slices.get(i + 1) || []))
   })
   return lines
 }
@@ -263,8 +265,8 @@ function stepSlices(steps: Step[], replay: Replay | null | undefined): Map<numbe
 }
 
 /**
- * The overlays the run closed, in order. They often show together (a sign-in prompt over a cookie banner), and a
- * click on one is blocked while another covers it, so the test closes them in this order from one handler.
+ * The overlays the run closed, in order. Several often show together (a sign-in prompt over a cookie banner), and a
+ * click on one is blocked while another covers it, so the test closes them in this order from one helper.
  */
 function overlaysSection(steps: Step[]): string[] {
   const closes = steps.filter((s) => s.op === "click" && s.overlay)
@@ -275,13 +277,13 @@ function overlaysSection(steps: Step[]): string[] {
     const container = o.id ? ` (container #${o.id})` : ""
     return `${i + 1}. ${o.kind || "overlay"}${o.name ? ` "${o.name}"` : ""}${container}: close with ${best ? playwrightOf(best) : s.best_locator || s.label}`
   })
-  return [
-    "## Overlays this run closed",
-    "",
-    "These covered the page and the run closed them in this order (the one on top first); the replay closed them the same way, as plain steps, and passed. In the test, write one helper that closes each of them that is visible, in this order, and call it after every navigation and right before each step that opens something (a date picker, a menu): an overlay can come back after a click. Use plain visibility checks and clicks; locator handlers and combined (or) locators block each other when two overlays show at once.",
-    "",
-    ...lines,
-  ]
+  // One overlay: the framework's own handler is the best practice. Several can stack, and a handler's click is then
+  // blocked by the other overlay while handlers do not run inside a handler, so one helper closes them top first.
+  const how =
+    closes.length === 1
+      ? "This covered the page and the run closed it; the replay closed it the same way, as a plain step, and passed. In the test, register the framework's overlay handler for it once, in the fixture or the base class setup (Playwright 1.42 and later: page.addLocatorHandler, Page.AddLocatorHandlerAsync), with the close control below as its locator. In a framework or version without one, write a helper that closes it when visible and call it after every navigation and right before each step that opens something (a date picker, a menu)."
+      : "These covered the page and the run closed them in this order (the one on top first); the replay closed them the same way, as plain steps, and passed. They can show at once, so do not use locator handlers or combined (or) locators for them: a handler's click is blocked while another overlay covers it, and handlers do not run inside a handler. Write one helper that closes each of them that is visible, in this order, and call it after every navigation and right before each step that opens something (a date picker, a menu): an overlay can come back after a click."
+  return ["## Overlays this run closed", "", how, "", ...lines]
 }
 
 /** The Playwright options of the replay pass that reached the run's final page: the test uses the same, so it gets the same page. */
@@ -380,7 +382,7 @@ function checkLine(c: Check | CheckResult, n: number): string {
 }
 
 /** The browser agent's checks, with the locator the replay found for each when it ran. */
-function checksSection(checks: Check[], replay?: Replay | null): string[] {
+function checksSection(checks: Check[], replay?: Replay | null, links: Map<number, string[]> = new Map()): string[] {
   if (!checks.length) return []
   const pass = replay?.passes.find((p) => p.reached && p.checks?.length) || replay?.passes.find((p) => p.checks?.length)
   const found = pass?.checks?.length === checks.length ? pass.checks : undefined
@@ -397,14 +399,77 @@ function checksSection(checks: Check[], replay?: Replay | null): string[] {
       : "The results the goal asks to check, with the text the page showed. Assert each of them, and add no other assertions.",
     "The text comes from one run: where it is live data (a price, a count, a date that moves), assert what the expected result says holds, not that value.",
     "",
-    ...merged.map((c, i) => checkLine(c, i + 1)),
+    ...merged.flatMap((c, i) => [checkLine(c, i + 1), ...(links.get(i + 1) || [])]),
+  ]
+}
+
+/**
+ * "In this repository" lines: the page-object members that already locate an element, found through page memory
+ * whichever locator they use (the run's getByRole('button', { name: 'Login' }) finds LoginPage.LoginButton = #login-button).
+ * A role locator whose name comes from a parameter matches too much to name here; code_element shows those.
+ */
+function repoLinks(graph: CodeGraph, pages: MemoryPage[], items: { locators?: Locator[]; page?: string }[], classes: Set<string> = new Set()): Map<number, string[]> {
+  const out = new Map<number, string[]>()
+  items.forEach((item, i) => {
+    const refs = (item.locators || []).map((l) => fromMemory(l.type, l.value)).filter((r): r is LocatorRef => Boolean(r))
+    if (!refs.length) return
+    const same = sameElement(pages, refs, item.page)
+    const matches = membersLocating(graph, same.refs).filter((m) => m.how !== "param")
+    if (!matches.length) return
+    for (const m of matches.slice(0, 2)) if (m.at.cls) classes.add(m.at.cls.name)
+    const [first, ...rest] = describeMatches(graph, matches, 2)
+    out.set(i + 1, [`   in this repository: ${first}`, ...rest.map((r) => `   or: ${r}`)])
+  })
+  return out
+}
+
+const MAX_EXAMPLE_LINES = 60
+
+/**
+ * The outlines of the classes the steps and checks link to, from the code graph: each member's signature, line, and
+ * locators, as the files are now. Then the repository's test that uses the most of them, in full, as the example of
+ * its fixtures, attributes, and assertion style. Scribe works from these instead of reading files to learn them.
+ */
+function classesSection(graph: CodeGraph, classes: string[]): string[] {
+  const lines = [
+    "## The page objects these steps use",
+    "",
+    "Outlines of the classes named under the steps and checks, from ForgeQE's code graph of the repository as it is now: each member's signature, line, and the locators it builds. Work from these. Read a method's body with code_outline Class.member, and read a file in full only to edit it.",
+    "",
+    "```",
+    outlines(graph, classes),
+    "```",
+  ]
+  const test = exampleTest(graph, classes)
+  if (!test) return lines
+  // A test outside a class (test('…'), def test_) takes its setup from the file: its imports, fixtures, and
+  // beforeEach. A short spec file is shown whole, so that setup comes with it.
+  let source = outline(graph, test.cls ? `${test.cls.name}.${test.member.name}` : test.member.name)
+  if (!test.cls) {
+    try {
+      const whole = readFileSync(path.join(graph.repo, test.file), "utf8").trimEnd()
+      if (whole.split("\n").length <= MAX_EXAMPLE_LINES) source = `${test.file}\n${whole}`
+    } catch {}
+  }
+  if (source.split("\n").length > MAX_EXAMPLE_LINES + 1) return lines
+  const header = test.cls ? `${test.cls.kind} ${test.cls.name}${test.cls.bases.length ? ` : ${test.cls.bases.join(", ")}` : ""} (${test.file}:${test.cls.line})` : test.file
+  return [
+    ...lines,
+    "",
+    "## A test in this repository to follow",
+    "",
+    `The test that uses the most of these page objects, from ${header}. Follow its fixture or base class, attributes, setup, and assertion style; you need not read other tests to learn them.`,
+    "",
+    "```",
+    source,
+    "```",
   ]
 }
 
 /** The run found a functional defect: the test asserts the correct behaviour and is marked as an expected failure. */
 export type KnownDefect = { reason: string; bug?: { label: string; url?: string } }
 
-export function buildHandoff(runDir: string, memoryDir?: string, opts: { replay?: Replay | null; knownDefect?: KnownDefect } = {}): Handoff {
+export function buildHandoff(runDir: string, memoryDir?: string, opts: { replay?: Replay | null; knownDefect?: KnownDefect; graph?: CodeGraph | null } = {}): Handoff {
   const run = readJson<RunJson>(path.join(runDir, "run.json"))
   if (!run) throw new Error(`No run.json in ${runDir}. Point at a ForgeQE run directory.`)
   const workflowFile = path.join(runDir, "workflow.yaml")
@@ -500,18 +565,28 @@ export function buildHandoff(runDir: string, memoryDir?: string, opts: { replay?
       "",
     )
   }
-  md.push(...stepsSection(steps, slices))
+  const elementSteps = steps.map((s) => (["click", "input", "select"].includes(s.op || "") ? { locators: s.locators, page: s.page || s.page_url } : {}))
+  const linked = new Set<string>()
+  const stepLinks = opts.graph ? repoLinks(opts.graph, pages, elementSteps, linked) : new Map<number, string[]>()
+  const checkLinks = opts.graph ? repoLinks(opts.graph, pages, checks.map((c) => ({ locators: c.element?.locators, page: c.url || run.final_url })), linked) : new Map<number, string[]>()
+  if (stepLinks.size || checkLinks.size) {
+    md.push(
+      "Under a step or a check, \"in this repository\" names the page-object member that already locates that element, found through page memory whichever locator it uses, and the methods that use it. Call that method, or use that member, instead of writing a new locator for the element. When its locator is brittle and the step has a ✓ semantic locator, change it where it is defined.",
+      "",
+    )
+  }
+  md.push(...stepsSection(steps, slices, stepLinks))
   const overlays = overlaysSection(steps)
   if (overlays.length) md.push("", ...overlays)
   if (opts.replay) md.push("", ...replaySection(opts.replay))
   const launch = launchSection(run.browser, opts.replay)
   if (launch.length) md.push("", ...launch)
-  if (checks.length) md.push("", ...checksSection(checks, opts.replay))
+  if (checks.length) md.push("", ...checksSection(checks, opts.replay, checkLinks))
+  if (opts.graph && linked.size) md.push("", ...classesSection(opts.graph, [...linked]))
   const snapshots = Boolean(opts.replay?.passes.some((p) => p.pages?.length))
   // Page memory is for finding elements the handoff does not give; with every step and check verified it is noise.
-  const elementSteps = steps.filter((s) => ["click", "input", "select"].includes(s.op || ""))
   const allVerified =
-    elementSteps.every((s) => verifiedLocators(s.locators).length) && checks.every((c) => c.item || verifiedLocators(c.element?.locators).length)
+    steps.filter((s) => ["click", "input", "select"].includes(s.op || "")).every((s) => verifiedLocators(s.locators).length) && checks.every((c) => c.item || verifiedLocators(c.element?.locators).length)
   if (visited.length && !snapshots && !allVerified) {
     md.push(
       "",

package/src/code/loop.ts

@@ -9,6 +9,10 @@ import { buildHandoff, type KnownDefect } from "./handoff.ts"
 import type { TestCase } from "../cases/types.ts"
 import { buildProfile, profileSection } from "./profile.ts"
 import { LIVE_BROWSER_SERVER, liveBrowser } from "./livebrowser.ts"
+import { additionFacts, buildGraph, classesUsedBy, outlines, type CodeGraph } from "./graph/graph.ts"
+import { CODE_GRAPH_SERVER, codeGraphTools } from "./graph/tools.ts"
+import { localToolServer } from "../mcp/server.ts"
+import type { ToolContext } from "../mcp/tools.ts"
 import { addWrittenTest, notesSection, readNotes, saveNotes } from "./notes.ts"
 import { canReplay, replayRun, savedReplay, type Replay } from "./replay.ts"
 import { openSession, READ_AGENT, TEST_AGENT, type OpencodeSession, type PromptOutcome } from "./runtime.ts"
@@ -117,12 +121,20 @@ export async function runCodeAgent(opts: {
   const repo = realpathSync(given)
   const { config } = opts
   const emit = opts.onEvent || (() => {})
-  let handoff = buildHandoff(opts.runDir, config.memory.dir, { knownDefect: opts.knownDefect })
+  // The repository's code graph, read without a model: the handoff links each element to the page object that already
+  // locates it, Scribe gets code_* tools instead of reading whole files, and the reviewer gets what the job duplicated.
+  const built = config.code.graph === false ? null : await buildGraph(repo).catch(() => null)
+  const graph: CodeGraph | null = built?.files.length ? built : null
+  let handoff = buildHandoff(opts.runDir, config.memory.dir, { knownDefect: opts.knownDefect, graph })
   if (!handoff.success && !opts.knownDefect) throw new Error("The coding agent only takes runs that passed. This run failed.")
   const plural = (n: number, w: string) => `${n} ${w}${n === 1 ? "" : "s"}`
   const shown = path.relative(process.cwd(), handoff.file)
   const handed = [plural(handoff.steps, "step"), handoff.checks ? plural(handoff.checks, "check") : "", handoff.pages ? `${plural(handoff.pages, "page")} from page memory` : ""]
   emit({ type: "code", kind: "info", text: `Handoff written: ${shown && !shown.startsWith("..") ? shown : handoff.file} (${handed.filter(Boolean).join(", ")})` })
+  if (graph) {
+    const classes = graph.files.reduce((n, f) => n + f.classes.length, 0)
+    emit({ type: "code", kind: "info", text: `Code graph: ${graph.files.length} files, ${classes} classes (${graph.parsed} read, ${graph.reused} unchanged, ${graph.ms}ms)` })
+  }
   const maxAttempts = Math.max(1, config.code.maxAttempts)
 
   const result: CodeResult = {
@@ -152,7 +164,15 @@ export async function runCodeAgent(opts: {
   const before = snapshot(repo, own)
   const outside = [opts.runDir, config.memory.dir].map((d) => realpathOr(d)).filter((d) => path.relative(repo, d).startsWith(".."))
   let session: OpencodeSession | null = null
-  const reviewer = opts.reviewer || openReviewer({ config, repo, readDirs, signal: opts.signal, onEvent: emit, open: opts.open })
+  const codeTools = graph
+    ? localToolServer({
+        tools: codeGraphTools({ repo, ...(config.memory.enabled ? { memoryDir: config.memory.dir } : {}) }),
+        context: () => ({ config, cwd: repo }) as ToolContext,
+        timeoutMs: 120_000,
+      })
+    : null
+  const reviewer =
+    opts.reviewer || openReviewer({ config, repo, readDirs, signal: opts.signal, onEvent: emit, open: opts.open, ...(codeTools ? { mcp: { [CODE_GRAPH_SERVER]: codeTools.entry } } : {}) })
   const runTest = opts.runTest || runTestCommand
   let challenged = false
   let stalls = 0
@@ -226,7 +246,7 @@ export async function runCodeAgent(opts: {
       agent: { ...TEST_AGENT, steps: config.code.maxSteps ?? 50 },
       agents: [READ_AGENT],
       skills: loadSkills(config.skills, repo).skills,
-      ...(live ? { mcp: { [LIVE_BROWSER_SERVER]: live.config } } : {}),
+      ...(live || codeTools ? { mcp: { ...(live ? { [LIVE_BROWSER_SERVER]: live.config } : {}), ...(codeTools ? { [CODE_GRAPH_SERVER]: codeTools.entry } : {}) } } : {}),
       ...(resume ? { resume } : {}),
     })
   // Each attempt after the first runs in a new session from a brief of the job so far (nextAttemptPrompt), so the
@@ -285,7 +305,7 @@ export async function runCodeAgent(opts: {
         ...(r.error ? { error: r.error } : {}),
         passes: r.passes.map((p) => ({ setup: p.setup, failed: p.steps.filter((s) => !s.ok && !s.skipped).map((s) => s.n), reached: p.reached })),
       }
-      handoff = buildHandoff(opts.runDir, config.memory.dir, { replay, knownDefect: opts.knownDefect })
+      handoff = buildHandoff(opts.runDir, config.memory.dir, { replay, knownDefect: opts.knownDefect, graph })
       // The replay's failure (its error, screenshot, and page snapshot) is in the handoff; the live browser waits for a repeated failure.
       liveOn = Boolean(live) && Boolean(resumed && earlier?.liveOn)
     } else if (resumed && earlier?.liveOn) {
@@ -463,8 +483,12 @@ export async function runCodeAgent(opts: {
         const where = run.browsers.length ? run.browsers.join(", ") : `remote browser (${report.remote_browser})`
         emit({ type: "code", kind: "info", text: `${report.test_file} passed in ${secs}s in ${where}; a reviewer checks it against the goal` })
         const changes = jobChanges(before) ?? undefined
+        const now = graph && changes?.length ? await buildGraph(repo).catch(() => null) : null
+        const facts = graph && now && changes ? additionFacts(graph, now, changes) : []
+        const used = now && changes ? outlines(now, classesUsedBy(now, changes)) : ""
+        const settings = (repoProfile?.settings || []).map((st) => `- ${st.file}: ${Object.entries(st.values).map(([k, v]) => `${k}=${v}`).join(", ")}`)
         // After a rejection or a tidy-up, the reviewer checks its own earlier issues instead of starting over.
-        const verdict = await reviewer.review({ handoff, report, output: run.output, browsers: run.browsers, seconds: secs, changes, before: preexisting(before), ...(result.review ? { earlier: result.review } : {}) })
+        const verdict = await reviewer.review({ handoff, report, output: run.output, browsers: run.browsers, seconds: secs, changes, before: preexisting(before), ...(facts.length ? { facts } : {}), ...(used ? { outlines: used } : {}), ...(settings.length ? { settings } : {}), ...(result.review ? { earlier: result.review } : {}) })
         if (opts.signal?.aborted) {
           result.status = "stopped"
           break
@@ -584,6 +608,7 @@ export async function runCodeAgent(opts: {
       await session.close()
     }
     await reviewer.close()
+    codeTools?.stop()
     // With code.model the agent runtime picks the model, so there is no price for it in llms.json; the reviewer is
     // priced at its own profile (code.review_profile). The job's cost is unknown when either part has no price.
     const scribeCost = costOf(result.usage, config.code.model ? undefined : config.llm.price)

package/src/code/profile.ts

@@ -26,7 +26,8 @@ const PAGE_DIRS = /(^|\/)(pages|page-?objects|pom|components|flows|screens)(\/|$
 const MAX_MEMBERS = 14
 const MAX_CLASSES = 25
 
-function walk(repo: string): string[] {
+/** The repository's files (relative, with /), skipping build output, dependencies, and dot folders. */
+export function walk(repo: string): string[] {
   const out: string[] = []
   const visit = (dir: string) => {
     if (out.length >= MAX_FILES) return
@@ -119,13 +120,21 @@ export function buildProfile(repo: string): RepoProfile | null {
     try {
       const doc = JSON.parse(read(repo, f)) as { dependencies?: Record<string, string>; devDependencies?: Record<string, string>; scripts?: Record<string, string> }
       const deps = { ...doc.dependencies, ...doc.devDependencies }
-      const interesting = Object.entries(deps).filter(([n]) => /playwright|cypress|webdriverio|jest|vitest|mocha/.test(n))
+      const interesting = Object.entries(deps).filter(([n]) => /playwright|cypress|webdriverio|@wdio\/|selenium|testing-library|jest|vitest|mocha/.test(n))
       if (interesting.length) profile.stack.push(`${f}: ${interesting.map(([n, v]) => `${n} ${v}`).join(", ")}`)
       if (doc.scripts?.test) profile.stack.push(`${f} test script: ${doc.scripts.test}`)
     } catch {
       /* not JSON */
     }
   }
+  // Java: Maven and Gradle builds.
+  for (const f of files.filter((f) => /(^|\/)(pom\.xml|build\.gradle(\.kts)?)$/.test(f))) {
+    const text = read(repo, f)
+    const maven = [...text.matchAll(/<artifactId>([^<]*(?:selenium|playwright|testng|junit|cucumber|selenide)[^<]*)<\/artifactId>\s*(?:<version>([^<]+)<\/version>)?/gi)].map((m) => (m[2] ? `${m[1]} ${m[2]}` : m[1]))
+    const gradle = [...text.matchAll(/["']([\w.-]+:[\w.-]*(?:selenium|playwright|testng|junit|cucumber|selenide)[\w.-]*(?::[\w.-]+)?)["']/gi)].map((m) => m[1])
+    const hits = [...new Set([...maven, ...gradle])]
+    if (hits.length) profile.stack.push(`${f}: ${hits.join(", ")}`)
+  }
   const pyDeps = files.filter((f) => /(^|\/)(pyproject\.toml|requirements[^/]*\.txt)$/.test(f))
   for (const f of pyDeps) {
     const hits = read(repo, f).match(/(pytest-playwright|playwright|pytest|selenium)[^\s"',]*/g)
@@ -185,8 +194,10 @@ export function buildProfile(repo: string): RepoProfile | null {
   }
   if (files.some((f) => /(^|\/)playwright\.config\.(ts|js|mjs|cjs)$/.test(f))) profile.oneTest.push('npx playwright test <file> -g "<test title>"')
   if (files.some((f) => /(^|\/)conftest\.py$/.test(f)) || pyDeps.length) profile.oneTest.push("pytest <file>::<test_name>")
+  if (files.some((f) => /(^|\/)pom\.xml$/.test(f))) profile.oneTest.push('mvn test -Dtest="<Class>#<method>"')
+  if (files.some((f) => /(^|\/)build\.gradle(\.kts)?$/.test(f))) profile.oneTest.push('./gradlew test --tests "<package>.<Class>.<method>"')
   // Only a recognised browser test stack is enough to start from; otherwise Scribe reads the repository itself.
-  const browserStack = testProjects.length > 0 || profile.stack.some((s) => /playwright|cypress|selenium|webdriverio/i.test(s))
+  const browserStack = testProjects.length > 0 || profile.stack.some((s) => /playwright|cypress|selenium|selenide|webdriverio|@wdio\//i.test(s))
   return browserStack ? profile : null
 }
 

package/src/code/replay.ts

@@ -735,7 +735,7 @@ export function replaySection(r: Replay): string[] {
   }
   lines.push("")
   const port =
-    "Port its steps into the repository's framework and page objects with the same locators and waits, then add the goal's assertions (the handoff's checks, when it lists them). Steps that dealt with a pop-up or banner on this run (see the browser agent's notes) still belong in a handler, as the rules say. Steps that run the browser agent's JavaScript were how it looked around or read values, not steps to copy: where the JavaScript clicks or types, do that with a Playwright action on the same element; where it reads values, assert them with locators."
+    "Port its steps into the repository's framework and page objects with the same locators and waits, then add the goal's assertions (the handoff's checks, when it lists them). Steps that dealt with a pop-up or banner on this run (see the browser agent's notes) still belong in the overlay handler or helper the rules describe. Steps that run the browser agent's JavaScript were how it looked around or read values, not steps to copy: where the JavaScript clicks or types, do that with a Playwright action on the same element; where it reads values, assert them with locators."
   if (first.ok) {
     lines.push(`The script works as it is. ${port}`)
     return lines

package/src/code/review.ts

@@ -72,6 +72,12 @@ export type ReviewInput = {
   before?: string[]
   /** This reviewer's earlier verdict on this job, when the agent has since changed the test to answer it. */
   earlier?: CodeReview
+  /** What ForgeQE's code graph found in what the job added: locators that duplicate an existing member's, brittle locators. */
+  facts?: string[]
+  /** Outlines of the classes the changed code uses, from the code graph, so the reviewer need not read their files. */
+  outlines?: string
+  /** The repository's browser settings files and their values, as ForgeQE read them. */
+  settings?: string[]
 }
 
 const LIST_MAX = 60
@@ -131,6 +137,19 @@ export function reviewPrompt(input: ReviewInput, repo?: string): string {
     "```",
     out,
     "```",
+    ...(input.facts?.length
+      ? ["", "ForgeQE's code graph found these in what the job added (from the code, not a guess; judge each by the test rules):", ...input.facts.map((f) => `- ${f}`)]
+      : []),
+    ...(input.outlines
+      ? [
+          "",
+          "Outlines of the classes the changed code uses, from ForgeQE's code graph of the repository as it is now (signatures, lines, and the locators each member builds). Check reuse and calls against these; read a member's body with code_outline Class.member, not the whole file:",
+          "```",
+          input.outlines,
+          "```",
+        ]
+      : []),
+    ...(input.settings?.length ? ["", "Browser settings in the repository, as ForgeQE read them from its settings files:", ...input.settings] : []),
     ...(repo && changed.length ? ["", "The changed files as they are now:", "", ...changedFiles(repo, changed)] : []),
     ...(input.earlier
       ? [
@@ -153,6 +172,8 @@ export function openReviewer(opts: {
   signal?: AbortSignal
   onEvent?: (e: CodeEvent) => void
   open?: (o: Parameters<typeof openSession>[0]) => Promise<OpencodeSession>
+  /** MCP servers for the review session: the code graph's tools. */
+  mcp?: Record<string, unknown>
 }): Reviewer {
   let session: OpencodeSession<ReviewReport> | null = null
   const usage: Usage = { input: 0, output: 0 }
@@ -185,6 +206,7 @@ export function openReviewer(opts: {
           skills: loadSkills(opts.config.skills, opts.repo).skills,
           schema: REVIEW_SCHEMA as unknown as Record<string, unknown>,
           title: "ForgeQE review",
+          ...(opts.mcp ? { mcp: opts.mcp } : {}),
         })
       }
       let reply = await session.prompt(reviewPrompt(input, opts.repo))

package/src/code/runtime.ts

@@ -644,6 +644,8 @@ export async function openSession<R = AgentReport>(opts: {
   const skillsUsed: string[] = []
   const assistant = new Set<string>()
   const said = new Set<string>()
+  /** Tool calls already said to have started, by part id. */
+  const startedCalls = new Set<string>()
   let idle: (() => void) | null = null
   let sessionError = ""
   // The turn's result comes from events: in agent runtime 1.18 listing a session's messages fails once a prompt used `format`.
@@ -664,6 +666,11 @@ export async function openSession<R = AgentReport>(opts: {
         break
       case "message.part.updated": {
         const part = p.part
+        // A call is said as soon as it starts, so a long one (an API query, a test run) is visible while it runs.
+        if (part?.type === "tool" && part.state?.status === "running" && part.id && !startedCalls.has(part.id) && !QUIET_TOOLS.has(part.tool) && !opts.hideTool?.(part.tool)) {
+          startedCalls.add(part.id)
+          emit({ type: "code", kind: "start", tool: part.tool, id: part.id, text: toolLine(opts.repo, part.tool, part.state.input || {}, part.state.title) })
+        }
         if (part?.type === "tool" && (part.state?.status === "completed" || part.state?.status === "error")) {
           if (part.tool === "StructuredOutput" && part.state.status === "completed" && !turn.structured) {
             turn.structured = part.state.input || null
@@ -687,7 +694,7 @@ export async function openSession<R = AgentReport>(opts: {
           const ok = part.state.status === "completed"
           const file = toolFile(opts.repo, part.tool, input)
           const skill = part.tool === "skill" && ok ? String(input.name || "") : ""
-          emit({ type: "code", kind: "tool", ok, tool: part.tool, ...(file ? { file } : {}), ...(skill ? { skill } : {}), text: ok ? line : `${line}: ${clip(toolError(String(part.state.error || "")) || "failed", 120)}` })
+          emit({ type: "code", kind: "tool", ok, tool: part.tool, ...(part.id ? { id: part.id } : {}), ...(file ? { file } : {}), ...(skill ? { skill } : {}), text: ok ? line : `${line}: ${clip(toolError(String(part.state.error || "")) || "failed", 120)}` })
         } else if (part?.type === "text" && part.time?.end && assistant.has(part.messageID) && !said.has(part.id)) {
           said.add(part.id)
           const text = String(part.text || "").trim()