@barivia/barmesh-mcp 0.5.4 → 0.6.1

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;
@@ -91,7 +92,7 @@ export function formatSnapshotLine(s) {
     if (s.qe != null)
         parts.push(`QE ${s.qe.toFixed(4)}`);
     if (s.te != null)
-        parts.push(`TE ${s.te.toFixed(4)}`);
+        parts.push(`Epoch TE ${s.te.toFixed(4)}`);
     if (s.eta_sec != null)
         parts.push(`ETA ~${s.eta_sec}s`);
     if (s.ordering_errors_tail?.length) {
@@ -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.4";
+export const CLIENT_VERSION = "0.6.1";
 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;

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",
@@ -189,12 +163,15 @@ async function handleResultsExplorer(job_id) {
                 `This localhost port is assigned per MCP session and changes if the proxy restarts — re-run barmesh_results_explorer for a fresh URL, or set BARIVIA_VIZ_PORT for a persistent port.`,
         });
     }
-    return structuredTextResult(payload, undefined, content);
+    return {
+        ...structuredTextResult(payload, undefined, content),
+        _meta: { ui: { resourceUri: RESULTS_EXPLORER_URI } },
+    };
 }
 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 +196,4 @@ export function registerResultsExplorerTool(server) {
         }
     });
 }
+export { FIGURE_SECTION_LABELS, FIGURE_SECTION_ORDER, figureSection };

package/dist/tools/cfd.js

@@ -25,6 +25,7 @@ COMMON MISTAKES: omitting feature_columns (required); choosing a reference_mesh
         backend: z.enum(["auto", "cpu", "gpu", "gpu_graphs"]).optional().describe("Compute backend (default auto / preset)"),
         stratify_scale: z.number().optional().describe("[0,1] per-mesh training-row cap; 1 uses all cells (default 1)"),
         emd_method: z.enum(["exact", "sinkhorn"]).optional().describe("EMD solver: exact LP (default) or sinkhorn (fast approximation for large grids)"),
+        te_inner_samples: z.number().int().optional().describe("Inner statistical sample count for per-batch topographic error estimates during SOM training (default clamp(grid_nodes*6, 500, 10000); display cap remains ≤1000 batch points/phase)"),
         component_planes_physical: z.boolean().optional().describe("Physical-scale component-plane colorbars (default true)"),
         figures: z.boolean().optional().describe("Generate publication figures (default true)"),
         transforms: z.record(z.enum(["log", "log1p", "log10", "sqrt", "square", "abs", "invert", "none"])).optional().describe("Per-feature transform applied before normalization (e.g. log1p to compress k/epsilon/omega). Same preprocessing engine as barsom training."),

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.",