@barivia/barmesh-mcp 0.5.1 → 0.5.3

package/README.md

@@ -55,30 +55,36 @@ API key; otherwise the analysis calls return HTTP 403. Contact Barivia to enable
 | `barmesh_datasets` | Upload / preview / list / get / subset / delete the mesh CSV. |
 | `barmesh_mesh_convergence` | SOM fingerprint distances (async job). |
 | `barmesh_richardson` | Richardson/GCI on scalar QoIs (async job). |
-| `barmesh_jobs` | Poll job status / list jobs (auto-polls CFD prepare + finalize when applicable). Reports phase, epoch/total, elapsed, ETA, and QE live during the SOM training. |
-| `barmesh_results` | Distances, convergence reading, and figures. `action=get` inlines a single `combined.png` overview by default; `action=render` produces publication PDFs on demand. |
-| `barmesh_results_explorer` | Interactive MCP App (or standalone localhost page) to browse the distances, convergence reading, and every figure after a job completes. |
+| `barmesh_jobs` | Poll job status / block until terminal (`action=monitor`) / list jobs. Auto-polls CFD prepare + finalize when applicable. Reports phase, epoch/total, elapsed, ETA, and QE live during the SOM training. |
+| `barmesh_training_monitor` | Alias for `barmesh_jobs(action=monitor)` — server-side poll with throttled snapshots until terminal (preferred after submit). |
+| `barmesh_results` | Distances, convergence reading, and figures. `action=get` inlines headline PNGs; `action=download` saves artifacts to disk; `action=render` produces publication PDFs on demand. |
+| `barmesh_results_explorer` | Interactive MCP App with a **figure dropdown above the plot** (or standalone localhost page) to browse every figure after a job completes. |
 | `barmesh_send_feedback` | Send a short note or bug report to the Barivia team. |
 
-### Figures and progress (0.5.0)
+### Figures and progress (0.5.2)
 
-- **Combined overview:** every completed `mesh_convergence` job produces a single
-  `combined.png` (coarse vs reference volume fingerprint, KL-vs-reference, EMD-vs-reference)
-  as the headline artifact, alongside per-panel PNG previews.
+- **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.
+- **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
-  after completion with `barmesh_results(action=render, format=pdf)`, then download each
-  with `barmesh_results(action=image, filename="KL_ref.pdf")`. This avoids generating
-  ~2× the artifacts (and storage/finalize cost) on every run.
-- **Adaptive layout:** the stepwise volume panels use a single row for small studies and
-  auto-wrap into a near-square grid for many meshes; figures are not cavity-specific.
-- **Live progress:** `barmesh_jobs(action=status)` exposes phase, epoch/total, elapsed,
-  ETA, and quantization error during the SOM training (barsom parity).
-- **Results explorer:** `barmesh_results_explorer(job_id)` opens an interactive figure
-  browser. It embeds as an MCP App in supporting hosts (Claude, VS Code, etc.) and falls
-  back to a standalone `localhost` page otherwise (set `BARIVIA_VIZ_PORT` for a stable port).
+  after completion with `barmesh_results(action=render, format=pdf)`, then download with
+  `barmesh_results(action=download, folder=...)` or `action=image`.
+- **Headless download:** `barmesh_results(action=download, folder=..., include_json=true)`
+  writes PNGs, `summary.json`, and text/CSV artifacts to a per-job subfolder (barsom parity).
+- **Explorer UX:** figure `<select>` above the plot (no scrolling past metrics to switch
+  figures). PNG previews inline; PDF/SVG offered for download when rendered.
+- **Uploads:** large CSVs use presigned PUT with explicit `Content-Length`; `.csv.gz` /
+  `.tsv.gz` accepted. Pin `@barivia/barmesh-mcp@0.5.2` (clear `~/.npm/_npx` if stale).
+- **Live progress:** `barmesh_training_monitor(job_id)` or `barmesh_jobs(action=monitor)` block
+  server-side with compact snapshots (phase, epoch, QE/TE, ETA, ordering_errors tail) until
+  terminal or `block_until_sec` (default 900). Waits for `cfd_finalize` by default. One-shot:
+  `barmesh_jobs(action=status)`.
 
 ### Migration notes
 
+- **`barmesh_training_monitor` (0.5.3):** server-side blocking monitor with throttled snapshots — preferred after job submit instead of manual `barmesh_jobs(status)` loops. Equivalent to `barmesh_jobs(action=monitor)`.
 - **`send_feedback` → `barmesh_send_feedback` (0.3.0):** the feedback tool was renamed so it no longer collides with the `@barivia/barsom-mcp` tool of the same name when both servers are enabled in one client. Update any direct call sites; the behavior is unchanged.
 
 ## Data format (mesh_convergence)

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 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 f}from"./tools/cfd.js";import{registerJobsTool as b}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{registerFeedbackTool as g}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_jobs(action=status) — poll every 10-20s, for minutes if needed.\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>"}]}}),h(i),y(i),u(i),f(i),b(i),v(i),g(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 w=i.server;w.oninitialized=()=>{const e=w.getClientCapabilities(),r=s(e);p(!!r?.mimeTypes?.includes(n))};const j=new r;await i.connect(j),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 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)});

package/dist/job_monitor.js

@@ -0,0 +1,208 @@
+/**
+ * Server-side job monitor for barmesh async workflows.
+ * Polls GET /v1/jobs/:id until terminal (or block_until timeout) and emits
+ * compact throttled snapshots so agents avoid manual status poll loops.
+ */
+import { apiCall } from "./shared.js";
+import { formatJobStatusText } from "./job_status_format.js";
+import { pollCfdFinalizeIfPresent, refreshJobAfterFinalize } from "./cfd_finalize.js";
+export const DEFAULT_BLOCK_UNTIL_SEC = 900;
+export const DEFAULT_POLL_INTERVAL_SEC = 5;
+export const MIN_POLL_INTERVAL_SEC = 5;
+export const HEARTBEAT_POLLS = 1;
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+function num(data, key) {
+    const v = data[key];
+    if (v == null || Number.isNaN(Number(v)))
+        return undefined;
+    return Number(v);
+}
+function str(data, key) {
+    const v = data[key];
+    if (v == null || String(v) === "")
+        return undefined;
+    return String(v);
+}
+function tailOrderingErrors(data, n = 4) {
+    const raw = data.ordering_errors;
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    return raw.slice(-n).map((x) => Number(x)).filter((x) => !Number.isNaN(x));
+}
+export function snapshotFromJob(data, elapsedSec, note) {
+    const status = String(data.status ?? "unknown");
+    const progress_pct = (data.progress ?? 0) * 100;
+    const snap = {
+        elapsed_sec: elapsedSec,
+        status,
+        progress_pct: Math.round(progress_pct * 10) / 10,
+    };
+    const phase = str(data, "progress_phase");
+    if (phase)
+        snap.phase = phase;
+    const epoch = num(data, "epoch");
+    const total = num(data, "total_epochs");
+    if (epoch != null)
+        snap.epoch = epoch;
+    if (total != null)
+        snap.total_epochs = total;
+    const qe = num(data, "quantization_error");
+    const te = num(data, "topographic_error");
+    if (qe != null)
+        snap.qe = Math.round(qe * 10_000) / 10_000;
+    if (te != null)
+        snap.te = Math.round(te * 10_000) / 10_000;
+    const eta = num(data, "training_eta_sec");
+    if (eta != null && eta > 0)
+        snap.eta_sec = Math.round(eta);
+    const tail = tailOrderingErrors(data);
+    if (tail && tail.length > 0)
+        snap.ordering_errors_tail = tail;
+    if (note)
+        snap.note = note;
+    return snap;
+}
+/** True when a new snapshot is worth recording (phase/epoch/progress/status change). */
+export function shouldRecordSnapshot(prev, next) {
+    if (!prev)
+        return true;
+    if (prev.status !== next.status)
+        return true;
+    if (next.note)
+        return true;
+    if (prev.phase !== next.phase)
+        return true;
+    if (prev.epoch !== next.epoch)
+        return true;
+    if (Math.abs(prev.progress_pct - next.progress_pct) >= 1)
+        return true;
+    if (prev.qe !== next.qe || prev.te !== next.te)
+        return true;
+    return false;
+}
+export function formatSnapshotLine(s) {
+    const parts = [`[+${s.elapsed_sec}s] ${s.status} ${s.progress_pct.toFixed(1)}%`];
+    if (s.phase)
+        parts.push(`phase ${s.phase}`);
+    if (s.epoch != null && s.total_epochs != null)
+        parts.push(`epoch ${s.epoch}/${s.total_epochs}`);
+    if (s.qe != null)
+        parts.push(`QE ${s.qe.toFixed(4)}`);
+    if (s.te != null)
+        parts.push(`TE ${s.te.toFixed(4)}`);
+    if (s.eta_sec != null)
+        parts.push(`ETA ~${s.eta_sec}s`);
+    if (s.ordering_errors_tail?.length) {
+        parts.push(`ordering_errors tail [${s.ordering_errors_tail.map((x) => x.toFixed(4)).join(", ")}]`);
+    }
+    if (s.note)
+        parts.push(s.note);
+    return parts.join(" | ");
+}
+export function formatMonitorText(result, opts) {
+    const lines = [
+        `Job ${result.job_id} monitor (block_until=${opts.block_until_sec}s, poll=${opts.poll_interval_sec}s):`,
+    ];
+    for (const s of result.snapshots)
+        lines.push(formatSnapshotLine(s));
+    lines.push("");
+    if (result.timed_out) {
+        lines.push(`Timed out before terminal state. Last status: ${result.status_text}`);
+        lines.push(`Re-run barmesh_training_monitor(job_id="${result.job_id}") or barmesh_jobs(action=monitor, job_id="${result.job_id}").`);
+    }
+    else {
+        lines.push(`Terminal: ${result.status_text}`);
+    }
+    lines.push(result.suggested_next_step);
+    return lines.join("\n");
+}
+function suggestedNextStep(job_id, data) {
+    const status = String(data.status ?? "");
+    if (status === "completed") {
+        const finalizeId = str(data, "finalize_job_id");
+        if (finalizeId) {
+            return `Compute done; cfd_finalize may still be running. Poll barmesh_jobs(status) or re-run monitor with wait_finalize=true, then barmesh_results(action=get, job_id="${job_id}").`;
+        }
+        return `Next: barmesh_results(action=get, job_id="${job_id}") or barmesh_results_explorer(job_id="${job_id}").`;
+    }
+    if (status === "failed") {
+        const stage = str(data, "failure_stage");
+        return `Job failed${stage ? ` at ${stage}` : ""}. Read the error above before retrying.`;
+    }
+    if (status === "cancelled")
+        return `Job cancelled. Confirm with barmesh_jobs(action=status, job_id="${job_id}").`;
+    return `Still running — re-run barmesh_training_monitor(job_id="${job_id}") to continue waiting.`;
+}
+async function fetchTrainingLogHint(job_id, data) {
+    const status = String(data.status ?? "");
+    if (status !== "completed" && status !== "failed")
+        return undefined;
+    try {
+        await apiCall("GET", `/v1/results/${job_id}/training-log`);
+        return `Training log available at GET /v1/results/${job_id}/training-log (learning_curve.png in results after finalize).`;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function monitorJob(job_id, options = {}) {
+    const block_until_sec = Math.max(30, options.block_until_sec ?? DEFAULT_BLOCK_UNTIL_SEC);
+    const poll_interval_sec = Math.max(MIN_POLL_INTERVAL_SEC, options.poll_interval_sec ?? DEFAULT_POLL_INTERVAL_SEC);
+    const wait_finalize = options.wait_finalize !== false;
+    const blockMs = block_until_sec * 1000;
+    const pollMs = poll_interval_sec * 1000;
+    const start = Date.now();
+    const snapshots = [];
+    let lastSnap = null;
+    let data = {};
+    let heartbeat = 0;
+    while (Date.now() - start < blockMs) {
+        data = (await apiCall("GET", `/v1/jobs/${job_id}`));
+        const elapsedSec = Math.round((Date.now() - start) / 1000);
+        const snap = snapshotFromJob(data, elapsedSec);
+        heartbeat += 1;
+        const heartbeatDue = heartbeat >= HEARTBEAT_POLLS;
+        if (shouldRecordSnapshot(lastSnap, snap) || heartbeatDue) {
+            snapshots.push(snap);
+            lastSnap = snap;
+            heartbeat = 0;
+        }
+        const status = String(data.status ?? "");
+        if (status === "completed" || status === "failed" || status === "cancelled") {
+            break;
+        }
+        await sleep(pollMs);
+    }
+    const status = String(data.status ?? "");
+    const terminal = status === "completed" || status === "failed" || status === "cancelled";
+    const timed_out = !terminal;
+    if (terminal && status === "completed" && wait_finalize && data.finalize_job_id) {
+        const finalizeId = String(data.finalize_job_id);
+        const elapsedSec = Math.round((Date.now() - start) / 1000);
+        snapshots.push(snapshotFromJob(data, elapsedSec, `cfd_finalize ${finalizeId} started — waiting for figure render`));
+        try {
+            const { note } = await pollCfdFinalizeIfPresent(job_id, data, Math.max(0, blockMs - (Date.now() - start)));
+            data = await refreshJobAfterFinalize(job_id);
+            snapshots.push(snapshotFromJob(data, Math.round((Date.now() - start) / 1000), note ?? `cfd_finalize ${finalizeId} completed`));
+        }
+        catch (err) {
+            snapshots.push(snapshotFromJob(data, Math.round((Date.now() - start) / 1000), `cfd_finalize failed: ${err.message}`));
+        }
+    }
+    const statusText = await formatJobStatusText(job_id, data);
+    const logHint = terminal ? await fetchTrainingLogHint(job_id, data) : undefined;
+    let suggested = suggestedNextStep(job_id, data);
+    if (logHint)
+        suggested += ` ${logHint}`;
+    return {
+        job_id,
+        terminal,
+        timed_out,
+        snapshots,
+        status_text: statusText,
+        data,
+        suggested_next_step: suggested,
+    };
+}

package/dist/job_status_format.js

@@ -3,6 +3,7 @@
  * Surfaces phase, elapsed, ETA, and epoch N/M during the SOM training of a
  * cfd_mesh_convergence job, plus CFD finalize (figure render) sub-status.
  */
+import { apiCall } from "./shared.js";
 function formatElapsedPart(data, status) {
     const wall = data.wall_elapsed_sec != null && !Number.isNaN(Number(data.wall_elapsed_sec))
         ? Number(data.wall_elapsed_sec)
@@ -32,7 +33,27 @@ function formatElapsedPart(data, status) {
     }
     return null;
 }
-export function formatJobStatusText(job_id, data) {
+async function finalizeStatusLine(finalizeId) {
+    try {
+        const fin = (await apiCall("GET", `/v1/jobs/${finalizeId}`));
+        const st = String(fin.status ?? "unknown");
+        const prog = fin.progress != null ? `${(Number(fin.progress) * 100).toFixed(0)}%` : null;
+        const phase = fin.progress_phase != null ? String(fin.progress_phase) : null;
+        const elapsed = formatElapsedPart(fin, st);
+        const bits = [`cfd_finalize ${finalizeId}: ${st}`];
+        if (prog)
+            bits.push(prog);
+        if (phase)
+            bits.push(`phase ${phase}`);
+        if (elapsed)
+            bits.push(elapsed);
+        return bits.join(", ");
+    }
+    catch {
+        return `cfd_finalize ${finalizeId} still running (poll barmesh_jobs(action=status, job_id="${finalizeId}"))`;
+    }
+}
+export async function formatJobStatusText(job_id, data) {
     const status = String(data.status ?? "unknown");
     const progress = (data.progress ?? 0) * 100;
     const label = data.label != null && data.label !== "" ? String(data.label) : null;
@@ -72,7 +93,8 @@ export function formatJobStatusText(job_id, data) {
     if (status === "completed") {
         const finalizeId = data.finalize_job_id != null && String(data.finalize_job_id) !== "" ? String(data.finalize_job_id) : null;
         if (finalizeId) {
-            parts.push(`Compute done; cfd_finalize still rendering figures (finalize_job_id=${finalizeId}). Poll barmesh_jobs(action=status) again to auto-wait before barmesh_results(action=get).`);
+            parts.push(await finalizeStatusLine(finalizeId));
+            parts.push(`Compute done; figures may still be uploading. Poll barmesh_jobs(status) until finalize completes before barmesh_results(get).`);
         }
         else {
             parts.push(`Results ready. Use barmesh_results(action=get, job_id="${job_id}") for distances and figures, or barmesh_results_explorer(job_id="${job_id}") to browse interactively.`);

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.1";
+export const CLIENT_VERSION = "0.5.3";
 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;
@@ -157,6 +157,14 @@ export function getSandboxRoot() {
         return pwd;
     return process.cwd();
 }
+export function sandboxPath(userPath, root) {
+    const resolved = path.resolve(root, userPath);
+    if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+        throw new Error("Path must be within the workspace directory. " +
+            "Set BARIVIA_WORKSPACE_ROOT to your project path if needed.");
+    }
+    return resolved;
+}
 export async function getWorkspaceRootAsync(mcpServer) {
     try {
         const result = await mcpServer.server.listRoots();
@@ -378,6 +386,12 @@ export function mimeForFilename(fname) {
 /** Per-image caption for multimodal LLM context (what to look for). */
 export function getCaptionForImage(filename) {
     const base = filename.replace(/\.(png|pdf|svg)$/i, "");
+    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.";
+    if (base === "learning_curve")
+        return "Quantization error by epoch: ordering phase (steel blue) then convergence (coral).";
     if (base === "KL_ref")
         return "KL divergence to the reference mesh: steel blue is from the reference, coral is to the reference. Lower and converging toward the finest mesh indicates sufficiency.";
     if (base === "KL_stepwise")

package/dist/tools/barmesh_results_explorer.js

@@ -3,10 +3,47 @@ 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";
 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));
+}
+export function resolveDefaultFigureKey(figures) {
+    const byKey = (k) => figures.find((f) => f.key === k);
+    if (byKey("combined"))
+        return "combined";
+    const raster = figures.find((f) => /\.(png|svg)$/i.test(f.filename));
+    if (raster)
+        return raster.key;
+    if (byKey("KL_ref"))
+        return "KL_ref";
+    return figures[0]?.key;
+}
 function labelForFigure(filename) {
     const base = filename.replace(/\.(png|pdf|svg)$/i, "");
     if (base === "combined")
-        return "Combined overview";
+        return "Component planes (overview)";
+    if (base === "overview_distances")
+        return "Distances & volume overview";
+    if (base === "learning_curve")
+        return "Learning curve (QE by epoch)";
     if (base === "KL_ref")
         return "KL divergence vs reference";
     if (base === "KL_stepwise")
@@ -65,10 +102,9 @@ function buildHighlights(summary) {
 /**
  * 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
- * download target is the best quality (SVG > PDF > PNG). Order follows first appearance
- * in `files` (combined first, then diagnostics, then component planes).
+ * download target is the best quality (SVG > PDF > PNG).
  */
-function groupFigures(files) {
+export function groupFigures(files) {
     const byBase = new Map();
     for (const f of files) {
         const m = f.match(/^(.*)\.(png|pdf|svg)$/i);
@@ -85,10 +121,14 @@ function groupFigures(files) {
         const preview = extSet.has("png") ? `${base}.png` : extSet.has("svg") ? `${base}.svg` : `${base}.${formats[0]}`;
         const downloadFilename = extSet.has("svg") ? `${base}.svg` : extSet.has("pdf") ? `${base}.pdf` : `${base}.png`;
         const vector = formats.filter((e) => e === "pdf" || e === "svg");
+        const vectorOnly = !/\.(png|svg)$/i.test(preview);
         const baseCaption = getCaptionForImage(preview) || "";
         const vectorNote = vector.length > 0
             ? `High-quality ${vector.join("/").toUpperCase()} available — download it (standalone page) or fetch with barmesh_results(action=image, filename="${downloadFilename}").`
             : "";
+        const emptyNote = vectorOnly
+            ? "Vector figure — no inline preview. Use Download or barmesh_results(action=render, format=png) for a raster."
+            : "";
         return {
             key: base,
             label: labelForFigure(preview),
@@ -96,17 +136,14 @@ function groupFigures(files) {
             downloadFilename,
             formats,
             kind: figureKind(base),
-            caption: [baseCaption, vectorNote].filter(Boolean).join(" ") || undefined,
+            caption: [baseCaption, vectorNote, emptyNote].filter(Boolean).join(" ") || undefined,
         };
     });
 }
 export function buildPayload(jobId, data) {
     const summary = (data.summary ?? {});
     const files = (summary.files ?? []).filter((f) => /\.(png|pdf|svg)$/i.test(f));
-    // Embedded view: never set `url` (sandboxed iframe cannot load localhost) — figures
-    // lazy-load as base64 through the _barmesh_fetch_figure bridge tool. One entry per
-    // logical figure; PNG previews inline, vector (PDF/SVG) is offered for download.
-    const figures = groupFigures(files);
+    const figures = sortFigures(groupFigures(files));
     const port = getVizPort();
     return {
         type: "barmesh-results-explorer",
@@ -116,9 +153,7 @@ export function buildPayload(jobId, data) {
         metrics: buildMetrics(summary),
         highlights: buildHighlights(summary),
         availableFigures: figures,
-        defaultFigureKey: figures.find((f) => f.key === "combined")?.key ??
-            figures.find((f) => f.key === "KL_ref")?.key ??
-            figures[0]?.key,
+        defaultFigureKey: resolveDefaultFigureKey(figures),
         standaloneUrl: port
             ? `http://localhost:${port}/viz/barmesh-results-explorer?mode=standalone&job_id=${jobId}`
             : undefined,
@@ -140,7 +175,7 @@ async function handleResultsExplorer(job_id) {
         },
     ];
     const defaultFigure = payload.availableFigures.find((f) => f.key === payload.defaultFigureKey);
-    if (defaultFigure) {
+    if (defaultFigure && /\.(png|svg|jpe?g|webp)$/i.test(defaultFigure.filename)) {
         await tryAttachImage(content, job_id, defaultFigure.filename);
     }
     if (!getClientSupportsMcpApps() && payload.standaloneUrl) {
@@ -156,16 +191,13 @@ 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 of the distances, convergence reading, and every figure (combined overview, KL/EMD vs reference and stepwise, volume fingerprints, component 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 it has been 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 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.",
         inputSchema: {
             job_id: z.string().describe("Job ID of a completed cfd_mesh_convergence job"),
         },
         _meta: { ui: { resourceUri: RESULTS_EXPLORER_URI } },
     };
     registerAppTool(server, "barmesh_results_explorer", toolConfig, async (args) => runMcpToolAudit("barmesh_results_explorer", "default", args, () => handleResultsExplorer(String(args.job_id))));
-    // MUST stay a registered tool: the explorer App view lazy-loads non-default raster
-    // figures through the App bridge (mcpApp.callServerTool), which can only reach
-    // registered server tools. Agents must not call it directly from chat.
     registerAuditedTool(server, "_barmesh_fetch_figure", "[INTERNAL — host / MCP App only; agents MUST NOT call this.] The Mesh Convergence Results Explorer view uses it to lazy-load one raster figure as base64. From chat, use barmesh_results(action=get) or barmesh_results_explorer instead.", {
         job_id: z.string(),
         filename: z.string(),

package/dist/tools/cfd.js

@@ -47,7 +47,7 @@ COMMON MISTAKES: omitting feature_columns (required); choosing a reference_mesh
         const id = data.id;
         if (id != null) {
             const prep = data.prepare_job_id != null ? " (dataset prepare complete)" : "";
-            data.suggested_next_step = `Poll barmesh_jobs(action=status, job_id=${id})${prep}; on completion call barmesh_results(action=get, job_id=${id}).`;
+            data.suggested_next_step = `Run barmesh_training_monitor(job_id="${id}") or barmesh_jobs(action=monitor, job_id="${id}")${prep}; on completion call barmesh_results(action=get, job_id="${id}").`;
         }
         return textResult(data);
     });
@@ -80,7 +80,7 @@ COMMON MISTAKES: not providing h_column or n_cells_column; mixing QoIs with diff
         const data = (await apiCall("POST", "/v1/cfd/richardson", body));
         const id = data.id;
         if (id != null)
-            data.suggested_next_step = `Poll barmesh_jobs(action=status, job_id=${id}); on completion call barmesh_results(action=get, job_id=${id}).`;
+            data.suggested_next_step = `Run barmesh_training_monitor(job_id="${id}") or barmesh_jobs(action=monitor, job_id="${id}"); on completion call barmesh_results(action=get, job_id="${id}").`;
         return textResult(data);
     });
 }

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_jobs(status) -> barmesh_results(get).
+Workflow: barmesh_prepare_mesh_data -> barmesh_datasets(upload) -> barmesh_mesh_convergence / barmesh_richardson -> barmesh_training_monitor (or barmesh_jobs monitor/status) -> barmesh_results(get).
 (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

@@ -3,28 +3,53 @@ import { registerAuditedTool } from "../audit.js";
 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";
 export function registerJobsTool(server) {
-    registerAuditedTool(server, "barmesh_jobs", `Check job status or list jobs.
+    registerAuditedTool(server, "barmesh_jobs", `Check job status, block until terminal, or list jobs.
 
-BEST FOR: Polling a submitted barmesh_mesh_convergence or barmesh_richardson job until status is completed/failed.
-ASYNC PROTOCOL: Poll action=status every 10-20s. Keep polling for several minutes — datacenter-scale grids plus EMD are slow; do not give up after one poll. When status=completed, call barmesh_results(action=get, job_id=...).
+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=...).
 ESCALATION: status=failed returns an error message and (when available) a failure_stage; read it before retrying.`, {
-        action: z.enum(["status", "list"]).describe("status: check one job; list: recent jobs"),
-        job_id: z.string().optional().describe("Job ID (required for status)"),
+        action: z
+            .enum(["status", "monitor", "list"])
+            .describe("status: one-shot check; monitor: block until terminal with snapshots; list: recent jobs"),
+        job_id: z.string().optional().describe("Job ID (required for status and monitor)"),
+        block_until_sec: z
+            .number()
+            .int()
+            .min(30)
+            .optional()
+            .describe(`action=monitor only: max wait seconds (default ${DEFAULT_BLOCK_UNTIL_SEC})`),
+        poll_interval_sec: z
+            .number()
+            .int()
+            .min(5)
+            .optional()
+            .describe(`action=monitor only: poll interval (default ${DEFAULT_POLL_INTERVAL_SEC})`),
+        wait_finalize: z
+            .boolean()
+            .optional()
+            .describe("action=monitor only: wait for cfd_finalize (default true)"),
     }, async (args) => {
-        const { action, job_id } = args;
+        const { action, job_id, block_until_sec, poll_interval_sec, wait_finalize } = args;
+        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 });
+        }
         if (action === "status") {
             if (!job_id)
                 throw new Error("barmesh_jobs(status) requires job_id.");
             let data = (await apiCall("GET", `/v1/jobs/${job_id}`));
             const status = String(data.status ?? "");
+            let note = null;
             if (status === "completed" && data.finalize_job_id) {
-                const { note } = await pollCfdFinalizeIfPresent(job_id, data);
+                ({ note } = await pollCfdFinalizeIfPresent(job_id, data));
                 data = await refreshJobAfterFinalize(job_id);
-                const statusText = note ? `${formatJobStatusText(job_id, data)}\n${note}` : formatJobStatusText(job_id, data);
-                return textResult({ ...data, status_text: statusText });
             }
-            return textResult({ ...data, status_text: formatJobStatusText(job_id, data) });
+            const statusText = await formatJobStatusText(job_id, data);
+            return textResult({ ...data, status_text: note ? `${statusText}\n${note}` : statusText });
         }
         const data = await apiCall("GET", "/v1/jobs");
         return textResult(data);