@barivia/barmesh-mcp 0.5.3 → 0.6.0

package/README.md

@@ -65,7 +65,8 @@ API key; otherwise the analysis calls return HTTP 403. Contact Barivia to enable
 
 - **Combined overview (`combined.png`):** barsom-style **grid of all component planes**
   on the trained SOM — the primary headline artifact. A separate
-  `overview_distances.png` holds the KL/EMD/volume diagnostic mosaic.
+  `overview_distances.png` holds the KL/EMD diagnostic mosaic (all four distance panels).
+  `plot_vol_all_meshes.png` shows volume fingerprints for every mesh in mesh_order.
 - **Learning curve:** every job produces `learning_curve.png` (QE by epoch) for training
   quality inspection; listed in the results explorer dropdown.
 - **PDFs on demand:** publication vector PDFs are NOT generated by default. Render them

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/shared.js

@@ -22,7 +22,7 @@ export const FETCH_TIMEOUT_MS = parseInt(process.env.BARIVIA_FETCH_TIMEOUT_MS ??
 export const MAX_RETRIES = 2;
 export const RETRYABLE_STATUS = new Set([502, 503, 504]);
 /** Single source of truth for the proxy version. Keep in sync with package.json on bump. */
-export const CLIENT_VERSION = "0.5.3";
+export const CLIENT_VERSION = "0.5.4";
 export const PUBLIC_SITE_ORIGIN = "https://barivia.se";
 /** Large per-cell CSV uploads may exceed the default fetch timeout. */
 export const UPLOAD_DATASET_TIMEOUT_MS = 180_000;
@@ -389,7 +389,7 @@ export function getCaptionForImage(filename) {
     if (base === "combined")
         return "All feature component planes on the trained SOM in one grid — primary comparison artifact (barsom-style combined view).";
     if (base === "overview_distances")
-        return "Diagnostic mosaic: volume fingerprints plus KL and EMD vs the reference mesh.";
+        return "Diagnostic mosaic: KL and EMD vs reference and stepwise (all distance panels).";
     if (base === "learning_curve")
         return "Quantization error by epoch: ordering phase (steel blue) then convergence (coral).";
     if (base === "KL_ref")
@@ -400,6 +400,8 @@ export function getCaptionForImage(filename) {
         return "Wasserstein-1 (EMD) distance from each mesh to the reference. A monotone decrease toward the finest mesh indicates field-level convergence.";
     if (base === "EMD_stepwise")
         return "Stepwise EMD between consecutive meshes. Small, plateauing values on the finest pairs indicate the fingerprint has stopped changing.";
+    if (base === "plot_vol_all_meshes")
+        return "Volume-weighted SOM fingerprints P_vol for every mesh in mesh_order (shared color scale).";
     if (base === "plot_vol_coarse_fine")
         return "Volume-weighted SOM fingerprints P_vol for the coarsest and reference meshes (shared color scale).";
     if (base.startsWith("plot_vol_steps") || base.startsWith("plot_vol_seven_steps"))
@@ -428,6 +430,12 @@ export async function loadViewHtml(viewName) {
     }
     return null;
 }
+export const MAX_INLINE_BYTES = parseInt(process.env.BARIVIA_MAX_INLINE_BYTES ?? "8000000", 10);
+let _inlineAttachBytesUsed = 0;
+/** Reset inline image byte budget (call at the start of each MCP tool response). */
+export function resetInlineAttachBudget() {
+    _inlineAttachBytesUsed = 0;
+}
 export async function tryAttachImage(content, jobId, filename) {
     if (filename.endsWith(".pdf") || filename.endsWith(".svg")) {
         content.push({
@@ -441,6 +449,14 @@ export async function tryAttachImage(content, jobId, filename) {
         content.push({ type: "text", text: `${filename}: ${caption}` });
     try {
         const { data: imgBuf } = await apiRawCall(`/v1/results/${jobId}/image/${filename}`);
+        if (_inlineAttachBytesUsed + imgBuf.length > MAX_INLINE_BYTES) {
+            content.push({
+                type: "text",
+                text: `(${filename} omitted — inline image budget exceeded; use barmesh_results(action=image, job_id="${jobId}", filename="${filename}") or action=download)`,
+            });
+            return;
+        }
+        _inlineAttachBytesUsed += imgBuf.length;
         content.push({
             type: "image",
             data: imgBuf.toString("base64"),

package/dist/tools/barmesh_results_explorer.js

@@ -2,28 +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_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);
@@ -52,6 +38,8 @@ function labelForFigure(filename) {
         return "Wasserstein (EMD) vs reference";
     if (base === "EMD_stepwise")
         return "Wasserstein (EMD) stepwise";
+    if (base === "plot_vol_all_meshes")
+        return "Volume fingerprint: all meshes";
     if (base === "plot_vol_coarse_fine")
         return "Volume fingerprint: coarse vs reference";
     if (base.startsWith("plot_vol_"))
@@ -60,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
@@ -135,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));
@@ -150,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
@@ -160,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"),
@@ -178,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",
@@ -191,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"),
         },
@@ -216,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

@@ -2,8 +2,36 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
-import { apiCall, apiRawCall, getWorkspaceRootAsync, sandboxPath, textResult, tryAttachImage, pollUntilComplete, POLL_STAGE_MAX_MS, } from "../shared.js";
-const MESH_DEFAULT_FIGURES = ["combined", "overview_distances", "KL_ref", "EMD_ref", "plot_vol_coarse_fine", "learning_curve"];
+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;
+    const header = label ? `Mesh convergence results for ${label} (job_id: ${jobId})` : `Mesh convergence results for job_id: ${jobId}`;
+    const grid = summary.grid ?? [];
+    const meshes = summary.meshes ?? [];
+    const stepwise = summary.stepwise ?? [];
+    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 readingLine = formatConvergenceReading(summary);
+    const ord = summary.ordering_errors;
+    const conv = summary.convergence_errors;
+    const curveNote = (ord?.length ?? 0) > 0 || (conv?.length ?? 0) > 0
+        ? `Training curves: ${ord?.length ?? 0} ordering + ${conv?.length ?? 0} convergence batch samples (≤1000 each in API/MCP responses).`
+        : "";
+    return [
+        header,
+        `Preset: ${String(summary.preset ?? "generic")} | Grid: ${grid.length >= 2 ? `${grid[0]}×${grid[1]}` : "N/A"} | Reference: ${String(summary.reference_mesh ?? "N/A")}`,
+        `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")}` : "",
+        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.",
+    ].filter(Boolean).join("\n");
+}
 const TEXT_ARTIFACTS = [
     "summary.json",
     "distances.csv",
@@ -23,7 +51,7 @@ export function registerResultsTool(server) {
 | download | Save figures and metrics to a local folder (headless / agent path). |
 
 BEST FOR: After barmesh_jobs(action=status) shows completed (and finalize finished if defer_figures was used).
-FIGURES: Default output includes combined.png (component-plane mosaic), overview_distances.png, learning_curve.png, and per-panel PNGs. action=get inlines headline panels; pass figures="all" for every PNG, "none" for metrics only.
+FIGURES: Default bundle is combined.png, overview_distances.png (all KL/EMD panels), plot_vol_all_meshes.png, plot_vol_steps.png, and learning_curve.png — not redundant per-feature PNGs. action=get inlines the headline set; pass figures="all" for every artifact listed in summary.files, figures="none" for metrics only (recommended for agents).
 PDFs ON DEMAND: vector PDFs are not produced by default. Use action=render (format=pdf) once, then action=image or action=download.
 If GET /v1/results returns 404 shortly after status=completed, cfd_finalize may still be rendering — poll barmesh_jobs(status) until finalize_job_id completes.
 NOT FOR: Submitting jobs.`, {
@@ -96,9 +124,18 @@ NOT FOR: Submitting jobs.`, {
             const files = summary.files ?? [];
             const isImage = (f) => /\.(png|svg|pdf)$/i.test(f);
             let toDownload;
-            if (figures === "all" || figures === undefined) {
+            if (figures === "all") {
                 toDownload = include_json ? files : files.filter(isImage);
             }
+            else if (figures === undefined) {
+                toDownload = MESH_DEFAULT_FIGURES.flatMap((b) => files.filter((f) => f.replace(/\.[^.]+$/, "") === b || f.startsWith(`${b}.`)));
+                if (include_json) {
+                    for (const t of TEXT_ARTIFACTS) {
+                        if (files.includes(t) && !toDownload.includes(t))
+                            toDownload.push(t);
+                    }
+                }
+            }
             else if (Array.isArray(figures)) {
                 toDownload = figures.flatMap((key) => {
                     if (/\.(png|pdf|svg|csv|txt|json)$/i.test(key))
@@ -139,9 +176,10 @@ NOT FOR: Submitting jobs.`, {
                 ? `Saved ${saved.length} file(s) to ${savedDir}: ${saved.join(", ")}`
                 : `No files saved. Check job_id and that the job (and cfd_finalize, if any) is completed.`);
         }
-        let summary;
+        resetInlineAttachBudget();
+        let data;
         try {
-            summary = (await apiCall("GET", `/v1/results/${job_id}`));
+            data = (await apiCall("GET", `/v1/results/${job_id}`));
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -154,7 +192,8 @@ NOT FOR: Submitting jobs.`, {
             }
             throw err;
         }
-        const content = [{ type: "text", text: JSON.stringify(summary, null, 2) }];
+        const summary = (data.summary ?? {});
+        const content = [{ type: "text", text: formatMeshResultsSummary(job_id, data, summary) }];
         if (figures === "none")
             return { content };
         const allFiles = summary.files ?? [];