@capagents/forgeqe 1.1.6 → 1.1.8

package/src/mcp/reporttools.ts

@@ -1,11 +1,29 @@
 import { mkdirSync, writeFileSync } from "node:fs"
 import path from "node:path"
 
+import { queryApi, type ApiQuery } from "../cases/api.ts"
+import { reportPage } from "../report/html.ts"
+import {
+  chooseColumns,
+  chooseFilters,
+  dedupe,
+  describeCall,
+  EvidenceLog,
+  evidenceList,
+  pickEvidence,
+  rowsOf,
+  type Cell,
+  type Column,
+  type EvidenceEntry,
+  type Row,
+} from "../report/evidence.ts"
 import type { McpTool } from "./tools.ts"
 
 /**
- * Reports the agent writes from what it found (release status, open defects, pipeline health): a Markdown file to
- * edit or paste, and the same report as a page to open or share. The chat gets the summary and the links.
+ * Reports the agent writes from what it found (open defects, release status, pipeline health). Every table in one is
+ * built from evidence: the output of tool calls in this session, or a read-only query ForgeQE runs itself. The model
+ * writes only the summary. The report is a page (report-ui, with filters, charts, and the sources it came from) and
+ * the same report as Markdown; the raw results are kept beside them.
  */
 
 /** "Release status: all projects" → "release-status-all-projects". */
@@ -21,7 +39,7 @@ export function reportSlug(title: string): string {
 
 const escapeHtml = (s: string) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;")
 
-/** The report as a page: the Markdown rendered, with raw HTML in it shown as text so a report can never run script. */
+/** A Markdown document as a plain page (forgeqe bi's page without Evidence): the Markdown rendered, with raw HTML in it shown as text so a report can never run script. */
 export function reportHtml(title: string, markdown: string, written: Date): string {
   const safe = markdown.replace(/<(?=[A-Za-z/!?])/g, "&lt;")
   const body = Bun.markdown.html(safe)
@@ -66,36 +84,209 @@ ${body}
 `
 }
 
+/** The summary as HTML, with raw HTML in it shown as text 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 MAX_ROWS = 5000
+const MD_ROWS = 200
+
+export type DatasetSpec = { name?: string; from?: string; match?: string; query?: ApiQuery; columns?: string[]; filters?: string[] }
+
+export type Dataset = { name: string; columns: Column[]; filters: string[]; rows: Row[]; sources: string[]; total: number; note?: string }
+export type Source = { id: string; tool: string; call: string; at: string; rows: number | null; file: string }
+
+/** The rows of one dataset, and the evidence they came from. */
+export async function buildDataset(spec: DatasetSpec, log: EvidenceLog, readApi: (q: ApiQuery) => Promise<unknown>): Promise<{ dataset: Dataset; used: EvidenceEntry[] }> {
+  const name = String(spec.name || "Data").trim()
+  let used: EvidenceEntry[]
+  if (spec.query) {
+    const q = spec.query
+    const out = await readApi(q)
+    const entry = log.record("query_api", { ...q }, typeof out === "string" ? out : JSON.stringify(out))
+    if (!entry) throw new Error(`Dataset "${name}": the query returned nothing.`)
+    used = [entry]
+  } else if (spec.from) {
+    used = pickEvidence(log.all(), String(spec.from), spec.match ? String(spec.match) : undefined)
+    if (!used.length) throw new Error(`Dataset "${name}": no tool result matches "${spec.from}"${spec.match ? ` with "${spec.match}"` : ""}. Results in this session:\n${evidenceList(log.all())}`)
+  } else {
+    throw new Error(`Dataset "${name}" needs "from" (a tool result of this session, e.g. E3 or the tool's name) or "query" (a read-only query ForgeQE runs).`)
+  }
+  const parts = used.map((e) => ({ e, rows: rowsOf(e.output) }))
+  const noData = parts.filter((p) => p.rows === null)
+  if (noData.length === parts.length) {
+    throw new Error(`Dataset "${name}": ${noData.map((p) => p.e.id).join(", ")} returned no data (no JSON records). Results in this session:\n${evidenceList(log.all())}`)
+  }
+  const all = dedupe(parts.flatMap((p) => p.rows || []))
+  const rows = all.slice(0, MAX_ROWS)
+  const columns = rows.length ? chooseColumns(rows, spec.columns) : []
+  const totals = parts.map((p) => {
+    const v = (() => {
+      try {
+        return JSON.parse(p.e.output) as { total?: unknown; count?: unknown }
+      } catch {
+        return null
+      }
+    })()
+    return typeof v?.total === "number" ? v.total : 0
+  })
+  const total = Math.max(all.length, ...totals)
+  const notes = [
+    all.length > MAX_ROWS ? `The page holds the first ${MAX_ROWS} of ${all.length} rows.` : "",
+    total > all.length ? `The query matched ${total}; the first ${all.length} were read.` : "",
+  ].filter(Boolean)
+  return {
+    dataset: { name, columns, filters: chooseFilters(rows, columns, spec.filters), rows, sources: used.map((e) => e.id), total, ...(notes.length ? { note: notes.join(" ") } : {}) },
+    used,
+  }
+}
+
+const mdCell = (v: Cell | undefined) => (v === null || v === undefined ? "" : String(v).replace(/\|/g, "\\|").replace(/\s+/g, " "))
+const csvCell = (v: Cell | undefined) => {
+  const s = v === null || v === undefined ? "" : String(v)
+  return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s
+}
+
+/** Counts of each value of a column, most first. */
+export function countBy(rows: Row[], key: string): [string, number][] {
+  const m = new Map<string, number>()
+  for (const r of rows) {
+    const v = r[key] === null || r[key] === undefined || r[key] === "" ? "(none)" : String(r[key])
+    m.set(v, (m.get(v) || 0) + 1)
+  }
+  return [...m].sort((a, b) => b[1] - a[1])
+}
+
+/** The report as Markdown: the summary, each dataset's counts and table, and the sources. */
+export function reportMarkdown(title: string, summary: string, datasets: Dataset[], sources: Source[], written: Date): string {
+  const out = [`# ${title}`, "", `_Written by ForgeQE on ${written.toISOString().slice(0, 16).replace("T", " ")} UTC, from ${sources.length === 1 ? "1 source" : `${sources.length} sources`}._`, "", summary, ""]
+  for (const d of datasets) {
+    out.push(`## ${d.name}`, "", `**${d.rows.length}** ${d.rows.length === 1 ? "row" : "rows"}${d.note ? ` (${d.note})` : ""} · from ${d.sources.join(", ")}`, "")
+    for (const f of d.filters.slice(0, 3)) out.push(`- By ${f}: ${countBy(d.rows, f).map(([v, n]) => `${v} ${n}`).join(", ")}`)
+    if (d.filters.length) out.push("")
+    if (d.rows.length) {
+      const cols = d.columns.filter((c) => c.key !== "Link")
+      const idCol = cols.find((c) => c.key === "ID" || c.key === "Key")
+      out.push(`| ${cols.map((c) => c.label).join(" | ")} |`, `| ${cols.map(() => "---").join(" | ")} |`)
+      for (const r of d.rows.slice(0, MD_ROWS)) {
+        out.push(`| ${cols.map((c) => (c === idCol && r.Link ? `[${mdCell(r[c.key])}](${r.Link})` : mdCell(r[c.key]))).join(" | ")} |`)
+      }
+      if (d.rows.length > MD_ROWS) out.push("", `The first ${MD_ROWS} rows; the page and ${csvName(d.name)} have all ${d.rows.length}.`)
+      out.push("")
+    }
+  }
+  out.push("## Sources", "", ...sources.map((s) => `- ${s.id} · ${s.call} · ${s.at.slice(0, 16).replace("T", " ")} UTC · ${s.rows === null ? "no data" : `${s.rows} rows`} · [raw](${s.file})`), "")
+  return out.join("\n")
+}
+
+const csvName = (name: string) => `${reportSlug(name)}.csv`
+
 export const REPORT_TOOLS: McpTool[] = [
   {
     name: "write_report",
     description:
-      'Save a report the user asks for ("create a release report", "write up the open defects", "give me a report I can share") as a Markdown file and an HTML page in the reports folder. Gather the facts with your other tools first, then pass the whole report as Markdown: a one-paragraph summary first, then ## sections, tables for per-item status (one row per project, case, or build), and links to builds, work items, and pull requests. Do not invent data you did not read. The user is shown the report paths as links, so reply with three to five lines of summary only: do not repeat the paths or paste the report.',
+      'Save a report the user asks for ("create a defect report for all open defects", "release status for all projects", "a report I can share") as a page with filters, charts, and its sources, and as Markdown. A report is built from evidence: each dataset is the output of tool calls you made in this session (from: the tool\'s name, e.g. wit_get_work_items_batch_by_ids or query_api, or an evidence id like E3; match narrows to calls whose input mentions it), or a read-only query ForgeQE runs itself (query: same fields as query_api; a WIQL query reads up to 1000 work items with project, state, priority, severity, assignee, area, and links, so prefer it for "all" of something). ForgeQE takes the rows from those results, not from you; columns and filters are optional (default: the usual ones in the data, such as Project, State, Priority, Assigned To). Write only the summary yourself: one short paragraph of what the data shows, with no figures the datasets do not hold. The user is shown the report paths as links, so reply with three to five lines of summary only.',
     inputSchema: {
       type: "object",
       properties: {
-        title: { type: "string", description: "The report's title, e.g. Release status: all projects, 9 October 2026" },
-        markdown: { type: "string", description: "The report body in Markdown, without the title (it is added as the heading)" },
+        title: { type: "string", description: "The report's title, e.g. Open defects: all projects, 13 October 2026" },
+        summary: { type: "string", description: "One short Markdown paragraph (or a few bullets) on what the data shows; the tables, counts, and charts are made from the datasets" },
+        datasets: {
+          type: "array",
+          minItems: 1,
+          items: {
+            type: "object",
+            properties: {
+              name: { type: "string", description: "e.g. Open defects" },
+              from: { type: "string", description: "Evidence ids (E3, or E3,E4) or the name of a tool called in this session; every successful call of it is used" },
+              match: { type: "string", description: "With a tool name: only its calls whose input contains this text" },
+              query: {
+                type: "object",
+                description: "A read-only query ForgeQE runs for this dataset (instead of from)",
+                properties: {
+                  system: { type: "string", enum: ["azure_devops", "jira", "xray", "confluence"] },
+                  wiql: { type: "string", description: "azure_devops: e.g. SELECT [System.Id] FROM WorkItems WHERE [System.WorkItemType] = 'Bug' AND [System.State] NOT IN ('Closed','Done','Removed'). Across projects, leave out @project" },
+                  project: { type: "string" },
+                  path: { type: "string", description: "A REST path, as for query_api (e.g. Jira /rest/api/3/search/jql?jql=...&fields=summary,status,priority,assignee,project)" },
+                  query: { type: "string", description: "xray: a GraphQL query" },
+                  variables: { type: "object" },
+                },
+                required: ["system"],
+              },
+              columns: { type: "array", items: { type: "string" }, description: "Columns to show, in order (default: the usual ones in the data)" },
+              filters: { type: "array", items: { type: "string" }, description: "Columns to filter by (default: Project, State, Priority, Assigned To, … when present)" },
+            },
+            required: ["name"],
+          },
+        },
       },
-      required: ["title", "markdown"],
+      required: ["title", "datasets"],
     },
     async run(args, ctx) {
       const title = String(args.title || "Report").trim()
-      const markdown = String(args.markdown || "").trim()
-      if (!markdown) throw new Error("The report is empty: pass its body as markdown.")
+      const summary = String(args.summary ?? args.markdown ?? "").trim()
+      const specs = (Array.isArray(args.datasets) ? args.datasets : []) as DatasetSpec[]
+      const log = ctx.evidence || new EvidenceLog()
+      if (!specs.length) {
+        throw new Error(`A report is built from evidence: pass datasets, each from a tool result of this session or a read-only query. Results in this session:\n${evidenceList(log.all())}`)
+      }
+      const readApi = (q: ApiQuery) => queryApi(ctx.config.sources, q, { full: true })
+      const built: Dataset[] = []
+      const used = new Map<string, EvidenceEntry>()
+      for (const spec of specs) {
+        const { dataset, used: entries } = await buildDataset(spec, log, readApi)
+        built.push(dataset)
+        for (const e of entries) used.set(e.id, e)
+      }
+
       const written = new Date()
       const stamp = written.toISOString().replace(/[-:]/g, "").replace("T", "-").slice(0, 15)
       // Beside the run reports, so the shell links it and outDir publishing (notify.report_url) serves it too.
       const dir = path.resolve(ctx.config.export.outDir, `${reportSlug(title)}-${stamp}`)
-      mkdirSync(dir, { recursive: true })
+      mkdirSync(path.join(dir, "evidence"), { recursive: true })
+      const sources: Source[] = [...used.values()].map((e) => {
+        const file = `evidence/${e.id}.json`
+        writeFileSync(path.join(dir, file), JSON.stringify({ id: e.id, tool: e.tool, input: e.input, at: e.at, output: e.output }, null, 2))
+        const rows = rowsOf(e.output)
+        return { id: e.id, tool: e.tool, call: describeCall(e), at: e.at, rows: rows ? rows.length : null, file }
+      })
+      for (const d of built) {
+        const cols = d.columns
+        writeFileSync(path.join(dir, csvName(d.name)), [cols.map((c) => csvCell(c.label)).join(","), ...d.rows.map((r) => cols.map((c) => csvCell(r[c.key])).join(","))].join("\n") + "\n")
+      }
       const md = path.join(dir, "report.md")
       const html = path.join(dir, "report.html")
-      writeFileSync(md, `# ${title}\n\n${markdown}\n`)
-      writeFileSync(html, reportHtml(title, markdown, written))
+      writeFileSync(md, reportMarkdown(title, summary, built, sources, written))
+      writeFileSync(
+        html,
+        reportPage(title, {
+          kind: "data",
+          title,
+          id: path.basename(dir),
+          startedAt: written.toISOString(),
+          ms: 0,
+          stopped: false,
+          generatedAt: written.toISOString(),
+          cases: [],
+          posted: [],
+          history: [],
+          report: { summary, summaryHtml: summary ? summaryHtml(summary) : "", datasets: built.map((d) => ({ ...d, csv: csvName(d.name) })), sources },
+        }),
+      )
       const show = (p: string) => path.relative(process.cwd(), p) || p
+      const rows = built.reduce((n, d) => n + d.rows.length, 0)
       ctx.emit?.({ type: "report", title, html, markdown: md })
-      ctx.emit?.({ type: "card", card: { status: "ok", title: `Report: ${title}`, body: [`Page      ${show(html)}`, `Markdown  ${show(md)}`] } })
-      return { html: show(html), markdown: show(md) }
+      ctx.emit?.({
+        type: "card",
+        card: { status: "ok", title: `Report: ${title}`, body: [`Page      ${show(html)}`, `Markdown  ${show(md)}`, `Evidence  ${rows} rows from ${sources.map((s) => s.id).join(", ")}`] },
+      })
+      return {
+        html: show(html),
+        markdown: show(md),
+        datasets: built.map((d) => ({ name: d.name, rows: d.rows.length, total: d.total, columns: d.columns.map((c) => c.key), filters: d.filters, counts: Object.fromEntries(d.filters.map((f) => [f, Object.fromEntries(countBy(d.rows, f).slice(0, 8))])), ...(d.note ? { note: d.note } : {}) })),
+        sources: sources.map((s) => `${s.id} ${s.call}`),
+      }
     },
   },
 ]

package/src/mcp/server.ts

@@ -1,5 +1,6 @@
 import { createHash, randomBytes, timingSafeEqual } from "node:crypto"
 
+import { EvidenceLog } from "../report/evidence.ts"
 import { logEvent } from "../sessionLog.ts"
 import type { McpTool, ToolContext, ToolEvent } from "./tools.ts"
 
@@ -24,14 +25,23 @@ export type McpServerOptions = {
   progressMs?: number
 }
 
+/** A ForgeQE tool call that has no line of its own, named for the Activity panel by its tool and its subject. */
+export function callLabel(name: string, args: Record<string, unknown>): string {
+  const subject = [args.title, args.goal, args.source, args.sources, args.run_dir, args.command].find((v) => typeof v === "string" && v.trim()) as string | undefined
+  const flat = subject?.replace(/\s+/g, " ").trim()
+  return `ForgeQE · ${name.replace(/_/g, " ")}${flat ? ` (${flat.length > 70 ? `${flat.slice(0, 69)}…` : flat})` : ""}`
+}
+
 /** JSON-RPC dispatch for MCP: initialize, ping, tools/list, tools/call, and cancellation. */
 export function createMcpServer(opts: McpServerOptions) {
   const running = new Map<string | number, AbortController>()
+  /** Every result of this server's tools, for write_report; the agent adds the results of the other MCP servers. */
+  const evidence = new EvidenceLog()
 
   async function callTool(params: Json, id: string | number, send: Send, outer?: AbortSignal): Promise<Json> {
     const tool = opts.tools.find((t) => t.name === params.name)
     if (!tool) return { content: [{ type: "text", text: `Unknown tool ${params.name}` }], isError: true }
-    const base = opts.context()
+    const base = { evidence, ...opts.context() }
     const controller = new AbortController()
     const abort = () => controller.abort()
     base.signal?.addEventListener("abort", abort, { once: true })
@@ -63,10 +73,13 @@ export function createMcpServer(opts: McpServerOptions) {
           }
         : undefined
       const callId = `${tool.name}-${String(id)}-${started}`
-      const said = (ok: boolean) => {
-        if (tool.line && emit) emit({ type: "call", text: tool.line(params.arguments || {}), ok, id: callId })
-      }
-      if (tool.line && emit) emit({ type: "call-start", text: tool.line(params.arguments || {}), id: callId })
+      // Every call is said as it starts and ends. A tool with no line of its own shows its result another way (a card,
+      // a run), so its call is named for the Activity panel only: "ForgeQE · write report (Open defects, 13 October)".
+      const args = params.arguments || {}
+      const label = tool.line ? tool.line(args) : callLabel(tool.name, args)
+      const quiet = tool.line ? {} : { quiet: true }
+      const said = (ok: boolean) => emit?.({ type: "call", text: label, ok, id: callId, ...quiet })
+      emit?.({ type: "call-start", text: label, id: callId, ...quiet })
       let out: unknown
       try {
         out = await tool.run(params.arguments || {}, { ...base, emit, signal: controller.signal })
@@ -76,7 +89,9 @@ export function createMcpServer(opts: McpServerOptions) {
       }
       if (controller.signal.aborted) return finish({ content: [{ type: "text", text: "Stopped by the user." }], isError: true })
       said(true)
-      return finish({ content: [{ type: "text", text: typeof out === "string" ? out : JSON.stringify(out, null, 2) }] })
+      const text = typeof out === "string" ? out : JSON.stringify(out, null, 2)
+      base.evidence.record(tool.name, args, text)
+      return finish({ content: [{ type: "text", text }] })
     } catch (err) {
       return finish({ content: [{ type: "text", text: controller.signal.aborted ? "Stopped by the user." : (err as Error).message || String(err) }], isError: true })
     } finally {
@@ -116,7 +131,7 @@ export function createMcpServer(opts: McpServerOptions) {
     }
   }
 
-  return { handle, abortAll: () => running.forEach((c) => c.abort()) }
+  return { handle, evidence, abortAll: () => running.forEach((c) => c.abort()) }
 }
 
 export type McpServer = ReturnType<typeof createMcpServer>

package/src/mcp/tools.ts

@@ -6,6 +6,7 @@ import type { Card } from "../card.ts"
 import { privateEnvNames } from "../childEnv.ts"
 import { usageLine } from "../usage.ts"
 import { queryApi } from "../cases/api.ts"
+import type { EvidenceLog } from "../report/evidence.ts"
 import { createAdoDashboard, type DashboardWidget } from "../cases/dashboards.ts"
 import { writeAdoWikiPage } from "../cases/wiki.ts"
 import { readConfluence } from "../cases/confluence.ts"
@@ -102,9 +103,12 @@ export type ToolEvent =
   /** write_report saved a report: its page and its Markdown. */
   | { type: "report"; title: string; html: string; markdown: string }
   /** A finished call of a tool that has no card of its own, as one line: "Azure DevOps API · QI-Claims/_apis/build/builds (top 5)". */
-  | { type: "call"; text: string; ok: boolean; id?: string }
-  /** The same call as it starts, so a long one is visible while it runs; its `call` with the same `id` follows. */
-  | { type: "call-start"; text: string; id: string }
+  | { type: "call"; text: string; ok: boolean; id?: string; quiet?: boolean }
+  /**
+   * The same call as it starts, so a long one is visible while it runs; its `call` with the same `id` follows.
+   * `quiet`: a tool that shows its own result (a card, a run): the call is for the Activity panel only.
+   */
+  | { type: "call-start"; text: string; id: string; quiet?: boolean }
 
 const API_LABEL: Record<string, string> = { azure_devops: "Azure DevOps", jira: "Jira", xray: "Xray", confluence: "Confluence" }
 
@@ -114,7 +118,12 @@ const API_LABEL: Record<string, string> = { azure_devops: "Azure DevOps", jira:
  */
 export function queryLine(args: Record<string, any>): string {
   const name = `${API_LABEL[String(args.system)] || String(args.system || "API")} API`
-  if (args.wiql) return `${name} · WIQL (${clip(String(args.wiql).replace(/\s+/g, " ").replace(/^SELECT .*? FROM WorkItems WHERE /i, ""), 90)})`
+  if (args.wiql) {
+    // The project first: it is what tells one search from the next, and the @project clause then says nothing more.
+    const where = String(args.wiql).replace(/\s+/g, " ").replace(/^SELECT .*? FROM WorkItems WHERE /i, "")
+    const query = args.project ? where.replace(/^\[System\.TeamProject\] = @project AND /i, "") : where
+    return `${name} · WIQL${args.project ? ` · ${args.project}` : ""} (${clip(query, 90)})`
+  }
   if (args.query) return `${name} · GraphQL (${clip(String(args.query).replace(/\s+/g, " "), 90)})`
   const raw = String(args.path || "")
   const url = /^https?:\/\//.test(raw) ? raw.replace(/^https?:\/\/[^/]+\/(?:[^/]+\/(?=[^/]+\/_apis\/))?/, "") : raw.replace(/^\//, "")
@@ -156,6 +165,8 @@ export type ToolContext = {
   openSession?: (o: any) => Promise<OpencodeSession<any>>
   /** Replaces write_test's confirming run in tests. */
   runTest?: typeof runTestCommand
+  /** The session's tool results, which write_report builds its tables from. */
+  evidence?: EvidenceLog
 }
 
 /** `lines`: context shown above the choice (the list being confirmed, sprint dates). */
@@ -705,7 +716,7 @@ export const TOOLS: McpTool[] = [
         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.",
+            "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, project, type, title, state, priority, severity, assignee, area, iteration, tags, created and changed dates, and a link. 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" },