@barivia/barmesh-mcp 0.4.1 → 0.5.1

package/README.md

@@ -55,10 +55,28 @@ 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). |
-| `barmesh_results` | Distances, convergence reading, and figures. |
+| `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_send_feedback` | Send a short note or bug report to the Barivia team. |
 
+### Figures and progress (0.5.0)
+
+- **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.
+- **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).
+
 ### Migration notes
 
 - **`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.
@@ -84,3 +102,4 @@ Parquet staging is supported by the API but not yet exposed as an MCP upload for
 | `BARIVIA_FETCH_TIMEOUT_MS` | `60000` | Per-request timeout (raise for large uploads). |
 | `BARIVIA_WORKSPACE_ROOT` | workspace/cwd | Root for resolving relative `file_path` uploads. |
 | `BARIVIA_ENFORCE_WORKSPACE_SANDBOX` | `1` | Restrict uploads to the workspace; set `0` to allow absolute paths. |
+| `BARIVIA_VIZ_PORT` | ephemeral | Fixed localhost port for the `barmesh_results_explorer` standalone page (otherwise OS-assigned per session). |

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 s}from"@modelcontextprotocol/sdk/server/stdio.js";import{API_KEY as r,CLIENT_VERSION as n}from"./shared.js";import{registerGuideTool as o}from"./tools/guide.js";import{registerDatasetsTool as t}from"./tools/datasets.js";import{registerCfdTools as a}from"./tools/cfd.js";import{registerJobsTool as i}from"./tools/jobs.js";import{registerResultsTool as c}from"./tools/results.js";import{registerFeedbackTool as m}from"./tools/feedback.js";r||(console.error("Error: BARIVIA_API_KEY not set. Set it in your MCP client config."),process.exit(1));(async function(){const r=new e({name:"barmesh",version:n},{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.\n\nThese tools are gated by the 'cfd' entitlement; analysis calls return 403 if your plan\ndoes not include it."});o(r),t(r),a(r),i(r),c(r),m(r);const l=new s;await r.connect(l),console.error(`barmesh-mcp ${n} 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 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)});

package/dist/job_status_format.js

@@ -0,0 +1,89 @@
+/**
+ * Format barmesh_jobs(status) text from GET /v1/jobs/:id (barsom parity).
+ * 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.
+ */
+function formatElapsedPart(data, status) {
+    const wall = data.wall_elapsed_sec != null && !Number.isNaN(Number(data.wall_elapsed_sec))
+        ? Number(data.wall_elapsed_sec)
+        : null;
+    const kernel = data.kernel_elapsed_sec != null && !Number.isNaN(Number(data.kernel_elapsed_sec))
+        ? Number(data.kernel_elapsed_sec)
+        : data.training_elapsed_sec != null && !Number.isNaN(Number(data.training_elapsed_sec))
+            ? Number(data.training_elapsed_sec)
+            : null;
+    if (wall != null && wall >= 0) {
+        const wallR = Math.round(wall);
+        if (status === "completed" && kernel != null && kernel >= 0 && Math.abs(wallR - Math.round(kernel)) >= 2) {
+            return `elapsed: ${wallR}s (kernel training: ${Math.round(kernel)}s)`;
+        }
+        return `elapsed: ${wallR}s`;
+    }
+    if (kernel != null && kernel >= 0) {
+        return `elapsed: ${Math.round(kernel)}s`;
+    }
+    const startedAt = data.started_at != null ? String(data.started_at) : null;
+    if (startedAt) {
+        const startedMs = Date.parse(startedAt);
+        if (!Number.isNaN(startedMs)) {
+            const elapsedSec = Math.max(0, Math.round((Date.now() - startedMs) / 1000));
+            return `elapsed: ${elapsedSec}s`;
+        }
+    }
+    return null;
+}
+export 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;
+    const jobDesc = label ? `Job ${label} (id: ${job_id})` : `Job ${job_id}`;
+    const parts = [`${jobDesc}: ${status} (${progress.toFixed(1)}%)`];
+    const attempt = data.attempt != null ? Number(data.attempt) : null;
+    if (attempt != null && attempt > 1) {
+        parts.push(`attempt ${attempt} (job was requeued after worker timeout — not stuck from scratch)`);
+    }
+    const phase = data.progress_phase != null && String(data.progress_phase) !== ""
+        ? String(data.progress_phase)
+        : null;
+    if (status === "running") {
+        parts.push(phase ? `phase: ${phase}` : `phase: preprocessing (download/parse before first tick)`);
+    }
+    const startedAt = data.started_at != null ? String(data.started_at) : null;
+    if (startedAt)
+        parts.push(`started_at: ${startedAt}`);
+    const elapsedPart = formatElapsedPart(data, status);
+    if (elapsedPart)
+        parts.push(elapsedPart);
+    if (status === "running") {
+        const etaSec = data.training_eta_sec != null ? Number(data.training_eta_sec) : null;
+        if (etaSec != null && etaSec > 0)
+            parts.push(`ETA ~${Math.round(etaSec)}s`);
+        const epoch = data.epoch != null ? Number(data.epoch) : null;
+        const totalEpochs = data.total_epochs != null ? Number(data.total_epochs) : null;
+        if (epoch != null && totalEpochs != null && totalEpochs > 0)
+            parts.push(`epoch ${epoch}/${totalEpochs}`);
+        const qe = data.quantization_error != null ? Number(data.quantization_error) : null;
+        if (qe != null && !Number.isNaN(qe))
+            parts.push(`QE ${qe.toFixed(4)}`);
+    }
+    if (status === "running" && progress < 5 && !phase) {
+        parts.push("Advisory: still in early preprocessing — epoch counter starts after ingest completes.");
+    }
+    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).`);
+        }
+        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.`);
+        }
+    }
+    else if (status === "failed") {
+        const failureStage = data.failure_stage != null && String(data.failure_stage) !== "" ? ` [${data.failure_stage}]` : "";
+        parts.push(`Error${failureStage}: ${data.error ?? "unknown"}`);
+    }
+    else if (status === "cancelled") {
+        parts.push(`Cancelled. Poll again to confirm; dataset and partial worker state are unchanged.`);
+    }
+    return parts.join(" | ");
+}

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.4.1";
+export const CLIENT_VERSION = "0.5.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;
@@ -95,6 +95,30 @@ export async function putPresignedStream(url, srcPath, contentType, timeoutMs =
     }
 }
 // ---------------------------------------------------------------------------
+// MCP App view state (results explorer)
+// ---------------------------------------------------------------------------
+let _vizPort = 0;
+let _clientSupportsMcpApps = false;
+export function getVizPort() {
+    return _vizPort;
+}
+export function setVizPort(port) {
+    _vizPort = port;
+}
+export function getClientSupportsMcpApps() {
+    return _clientSupportsMcpApps;
+}
+export function setClientSupportsMcpApps(value) {
+    _clientSupportsMcpApps = value;
+}
+/** Tool result carrying both a structured payload (for the MCP App view) and text/image content. */
+export function structuredTextResult(structuredContent, text, content) {
+    return {
+        structuredContent,
+        content: content ?? [{ type: "text", text: text ?? JSON.stringify(structuredContent, null, 2) }],
+    };
+}
+// ---------------------------------------------------------------------------
 // Fetch helpers
 // ---------------------------------------------------------------------------
 export function isTransientError(err, status) {
@@ -370,6 +394,26 @@ export function getCaptionForImage(filename) {
         return `Component plane for ${base.replace(/^plot_/, "")} on the trained SOM.`;
     return "";
 }
+// ---------------------------------------------------------------------------
+// View loading (bundled single-file HTML for the results explorer MCP App)
+// ---------------------------------------------------------------------------
+const BASE_DIR = import.meta.dirname ?? path.dirname(fileURLToPath(import.meta.url));
+export async function loadViewHtml(viewName) {
+    const candidates = [
+        path.join(BASE_DIR, "views", "src", "views", viewName, "index.html"),
+        path.join(BASE_DIR, "views", viewName, "index.html"),
+        path.join(BASE_DIR, "..", "dist", "views", "src", "views", viewName, "index.html"),
+    ];
+    for (const p of candidates) {
+        try {
+            return await fs.readFile(p, "utf-8");
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
 export async function tryAttachImage(content, jobId, filename) {
     if (filename.endsWith(".pdf") || filename.endsWith(".svg")) {
         content.push({

package/dist/tools/barmesh_results_explorer.js

@@ -0,0 +1,186 @@
+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";
+export const RESULTS_EXPLORER_URI = "ui://barmesh/results-explorer";
+function labelForFigure(filename) {
+    const base = filename.replace(/\.(png|pdf|svg)$/i, "");
+    if (base === "combined")
+        return "Combined overview";
+    if (base === "KL_ref")
+        return "KL divergence vs reference";
+    if (base === "KL_stepwise")
+        return "KL divergence stepwise";
+    if (base === "EMD_ref")
+        return "Wasserstein (EMD) vs reference";
+    if (base === "EMD_stepwise")
+        return "Wasserstein (EMD) stepwise";
+    if (base === "plot_vol_coarse_fine")
+        return "Volume fingerprint: coarse vs reference";
+    if (base.startsWith("plot_vol_"))
+        return "Volume fingerprint: stepwise";
+    if (base.startsWith("plot_"))
+        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 ?? [];
+    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: "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
+ * download target is the best quality (SVG > PDF > PNG). Order follows first appearance
+ * in `files` (combined first, then diagnostics, then component planes).
+ */
+function groupFigures(files) {
+    const byBase = new Map();
+    for (const f of files) {
+        const m = f.match(/^(.*)\.(png|pdf|svg)$/i);
+        if (!m)
+            continue;
+        const base = m[1];
+        const ext = m[2].toLowerCase();
+        const set = byBase.get(base) ?? new Set();
+        set.add(ext);
+        byBase.set(base, set);
+    }
+    return [...byBase.entries()].map(([base, extSet]) => {
+        const formats = [...extSet];
+        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 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}").`
+            : "";
+        return {
+            key: base,
+            label: labelForFigure(preview),
+            filename: preview,
+            downloadFilename,
+            formats,
+            kind: figureKind(base),
+            caption: [baseCaption, vectorNote].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 port = getVizPort();
+    return {
+        type: "barmesh-results-explorer",
+        jobId,
+        title: "Mesh Convergence Results",
+        subtitle: String(data.label ?? ""),
+        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,
+        standaloneUrl: port
+            ? `http://localhost:${port}/viz/barmesh-results-explorer?mode=standalone&job_id=${jobId}`
+            : undefined,
+    };
+}
+async function handleResultsExplorer(job_id) {
+    const data = (await apiCall("GET", `/v1/results/${job_id}`));
+    const payload = buildPayload(job_id, data);
+    const content = [
+        {
+            type: "text",
+            text: [
+                `Mesh convergence results explorer ready for job ${job_id}.`,
+                payload.subtitle ? `Label: ${payload.subtitle}` : "",
+                payload.highlights[0] ?? "",
+            ]
+                .filter(Boolean)
+                .join("\n"),
+        },
+    ];
+    const defaultFigure = payload.availableFigures.find((f) => f.key === payload.defaultFigureKey);
+    if (defaultFigure) {
+        await tryAttachImage(content, job_id, defaultFigure.filename);
+    }
+    if (!getClientSupportsMcpApps() && payload.standaloneUrl) {
+        content.push({
+            type: "text",
+            text: `Interactive results explorer: [Open results explorer](${payload.standaloneUrl})\n` +
+                `AGENT: surface this to the user as a clickable markdown link in your reply. ` +
+                `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);
+}
+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.",
+        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(),
+    }, async ({ job_id, filename }) => {
+        const safeFilename = filename.replace(/[^a-zA-Z0-9._-]/g, "");
+        const mime = mimeForFilename(safeFilename);
+        if (safeFilename.endsWith(".pdf") || safeFilename.endsWith(".svg")) {
+            return { content: [{ type: "text", text: `${safeFilename} is a vector format and cannot be displayed inline.` }] };
+        }
+        try {
+            const { data: imgBuf } = await apiRawCall(`/v1/results/${job_id}/image/${safeFilename}`);
+            return { content: [{ type: "image", data: imgBuf.toString("base64"), mimeType: mime }] };
+        }
+        catch {
+            return { content: [{ type: "text", text: `Failed to fetch ${safeFilename}.` }] };
+        }
+    });
+}

package/dist/tools/jobs.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 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";
 export function registerJobsTool(server) {
     registerAuditedTool(server, "barmesh_jobs", `Check job status or list jobs.
 
@@ -20,16 +21,10 @@ ESCALATION: status=failed returns an error message and (when available) a failur
             if (status === "completed" && data.finalize_job_id) {
                 const { note } = await pollCfdFinalizeIfPresent(job_id, data);
                 data = await refreshJobAfterFinalize(job_id);
-                const lines = [
-                    `Job ${job_id}: ${String(data.status ?? "unknown")}`,
-                    data.label != null ? `Label: ${String(data.label)}` : null,
-                    data.progress != null ? `Progress: ${String(data.progress)}` : null,
-                    data.result_ref != null ? `Results: ${String(data.result_ref)}` : null,
-                    note,
-                ].filter(Boolean);
-                return textResult({ ...data, status_text: lines.join("\n") });
+                const statusText = note ? `${formatJobStatusText(job_id, data)}\n${note}` : formatJobStatusText(job_id, data);
+                return textResult({ ...data, status_text: statusText });
             }
-            return textResult(data);
+            return textResult({ ...data, status_text: formatJobStatusText(job_id, data) });
         }
         const data = await apiCall("GET", "/v1/jobs");
         return textResult(data);

package/dist/tools/results.js

@@ -1,27 +1,52 @@
 import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
-import { apiCall, apiRawCall, textResult, tryAttachImage } from "../shared.js";
-const MESH_DEFAULT_FIGURES = ["KL_ref", "EMD_ref", "plot_vol_coarse_fine"];
+import { apiCall, apiRawCall, textResult, tryAttachImage, pollUntilComplete, POLL_STAGE_MAX_MS } from "../shared.js";
+// Headline figures when present, best first: the combined overview (barsom parity),
+// then KL/EMD-vs-reference and the coarse/fine volume pair.
+const MESH_DEFAULT_FIGURES = ["combined", "KL_ref", "EMD_ref", "plot_vol_coarse_fine"];
 export function registerResultsTool(server) {
     registerAuditedTool(server, "barmesh_results", `Fetch results of a completed CFD job: distances, convergence reading, and figures.
 
 | Action | Use when |
 |--------|----------|
 | get | Read the summary (distances per mesh, stepwise, convergence reading) and inline key figures. |
-| image | Download one figure by filename (e.g. KL_ref.pdf, EMD_stepwise.png). |
+| image | Download one figure by filename (e.g. KL_ref.png, EMD_stepwise.pdf). |
+| render | Re-render the figures as publication PDFs (or SVG) on demand — PDFs are NOT generated by default. |
 
 BEST FOR: After barmesh_jobs(action=status) shows completed.
-FIGURES: For mesh_convergence, action=get inlines the headline panels (KL_ref, EMD_ref, volume coarse/fine) as PNGs with captions; pass figures="all" for every figure, "none" for metrics only, or a list of names. PDFs are publication vector copies — fetch with action=image.
+FIGURES: Default job output is metrics + PNG previews, including a single combined.png overview. action=get inlines the combined headline plus KL_ref/EMD_ref/volume PNGs with captions; pass figures="all" for every PNG, "none" for metrics only, or a list of names.
+PDFs ON DEMAND: vector PDFs are not produced by default. Use action=render (format=pdf) once, then action=image to download each <name>.pdf. For an interactive browser use barmesh_results_explorer.
 NOT FOR: Submitting jobs.`, {
-        action: z.enum(["get", "image"]).describe("get: summary + figures; image: download one figure file"),
+        action: z.enum(["get", "image", "render"]).describe("get: summary + figures; image: download one figure file; render: re-render figures as PDF/SVG on demand"),
         job_id: z.string().describe("Job ID"),
-        filename: z.string().optional().describe("For action=image: the figure filename (e.g. KL_ref.pdf)"),
+        filename: z.string().optional().describe("For action=image: the figure filename (e.g. KL_ref.png or, after render, KL_ref.pdf)"),
+        format: z.enum(["pdf", "png", "svg"]).optional().describe("For action=render: output format to generate (default pdf). PNG previews already exist by default."),
         figures: z
             .union([z.enum(["default", "all", "none"]), z.array(z.string())])
             .optional()
             .describe("For action=get: which figures to inline (default headline panels; 'all'; 'none'; or a list of names)"),
     }, async (args) => {
-        const { action, job_id, filename, figures } = args;
+        const { action, job_id, filename, format, figures } = args;
+        if (action === "render") {
+            const fmt = format ?? "pdf";
+            const submit = (await apiCall("POST", "/v1/cfd/render", { job_id, format: fmt }));
+            const renderId = (submit.id ?? submit.job_id);
+            if (!renderId)
+                throw new Error("cfd render did not return a job id");
+            const poll = await pollUntilComplete(renderId, POLL_STAGE_MAX_MS);
+            if (poll.status === "failed") {
+                return textResult({ status: "failed", render_job_id: renderId, error: poll.error ?? "render failed" });
+            }
+            if (poll.status !== "completed") {
+                return textResult({ status: poll.status, render_job_id: renderId, note: `Still rendering; poll barmesh_jobs(action=status, job_id="${renderId}").` });
+            }
+            return textResult({
+                status: "completed",
+                render_job_id: renderId,
+                format: fmt,
+                suggested_next_step: `Figures rendered as ${fmt}. Download one with barmesh_results(action=image, job_id="${job_id}", filename="KL_ref.${fmt}"), or list filenames via barmesh_results(action=get, job_id="${job_id}").`,
+            });
+        }
         if (action === "image") {
             if (!filename)
                 throw new Error("barmesh_results(image) requires filename.");