@barivia/barmesh-mcp 0.5.4 → 0.6.0

package/dist/blocking_monitor.js

@@ -0,0 +1,34 @@
+import { resetInlineAttachBudget, structuredTextResult, tryAttachImage, } from "./shared.js";
+import { DEFAULT_BLOCK_UNTIL_SEC, DEFAULT_POLL_INTERVAL_SEC, formatMonitorText, monitorJob, } from "./job_monitor.js";
+/** Headless blocking monitor for barmesh_jobs(action=monitor). */
+export async function runBlockingMonitor(args) {
+    const block_until_sec = args.block_until_sec ?? DEFAULT_BLOCK_UNTIL_SEC;
+    const poll_interval_sec = args.poll_interval_sec ?? DEFAULT_POLL_INTERVAL_SEC;
+    const result = await monitorJob(args.job_id, {
+        block_until_sec,
+        poll_interval_sec,
+        wait_finalize: args.wait_finalize,
+    });
+    const reviewMode = result.data.monitor_mode === "review";
+    const text = reviewMode
+        ? String(result.data.status_text ?? "")
+        : formatMonitorText(result, { block_until_sec, poll_interval_sec });
+    resetInlineAttachBudget();
+    const content = [{ type: "text", text }];
+    if (reviewMode && result.terminal && String(result.data.status) === "completed") {
+        await tryAttachImage(content, args.job_id, "learning_curve.png");
+    }
+    return structuredTextResult({
+        ...result.data,
+        monitor: {
+            job_id: result.job_id,
+            terminal: result.terminal,
+            timed_out: result.timed_out,
+            mode: reviewMode ? "review" : "live",
+            snapshots: result.snapshots,
+            status_text: result.status_text,
+            suggested_next_step: result.suggested_next_step,
+        },
+        status_text: text,
+    }, undefined, content);
+}

package/dist/convergence_reading.js

@@ -0,0 +1,25 @@
+/**
+ * Single canonical convergence reading formatter (summary.json / cfd_metrics fields).
+ * Used by barmesh_results(get) only — explorer does not repeat this prose.
+ */
+export function formatConvergenceReading(summary) {
+    const convergence = summary.convergence;
+    if (!convergence)
+        return null;
+    const emd = convergence.emd;
+    const skl = convergence.skl;
+    const ref = String(summary.reference_mesh ?? "reference");
+    const parts = [];
+    if (emd) {
+        const plateau = emd.plateau === true ? "plateauing" : "not plateauing";
+        const mono = emd.monotonic_decrease === true ? "monotonic decrease" : "non-monotonic";
+        parts.push(`EMD vs ${ref}: ${mono}, ${plateau}`);
+    }
+    if (skl) {
+        const plateau = skl.plateau === true ? "plateauing" : "not plateauing";
+        parts.push(`SKL vs ${ref}: ${plateau}`);
+    }
+    if (parts.length === 0)
+        return null;
+    return parts.join("; ");
+}

package/dist/figure_sections.js

@@ -0,0 +1,50 @@
+/**
+ * Canonical figure taxonomy for barmesh_results_explorer dropdown sections.
+ */
+export const FIGURE_SECTION_ORDER = [
+    "overview",
+    "distances",
+    "diagnostics",
+    "component",
+];
+export const FIGURE_SECTION_LABELS = {
+    overview: "Overview",
+    distances: "Distances",
+    diagnostics: "Diagnostics",
+    component: "Component planes",
+};
+/** Map a figure base key into one of four explorer sections. */
+export function figureSection(key) {
+    if (key === "combined")
+        return "overview";
+    if (key === "overview_distances" ||
+        key.startsWith("KL_") ||
+        key.startsWith("EMD_")) {
+        return "distances";
+    }
+    if (key === "learning_curve" || key.startsWith("plot_vol"))
+        return "diagnostics";
+    if (key.startsWith("plot_"))
+        return "component";
+    return "diagnostics";
+}
+export const FIGURE_SORT_RANK = {
+    combined: 0,
+    overview_distances: 1,
+    KL_ref: 10,
+    KL_stepwise: 11,
+    EMD_ref: 12,
+    EMD_stepwise: 13,
+    learning_curve: 14,
+    plot_vol_all_meshes: 19,
+    plot_vol_coarse_fine: 20,
+};
+export function sortRank(key) {
+    if (key in FIGURE_SORT_RANK)
+        return FIGURE_SORT_RANK[key];
+    if (key.startsWith("plot_vol"))
+        return 25;
+    if (key.startsWith("plot_"))
+        return 30;
+    return 50;
+}

package/dist/index.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import{McpServer as e}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport as r}from"@modelcontextprotocol/sdk/server/stdio.js";import{getUiCapability as s,registerAppResource as o,RESOURCE_MIME_TYPE as t}from"@modelcontextprotocol/ext-apps/server";import{startVizServer as n}from"./viz-server.js";import{API_KEY as i,CLIENT_VERSION as a,apiCall as c,apiRawCall as m,loadViewHtml as l,setVizPort as d,setClientSupportsMcpApps as h}from"./shared.js";import{registerGuideTool as p}from"./tools/guide.js";import{registerDatasetsTool as b}from"./tools/datasets.js";import{registerCfdTools as f}from"./tools/cfd.js";import{registerJobsTool as u}from"./tools/jobs.js";import{registerResultsTool as _}from"./tools/results.js";import{registerResultsExplorerTool as v,RESULTS_EXPLORER_URI as g}from"./tools/barmesh_results_explorer.js";import{registerTrainingMonitorTool as y}from"./tools/training_monitor.js";import{registerFeedbackTool as j}from"./tools/feedback.js";i||(console.error("Error: BARIVIA_API_KEY not set. Set it in your MCP client config."),process.exit(1));(async function(){const i=new e({name:"barmesh",version:a},{instructions:"# Barivia barmesh — CFD mesh-convergence analytics\n\nSOM-based mesh-convergence verification: compare CFD meshes of a refinement study by the\nvolume-weighted distribution their cells form on a shared self-organizing map, plus\nclassical Richardson/GCI on scalar quantities.\n\n## Two tracks\n- barmesh_mesh_convergence: high-dimensional field comparison. Symmetric KL and\n  Wasserstein-1 (EMD) distances between each mesh's SOM fingerprint and a reference,\n  and between consecutive meshes. Decreasing, plateauing distances toward the finest\n  mesh indicate sufficiency. Complements (does not replace) numerical uncertainty analysis.\n- barmesh_richardson: classical grid-convergence index on scalar QoIs.\n\n## Workflow (read-only first)\n1. barmesh_guide_workflow — orient and confirm your plan includes CFD tools.\n2. barmesh_prepare_mesh_data — recipe for the combined per-cell CSV (mesh_id + features + cell volume V).\n3. barmesh_datasets(action=upload) then preview.\n4. barmesh_mesh_convergence (and/or barmesh_richardson) — returns a job id.\n5. barmesh_training_monitor(job_id) or barmesh_jobs(action=monitor) — blocks with throttled snapshots until done (preferred); or barmesh_jobs(status) for one-shot polls every 10-20s.\n6. barmesh_results(action=get) — distances, convergence reading, and figures; then\n   barmesh_results_explorer(job_id) to browse every figure interactively.\n\nThese tools are gated by the 'cfd' entitlement; analysis calls return 403 if your plan\ndoes not include it."});o(i,g,g,{mimeType:t},async()=>{const e=await l("barmesh-results-explorer");return{contents:[{uri:g,mimeType:t,text:e??"<html><body>Results Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),p(i),v(i),b(i),f(i),u(i),y(i),_(i),j(i);try{const e=await n(c,m,l);d(e)}catch(e){process.env.BARIVIA_VIZ_PORT&&console.error("barmesh viz server failed to start:",e)}const w=i.server;w.oninitialized=()=>{const e=w.getClientCapabilities(),r=s(e);h(!!r?.mimeTypes?.includes(t))};const x=new r;await i.connect(x),console.error(`barmesh-mcp ${a} ready (API: ${process.env.BARIVIA_API_URL??"https://api.barivia.se"})`)})().catch(e=>{console.error("Fatal error starting barmesh-mcp:",e),process.exit(1)});
+import{McpServer as e}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport as r}from"@modelcontextprotocol/sdk/server/stdio.js";import{getUiCapability as s,registerAppResource as o,RESOURCE_MIME_TYPE as n}from"@modelcontextprotocol/ext-apps/server";import{startVizServer as t}from"./viz-server.js";import{API_KEY as i,CLIENT_VERSION as a,apiCall as c,apiRawCall as m,loadViewHtml as l,setVizPort as d,setClientSupportsMcpApps as p}from"./shared.js";import{registerGuideTool as h}from"./tools/guide.js";import{registerDatasetsTool as u}from"./tools/datasets.js";import{registerCfdTools as b}from"./tools/cfd.js";import{registerJobsTool as f}from"./tools/jobs.js";import{registerResultsTool as v}from"./tools/results.js";import{registerResultsExplorerTool as y,RESULTS_EXPLORER_URI as _}from"./tools/barmesh_results_explorer.js";import{registerTrainingMonitorTool as g,TRAINING_MONITOR_URI as w}from"./tools/training_monitor.js";import{registerFeedbackTool as j}from"./tools/feedback.js";i||(console.error("Error: BARIVIA_API_KEY not set. Set it in your MCP client config."),process.exit(1));(async function(){const i=new e({name:"barmesh",version:a},{instructions:"# Barivia barmesh — CFD mesh-convergence analytics\n\nSOM-based mesh-convergence verification: compare CFD meshes of a refinement study by the\nvolume-weighted distribution their cells form on a shared self-organizing map, plus\nclassical Richardson/GCI on scalar quantities.\n\n## Two tracks\n- barmesh_mesh_convergence: high-dimensional field comparison. Symmetric KL and\n  Wasserstein-1 (EMD) distances between each mesh's SOM fingerprint and a reference,\n  and between consecutive meshes. Decreasing, plateauing distances toward the finest\n  mesh indicate sufficiency. Complements (does not replace) numerical uncertainty analysis.\n- barmesh_richardson: classical grid-convergence index on scalar QoIs.\n\n## Workflow (read-only first)\n1. barmesh_guide_workflow — orient and confirm your plan includes CFD tools.\n2. barmesh_prepare_mesh_data — recipe for the combined per-cell CSV (mesh_id + features + cell volume V).\n3. barmesh_datasets(action=upload) then preview.\n4. barmesh_mesh_convergence (and/or barmesh_richardson) — returns a job id.\n5. barmesh_training_monitor(job_id) — visual MCP App with live curves (default); barmesh_jobs(action=monitor) — headless blocking snapshots; or barmesh_jobs(status) for one-shot polls every 10-20s.\n6. barmesh_results(action=get) — distances, convergence reading, and figures; then\n   barmesh_results_explorer(job_id) to browse every figure interactively.\n\nThese tools are gated by the 'cfd' entitlement; analysis calls return 403 if your plan\ndoes not include it."});o(i,_,_,{mimeType:n},async()=>{const e=await l("barmesh-results-explorer");return{contents:[{uri:_,mimeType:n,text:e??"<html><body>Results Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),o(i,w,w,{mimeType:n},async()=>{const e=await l("barmesh-training-monitor");return{contents:[{uri:w,mimeType:n,text:e??"<html><body>Training Monitor view not built yet. Run: npm run build:views</body></html>"}]}}),h(i),y(i),u(i),b(i),f(i),g(i),v(i),j(i);try{const e=await t(c,m,l);d(e)}catch(e){process.env.BARIVIA_VIZ_PORT&&console.error("barmesh viz server failed to start:",e)}const x=i.server;x.oninitialized=()=>{const e=x.getClientCapabilities(),r=s(e);p(!!r?.mimeTypes?.includes(n))};const I=new r;await i.connect(I),console.error(`barmesh-mcp ${a} ready (API: ${process.env.BARIVIA_API_URL??"https://api.barivia.se"})`)})().catch(e=>{console.error("Fatal error starting barmesh-mcp:",e),process.exit(1)});

package/dist/job_monitor.js

@@ -6,6 +6,7 @@
 import { apiCall } from "./shared.js";
 import { formatJobStatusText } from "./job_status_format.js";
 import { pollCfdFinalizeIfPresent, refreshJobAfterFinalize } from "./cfd_finalize.js";
+import { buildPostHocReview, isTerminalStatus } from "./training_review.js";
 export const DEFAULT_BLOCK_UNTIL_SEC = 900;
 export const DEFAULT_POLL_INTERVAL_SEC = 5;
 export const MIN_POLL_INTERVAL_SEC = 5;
@@ -156,10 +157,20 @@ export async function monitorJob(job_id, options = {}) {
     const start = Date.now();
     const snapshots = [];
     let lastSnap = null;
-    let data = {};
+    let data = (await apiCall("GET", `/v1/jobs/${job_id}`));
+    const initialStatus = String(data.status ?? "");
+    if (isTerminalStatus(initialStatus)) {
+        const suggested = suggestedNextStep(job_id, data);
+        return buildPostHocReview(job_id, data, suggested);
+    }
     let heartbeat = 0;
     while (Date.now() - start < blockMs) {
-        data = (await apiCall("GET", `/v1/jobs/${job_id}`));
+        if (snapshots.length === 0) {
+            /* first fetch already done above */
+        }
+        else {
+            data = (await apiCall("GET", `/v1/jobs/${job_id}`));
+        }
         const elapsedSec = Math.round((Date.now() - start) / 1000);
         const snap = snapshotFromJob(data, elapsedSec);
         heartbeat += 1;

package/dist/results_metadata.js

@@ -0,0 +1,78 @@
+/**
+ * Compact metadata strip for barmesh_results_explorer header.
+ */
+function fmtNum(v, digits = 4) {
+    if (typeof v === "number" && Number.isFinite(v))
+        return v.toFixed(digits);
+    return v != null ? String(v) : "N/A";
+}
+function truncId(jobId) {
+    return jobId.length > 8 ? `${jobId.slice(0, 8)}…` : jobId;
+}
+function meshCellsSummary(summary) {
+    const meshes = summary.meshes ?? [];
+    if (meshes.length === 0)
+        return "N/A";
+    return meshes
+        .map((m) => `${String(m.mesh ?? "?")}:${m.n_cells ?? "?"}`)
+        .join(", ");
+}
+export function buildMetadataStrip(jobId, data, jobMeta) {
+    const summary = (data.summary ?? {});
+    const label = data.label != null && data.label !== ""
+        ? String(data.label)
+        : jobMeta?.label != null
+            ? String(jobMeta.label)
+            : null;
+    const jobType = String(summary.job_type ?? "cfd_mesh_convergence");
+    const datasetName = jobMeta?.dataset_name != null ? String(jobMeta.dataset_name) : null;
+    const grid = summary.grid ?? [];
+    const epochs = summary.epochs ?? [];
+    const epochStr = epochs.length >= 2 ? `[${epochs[0]},${epochs[1]}]` : epochs.length === 1 ? String(epochs[0]) : "N/A";
+    const line1 = [
+        label ? `label ${label}` : null,
+        `job ${truncId(jobId)}`,
+        jobType,
+        datasetName ? `dataset ${datasetName}` : null,
+    ]
+        .filter(Boolean)
+        .join(" · ");
+    const nTrain = summary.n_train_total != null ? String(summary.n_train_total) : null;
+    const ref = summary.reference_mesh != null ? String(summary.reference_mesh) : null;
+    const meshOrder = Array.isArray(summary.mesh_order) && summary.mesh_order.length > 0
+        ? summary.mesh_order.map(String).join("→")
+        : null;
+    const line2 = [
+        nTrain != null ? `n_train ${nTrain}` : null,
+        meshOrder ? `meshes ${meshOrder}` : `cells ${meshCellsSummary(summary)}`,
+        ref ? `ref ${ref}` : null,
+    ]
+        .filter(Boolean)
+        .join(" · ");
+    const wall = jobMeta?.wall_elapsed_sec != null ? Math.round(Number(jobMeta.wall_elapsed_sec)) : null;
+    const kernel = jobMeta?.kernel_elapsed_sec != null
+        ? Math.round(Number(jobMeta.kernel_elapsed_sec))
+        : jobMeta?.training_elapsed_sec != null
+            ? Math.round(Number(jobMeta.training_elapsed_sec))
+            : null;
+    const line3 = [
+        `preset ${String(summary.preset ?? "generic")}`,
+        grid.length >= 2 ? `grid ${grid[0]}×${grid[1]}` : null,
+        `epochs ${epochStr}`,
+        summary.batch_size != null ? `batch ${summary.batch_size}` : null,
+        summary.stratify_scale != null ? `stratify ${summary.stratify_scale}` : null,
+        summary.backend != null ? `backend ${summary.backend}` : null,
+    ]
+        .filter(Boolean)
+        .join(" · ");
+    const line4 = [
+        wall != null ? `wall ${wall}s` : null,
+        kernel != null ? `kernel ${kernel}s` : null,
+        summary.quantization_error != null ? `QE ${fmtNum(summary.quantization_error)}` : null,
+        summary.topographic_error != null ? `TE ${fmtNum(summary.topographic_error)}` : null,
+        summary.emd_method != null ? `emd ${summary.emd_method}` : null,
+    ]
+        .filter(Boolean)
+        .join(" · ");
+    return [line1, line2, line3, line4].filter((l) => l.length > 0);
+}

package/dist/tools/barmesh_results_explorer.js

@@ -2,29 +2,14 @@ import { z } from "zod";
 import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
 import { registerAuditedTool, runMcpToolAudit } from "../audit.js";
 import { apiCall, apiRawCall, getClientSupportsMcpApps, getVizPort, getCaptionForImage, mimeForFilename, structuredTextResult, tryAttachImage, } from "../shared.js";
+import { FIGURE_SECTION_LABELS, FIGURE_SECTION_ORDER, figureSection, sortRank, } from "../figure_sections.js";
+import { buildMetadataStrip } from "../results_metadata.js";
 export const RESULTS_EXPLORER_URI = "ui://barmesh/results-explorer";
-const FIGURE_SORT_RANK = {
-    combined: 0,
-    overview_distances: 1,
-    KL_ref: 10,
-    KL_stepwise: 11,
-    EMD_ref: 12,
-    EMD_stepwise: 13,
-    learning_curve: 14,
-    plot_vol_all_meshes: 19,
-    plot_vol_coarse_fine: 20,
-};
-function sortRank(key) {
-    if (key in FIGURE_SORT_RANK)
-        return FIGURE_SORT_RANK[key];
-    if (key.startsWith("plot_vol"))
-        return 25;
-    if (key.startsWith("plot_"))
-        return 30;
-    return 50;
-}
 export function sortFigures(figures) {
-    return [...figures].sort((a, b) => sortRank(a.key) - sortRank(b.key) || a.label.localeCompare(b.label));
+    return [...figures].sort((a, b) => FIGURE_SECTION_ORDER.indexOf(a.section ?? "diagnostics") -
+        FIGURE_SECTION_ORDER.indexOf(b.section ?? "diagnostics") ||
+        sortRank(a.key) - sortRank(b.key) ||
+        a.label.localeCompare(b.label));
 }
 export function resolveDefaultFigureKey(figures) {
     const byKey = (k) => figures.find((f) => f.key === k);
@@ -63,45 +48,23 @@ function labelForFigure(filename) {
         return `Component plane: ${base.replace(/^plot_/, "").replace(/_/g, " ")}`;
     return base.replace(/_/g, " ");
 }
-function figureKind(base) {
-    if (base === "combined")
-        return "summary";
-    if (base.startsWith("plot_") && !base.startsWith("plot_vol_"))
-        return "component";
-    return "diagnostic";
-}
 function buildMetrics(summary) {
     const grid = summary.grid ?? [];
     const qe = summary.quantization_error != null ? Number(summary.quantization_error).toFixed(4) : "N/A";
     const te = summary.topographic_error != null ? Number(summary.topographic_error).toFixed(4) : "N/A";
     const meshes = summary.meshes ?? [];
+    const epochs = summary.epochs ?? [];
     return [
         { label: "Grid", value: grid.length >= 2 ? `${grid[0]}×${grid[1]}` : "N/A" },
         { label: "Preset", value: String(summary.preset ?? "generic") },
         { label: "Reference", value: String(summary.reference_mesh ?? "N/A") },
         { label: "Meshes", value: String(meshes.length || "N/A") },
+        { label: "Epochs", value: epochs.length >= 2 ? `${epochs[0]}+${epochs[1]}` : "N/A" },
         { label: "QE", value: qe },
         { label: "TE", value: te },
         { label: "EMD method", value: String(summary.emd_method ?? "exact") },
     ];
 }
-function buildHighlights(summary) {
-    const out = [];
-    const convergence = summary.convergence;
-    const emd = convergence?.emd;
-    const skl = convergence?.skl;
-    if (emd) {
-        const plateau = emd.plateau === true ? "plateauing" : "not yet plateauing";
-        const mono = emd.monotonic_decrease === true ? "monotonic decrease" : "non-monotonic";
-        out.push(`EMD vs reference: ${mono}, ${plateau}.`);
-    }
-    if (skl) {
-        const plateau = skl.plateau === true ? "plateauing" : "not yet plateauing";
-        out.push(`Symmetric KL vs reference: ${plateau}.`);
-    }
-    out.push("Advisory: SOM distances complement, not replace, numerical uncertainty analysis (Richardson/GCI).");
-    return out;
-}
 /**
  * Group `<base>.<ext>` figure files into one logical figure per base, collecting the
  * available formats. Preview is the inline-displayable raster (PNG, else SVG); the
@@ -138,12 +101,12 @@ export function groupFigures(files) {
             filename: preview,
             downloadFilename,
             formats,
-            kind: figureKind(base),
+            section: figureSection(base),
             caption: [baseCaption, vectorNote, emptyNote].filter(Boolean).join(" ") || undefined,
         };
     });
 }
-export function buildPayload(jobId, data) {
+export function buildPayload(jobId, data, jobMeta) {
     const summary = (data.summary ?? {});
     const files = (summary.files ?? []).filter((f) => /\.(png|pdf|svg)$/i.test(f));
     const figures = sortFigures(groupFigures(files));
@@ -153,8 +116,8 @@ export function buildPayload(jobId, data) {
         jobId,
         title: "Mesh Convergence Results",
         subtitle: String(data.label ?? ""),
+        metadataStrip: buildMetadataStrip(jobId, data, jobMeta),
         metrics: buildMetrics(summary),
-        highlights: buildHighlights(summary),
         availableFigures: figures,
         defaultFigureKey: resolveDefaultFigureKey(figures),
         standaloneUrl: port
@@ -163,15 +126,18 @@ export function buildPayload(jobId, data) {
     };
 }
 async function handleResultsExplorer(job_id) {
-    const data = (await apiCall("GET", `/v1/results/${job_id}`));
-    const payload = buildPayload(job_id, data);
+    const [data, jobMeta] = await Promise.all([
+        apiCall("GET", `/v1/results/${job_id}`),
+        apiCall("GET", `/v1/jobs/${job_id}`).catch(() => ({})),
+    ]);
+    const payload = buildPayload(job_id, data, jobMeta);
     const content = [
         {
             type: "text",
             text: [
                 `Mesh convergence results explorer ready for job ${job_id}.`,
                 payload.subtitle ? `Label: ${payload.subtitle}` : "",
-                payload.highlights[0] ?? "",
+                payload.metadataStrip?.[0] ?? "",
             ]
                 .filter(Boolean)
                 .join("\n"),
@@ -181,6 +147,14 @@ async function handleResultsExplorer(job_id) {
     if (defaultFigure && /\.(png|svg|jpe?g|webp)$/i.test(defaultFigure.filename)) {
         await tryAttachImage(content, job_id, defaultFigure.filename);
     }
+    if (payload.standaloneUrl) {
+        content.push({
+            type: "text",
+            text: `Standalone results explorer URL (copy if Open is blocked):\n${payload.standaloneUrl}\n` +
+                `AGENT: surface this URL to the user — markdown link or copy/paste into a browser when the inline MCP panel cannot open localhost. ` +
+                `This localhost port is per MCP session and goes stale if the proxy restarts — re-run barmesh_results_explorer for a fresh URL, or set BARIVIA_VIZ_PORT for a persistent port.`,
+        });
+    }
     if (!getClientSupportsMcpApps() && payload.standaloneUrl) {
         content.push({
             type: "text",
@@ -194,7 +168,7 @@ async function handleResultsExplorer(job_id) {
 export function registerResultsExplorerTool(server) {
     const toolConfig = {
         title: "Mesh Convergence Results Explorer",
-        description: "PREFERRED way to browse a completed mesh_convergence job after a first barmesh_results(get) glance. Interactive explorer with a figure dropdown above the plot (component-plane mosaic headline, distances, volume fingerprints, learning curve, per-feature planes). Each figure shows its PNG preview inline (PDFs cannot render in the sandboxed panel) and offers the best-quality vector (PDF/SVG) for download when rendered (barmesh_results(action=render, format=pdf)). Embeds as an MCP App or falls back to a standalone localhost page. barmesh_results(action=get) remains the headless/metrics path.",
+        description: "PREFERRED way to browse a completed mesh_convergence job after a first barmesh_results(get) glance. Interactive explorer with a grouped figure dropdown (Overview → Distances → Diagnostics → Component planes): combined mosaic headline, overview_distances, KL/EMD panels, learning curve, volume fingerprints, per-feature planes. Header shows job/dataset/training metadata from status + summary.json. Convergence reading lives in barmesh_results(get) / summary.convergence only — not repeated here. Each figure shows its PNG preview inline (PDFs cannot render in the sandboxed panel) and offers vector download when rendered. Embeds as an MCP App or falls back to a standalone localhost page.",
         inputSchema: {
             job_id: z.string().describe("Job ID of a completed cfd_mesh_convergence job"),
         },
@@ -219,3 +193,4 @@ export function registerResultsExplorerTool(server) {
         }
     });
 }
+export { FIGURE_SECTION_LABELS, FIGURE_SECTION_ORDER, figureSection };

package/dist/tools/guide.js

@@ -2,7 +2,7 @@ import { registerAuditedTool } from "../audit.js";
 import { apiCall, textResult } from "../shared.js";
 const OFFLINE_GUIDE = `barmesh: CFD mesh-convergence on the Barivia API.
 Two tracks: barmesh_mesh_convergence (SOM fingerprint distances) and barmesh_richardson (classical GCI).
-Workflow: barmesh_prepare_mesh_data -> barmesh_datasets(upload) -> barmesh_mesh_convergence / barmesh_richardson -> barmesh_training_monitor (or barmesh_jobs monitor/status) -> barmesh_results(get).
+Workflow: barmesh_prepare_mesh_data -> barmesh_datasets(upload) -> barmesh_mesh_convergence / barmesh_richardson -> barmesh_training_monitor (default visual MCP App; post-hoc review when already done) or barmesh_jobs(monitor/status) headless fallback -> barmesh_results(get) -> barmesh_results_explorer for figures.
 (API unreachable; this is the offline summary. Set BARIVIA_API_KEY / BARIVIA_API_URL.)`;
 const OFFLINE_PREP = `barmesh mesh-data prep (offline summary; API unreachable):
 Build ONE combined per-cell CSV across all meshes of the refinement study:

package/dist/tools/jobs.js

@@ -4,12 +4,13 @@ import { apiCall, textResult } from "../shared.js";
 import { pollCfdFinalizeIfPresent, refreshJobAfterFinalize } from "../cfd_finalize.js";
 import { formatJobStatusText } from "../job_status_format.js";
 import { DEFAULT_BLOCK_UNTIL_SEC, DEFAULT_POLL_INTERVAL_SEC } from "../job_monitor.js";
-import { runMonitor } from "./training_monitor.js";
+import { runBlockingMonitor } from "../blocking_monitor.js";
 export function registerJobsTool(server) {
     registerAuditedTool(server, "barmesh_jobs", `Check job status, block until terminal, or list jobs.
 
 BEST FOR: action=monitor after submit (one call, throttled snapshots — preferred for agents). action=status for a single one-shot check.
-ASYNC PROTOCOL: monitor blocks server-side until completed/failed or block_until timeout (default ${DEFAULT_BLOCK_UNTIL_SEC}s, poll every ${DEFAULT_POLL_INTERVAL_SEC}s). status is one-shot; poll every 10-20s manually if not using monitor. When status=completed, call barmesh_results(action=get, job_id=...).
+MONITOR MODES: barmesh_training_monitor — default visual MCP App (live curves, post-hoc review on completed jobs). barmesh_jobs(action=monitor) — headless blocking snapshots for agents (live or post-hoc review; attaches learning_curve.png when already completed).
+ASYNC PROTOCOL: monitor blocks server-side until completed/failed or block_until timeout (default ${DEFAULT_BLOCK_UNTIL_SEC}s, poll every ${DEFAULT_POLL_INTERVAL_SEC}s). status is one-shot; poll every 10-20s manually if not using monitor. When status=completed, call barmesh_results(action=get, job_id=...) then barmesh_results_explorer(job_id=...).
 ESCALATION: status=failed returns an error message and (when available) a failure_stage; read it before retrying.`, {
         action: z
             .enum(["status", "monitor", "list"])
@@ -36,7 +37,7 @@ ESCALATION: status=failed returns an error message and (when available) a failur
         if (action === "monitor") {
             if (!job_id)
                 throw new Error("barmesh_jobs(monitor) requires job_id.");
-            return runMonitor({ job_id, block_until_sec, poll_interval_sec, wait_finalize });
+            return runBlockingMonitor({ job_id, block_until_sec, poll_interval_sec, wait_finalize });
         }
         if (action === "status") {
             if (!job_id)

package/dist/tools/results.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
 import { apiCall, apiRawCall, getWorkspaceRootAsync, sandboxPath, textResult, tryAttachImage, resetInlineAttachBudget, pollUntilComplete, POLL_STAGE_MAX_MS, } from "../shared.js";
+import { formatConvergenceReading } from "../convergence_reading.js";
 const MESH_DEFAULT_FIGURES = ["combined", "overview_distances", "plot_vol_all_meshes", "plot_vol_steps", "learning_curve"];
 function formatMeshResultsSummary(jobId, data, summary) {
     const label = data.label != null && data.label !== "" ? String(data.label) : null;
@@ -13,18 +14,7 @@ function formatMeshResultsSummary(jobId, data, summary) {
     const fmt = (v) => (typeof v === "number" && Number.isFinite(v) ? v.toFixed(4) : String(v ?? "N/A"));
     const meshLines = meshes.map((m) => `  ${String(m.mesh ?? "?")} (n=${m.n_cells ?? "?"}): SKL→ref=${fmt(m.skl_to_ref)} EMD→ref=${fmt(m.emd_to_ref)}`);
     const stepLines = stepwise.map((s) => `  ${String(s.pair ?? "?")}: EMD=${fmt(s.emd)} KL↓=${fmt(s.kl_coarsen)} KL↑=${fmt(s.kl_refine)}`);
-    const convergence = summary.convergence;
-    const emd = convergence?.emd;
-    const skl = convergence?.skl;
-    const reading = [];
-    if (emd) {
-        const plateau = emd.plateau === true ? "plateauing" : "not yet plateauing";
-        const mono = emd.monotonic_decrease === true ? "monotonic decrease toward reference" : "non-monotonic vs reference";
-        reading.push(`EMD vs ${String(summary.reference_mesh ?? "reference")}: ${mono}, ${plateau}.`);
-    }
-    if (skl) {
-        reading.push(`Symmetric KL vs reference: ${skl.plateau === true ? "plateauing" : "not yet plateauing"}.`);
-    }
+    const readingLine = formatConvergenceReading(summary);
     const ord = summary.ordering_errors;
     const conv = summary.convergence_errors;
     const curveNote = (ord?.length ?? 0) > 0 || (conv?.length ?? 0) > 0
@@ -36,7 +26,7 @@ function formatMeshResultsSummary(jobId, data, summary) {
         `QE: ${fmt(summary.quantization_error)} | TE: ${fmt(summary.topographic_error)} | EMD method: ${String(summary.emd_method ?? "exact")}`,
         meshes.length > 0 ? `\nDistances vs reference:\n${meshLines.join("\n")}` : "",
         stepLines.length > 0 ? `\nStepwise:\n${stepLines.join("\n")}` : "",
-        reading.length > 0 ? `\nConvergence reading:\n${reading.map((l) => `  ${l}`).join("\n")}` : "",
+        readingLine ? `\nConvergence: ${readingLine}` : "",
         curveNote,
         "\nAdvisory: SOM distances complement, not replace, numerical uncertainty analysis (use barmesh_richardson for classical GCI).",
         "For every figure: barmesh_results_explorer(job_id) or barmesh_results(action=download). Use figures=\"none\" to skip inline images.",

package/dist/tools/training_monitor.js

@@ -1,56 +1,76 @@
 import { z } from "zod";
-import { registerAuditedTool } from "../audit.js";
-import { textResult } from "../shared.js";
-import { DEFAULT_BLOCK_UNTIL_SEC, DEFAULT_POLL_INTERVAL_SEC, formatMonitorText, monitorJob, } from "../job_monitor.js";
-const MONITOR_DESCRIPTION = `Block until a barmesh_mesh_convergence or barmesh_richardson job reaches a terminal state, emitting compact progress snapshots along the way.
-
-BEST FOR: After job submit — one call replaces manual barmesh_jobs(status) poll loops (10–20s × several minutes).
-ASYNC PROTOCOL: Server-side poll every ~5s (configurable) until completed/failed/cancelled or block_until timeout. Snapshots include phase, epoch/total, QE/TE, ETA, and ordering_errors tail when live.
-FINALIZE: When defer_figures is used, waits for cfd_finalize and adds a snapshot when figure render starts/completes.
-NOT REQUIRED: barmesh_jobs(action=status) still works for one-shot checks; this tool is the agent-friendly blocking variant (barsom training_monitor parity for headless workflows).
-ESCALATION: On timeout, re-run with a higher block_until_sec; on failed, read failure_stage in the final snapshot.`;
-const monitorSchema = {
-    job_id: z.string().describe("Job ID from barmesh_mesh_convergence or barmesh_richardson"),
-    block_until_sec: z
-        .number()
-        .int()
-        .min(30)
-        .optional()
-        .describe(`Max seconds to wait (default ${DEFAULT_BLOCK_UNTIL_SEC}; mesh jobs often need 6–10 min)`),
-    poll_interval_sec: z
-        .number()
-        .int()
-        .min(5)
-        .optional()
-        .describe(`Seconds between status polls (default ${DEFAULT_POLL_INTERVAL_SEC}; do not go below 5)`),
-    wait_finalize: z
-        .boolean()
-        .optional()
-        .describe("When true (default), wait for cfd_finalize after compute completes before returning"),
-};
-async function runMonitor(args) {
-    const block_until_sec = args.block_until_sec ?? DEFAULT_BLOCK_UNTIL_SEC;
-    const poll_interval_sec = args.poll_interval_sec ?? DEFAULT_POLL_INTERVAL_SEC;
-    const result = await monitorJob(args.job_id, {
-        block_until_sec,
-        poll_interval_sec,
-        wait_finalize: args.wait_finalize,
-    });
-    const text = formatMonitorText(result, { block_until_sec, poll_interval_sec });
-    return textResult({
-        ...result.data,
-        monitor: {
-            job_id: result.job_id,
-            terminal: result.terminal,
-            timed_out: result.timed_out,
-            snapshots: result.snapshots,
-            status_text: result.status_text,
-            suggested_next_step: result.suggested_next_step,
-        },
-        status_text: text,
-    });
+import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
+import { runMcpToolAudit } from "../audit.js";
+import { apiCall, getClientSupportsMcpApps, getVizPort, structuredTextResult, } from "../shared.js";
+import { enrichWithTrainingLog, hasCurveArrays } from "../training_review.js";
+export const TRAINING_MONITOR_URI = "ui://barmesh/training-monitor";
+export const TRAINING_MONITOR_REFRESH_MS = 5000;
+function buildStructuredContent(job_id, data) {
+    const id = String(data.id ?? job_id);
+    return {
+        ...data,
+        type: "barmesh-training-monitor",
+        jobId: id,
+        id,
+        job_id: id,
+        refresh_interval_ms: TRAINING_MONITOR_REFRESH_MS,
+    };
 }
 export function registerTrainingMonitorTool(server) {
-    registerAuditedTool(server, "barmesh_training_monitor", MONITOR_DESCRIPTION, monitorSchema, runMonitor);
+    registerAppTool(server, "barmesh_training_monitor", {
+        title: "Mesh Convergence Training Monitor",
+        description: "Default visual monitor for mesh_convergence jobs after submit. Embedded MCP App auto-refreshes every 5s: epoch progress bar, phase, ETA, live QE/TE curves (uniformly subsampled to ≤1000 batch samples per phase), and a per-epoch hit-grid heatmap when available. On already-completed jobs, replays training-log curves in review mode (same entry point). Also exposes a standalone localhost URL — copy it if window.open is blocked in your MCP host. Headless fallback: barmesh_jobs(action=monitor) blocks with compact text snapshots (live or post-hoc review). barmesh_jobs(action=status) remains a one-shot poll. After completion, use barmesh_results_explorer for figures.",
+        inputSchema: {
+            job_id: z.string().describe("Job ID from barmesh_mesh_convergence or barmesh_richardson"),
+            fetch_training_log: z
+                .boolean()
+                .optional()
+                .describe("Internal: merge completed-job training-log arrays when live progress is empty"),
+        },
+        _meta: { ui: { resourceUri: TRAINING_MONITOR_URI } },
+    }, async (args) => runMcpToolAudit("barmesh_training_monitor", "default", args, async () => {
+        const { job_id, fetch_training_log } = args;
+        let data = (await apiCall("GET", `/v1/jobs/${job_id}`));
+        const jobStatus = String(data.status ?? "");
+        const terminal = jobStatus === "completed" || jobStatus === "failed";
+        if (fetch_training_log || (terminal && !hasCurveArrays(data))) {
+            data = await enrichWithTrainingLog(job_id, data);
+        }
+        const structuredContent = buildStructuredContent(job_id, data);
+        const progress = (data.progress ?? 0) * 100;
+        const etaSec = data.training_eta_sec != null ? Number(data.training_eta_sec) : null;
+        const elapsedSec = data.training_elapsed_sec != null ? Number(data.training_elapsed_sec) : null;
+        const epoch = data.epoch != null ? Number(data.epoch) : null;
+        const totalEpochs = data.total_epochs != null ? Number(data.total_epochs) : null;
+        const timingParts = [];
+        if (elapsedSec != null && elapsedSec >= 0)
+            timingParts.push(`elapsed ${Math.round(elapsedSec)}s`);
+        if (etaSec != null && etaSec > 0)
+            timingParts.push(`ETA ~${Math.round(etaSec)}s`);
+        if (epoch != null && totalEpochs != null)
+            timingParts.push(`epoch ${epoch}/${totalEpochs}`);
+        const timingNote = timingParts.length > 0 ? ` ${timingParts.join(", ")}.` : "";
+        const modeNote = terminal ? " (post-hoc review — training-log curves)" : "";
+        const text = `Training monitor (visual MCP App, refreshes every ${TRAINING_MONITOR_REFRESH_MS / 1000}s): job ${job_id} — ${jobStatus} (${progress.toFixed(1)}%).${modeNote}${timingNote}`;
+        const content = [{ type: "text", text }];
+        const port = getVizPort();
+        const standaloneUrl = port
+            ? `http://localhost:${port}/viz/barmesh-training-monitor?mode=standalone&job_id=${encodeURIComponent(job_id)}`
+            : undefined;
+        if (standaloneUrl) {
+            content.push({
+                type: "text",
+                text: `Standalone training monitor URL (copy if Open is blocked):\n${standaloneUrl}\n` +
+                    `AGENT: surface this URL to the user — use a markdown link or tell them to copy/paste into a browser when the inline panel cannot open localhost. Re-post after the job completes so they can review curves.\n` +
+                    `This localhost port is per MCP session and goes stale if the proxy restarts — re-run barmesh_training_monitor for a fresh URL, or set BARIVIA_VIZ_PORT for a persistent port. Health check: http://localhost:${port}/api/health?job_id=${encodeURIComponent(job_id)}`,
+            });
+        }
+        if (!getClientSupportsMcpApps() && standaloneUrl) {
+            content.push({
+                type: "text",
+                text: `Interactive training monitor: [Open training monitor](${standaloneUrl})`,
+            });
+        }
+        return structuredTextResult(structuredContent, text, content);
+    }));
 }
-export { runMonitor, MONITOR_DESCRIPTION, monitorSchema };

package/dist/training_monitor_curve.js

@@ -0,0 +1,30 @@
+/** Batch-sample x-axis helpers for the barmesh_training_monitor MCP App chart. */
+export function batchSampleAxis(n, offset = 0) {
+    if (n <= 0)
+        return [];
+    return Array.from({ length: n }, (_, i) => offset + i + 1);
+}
+export function combinedBatchAxis(nOrd, nConv) {
+    if (nOrd <= 0 && nConv <= 0)
+        return [];
+    return [...batchSampleAxis(nOrd, 0), ...batchSampleAxis(nConv, nOrd)];
+}
+export function formatCurveSourceNote(data) {
+    const src = data.training_curve_source_batches;
+    if (!src)
+        return null;
+    const parts = [];
+    const ordTotal = typeof src.ordering === "number" ? src.ordering : null;
+    const convTotal = typeof src.convergence === "number" ? src.convergence : null;
+    const ordShown = Array.isArray(data.ordering_errors) ? data.ordering_errors.length : 0;
+    const convShown = Array.isArray(data.convergence_errors) ? data.convergence_errors.length : 0;
+    if (ordTotal != null && ordTotal > ordShown) {
+        parts.push(`${ordShown} of ${ordTotal.toLocaleString()} ordering batch samples`);
+    }
+    if (convTotal != null && convTotal > convShown) {
+        parts.push(`${convShown} of ${convTotal.toLocaleString()} convergence batch samples`);
+    }
+    if (parts.length === 0)
+        return null;
+    return `Displaying uniformly subsampled curves (≤1000 points/phase): ${parts.join("; ")}.`;
+}