@barivia/barmesh-mcp 0.5.1 → 0.5.2

package/README.md

@@ -56,26 +56,28 @@ API key; otherwise the analysis calls return HTTP 403. Contact Barivia to enable
 | `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_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.
+  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_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).
+  ETA, QE during SOM training, plus cfd_finalize sub-status when figures are deferred.
 
 ### Migration notes
 

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.2";
 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/jobs.js

@@ -18,13 +18,13 @@ ESCALATION: status=failed returns an error message and (when available) a failur
                 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);

package/dist/tools/results.js

@@ -1,32 +1,44 @@
+import fs from "node:fs/promises";
+import path from "node:path";
 import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
-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"];
+import { apiCall, apiRawCall, getWorkspaceRootAsync, sandboxPath, textResult, tryAttachImage, pollUntilComplete, POLL_STAGE_MAX_MS, } from "../shared.js";
+const MESH_DEFAULT_FIGURES = ["combined", "overview_distances", "KL_ref", "EMD_ref", "plot_vol_coarse_fine", "learning_curve"];
+const TEXT_ARTIFACTS = [
+    "summary.json",
+    "distances.csv",
+    "training_metrics.txt",
+    "distances_to_ref.txt",
+    "emd_stepwise.txt",
+    "cfd_metrics.json",
+];
 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.png, EMD_stepwise.pdf). |
+| image | Download one figure by filename (e.g. KL_ref.png, combined.pdf). |
 | render | Re-render the figures as publication PDFs (or SVG) on demand — PDFs are NOT generated by default. |
+| download | Save figures and metrics to a local folder (headless / agent path). |
 
-BEST FOR: After barmesh_jobs(action=status) shows completed.
-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.
+BEST FOR: After barmesh_jobs(action=status) shows completed (and finalize finished if defer_figures was used).
+FIGURES: Default output includes combined.png (component-plane mosaic), overview_distances.png, learning_curve.png, and per-panel PNGs. action=get inlines headline panels; pass figures="all" for every PNG, "none" for metrics only.
+PDFs ON DEMAND: vector PDFs are not produced by default. Use action=render (format=pdf) once, then action=image or action=download.
+If GET /v1/results returns 404 shortly after status=completed, cfd_finalize may still be rendering — poll barmesh_jobs(status) until finalize_job_id completes.
 NOT FOR: Submitting jobs.`, {
-        action: z.enum(["get", "image", "render"]).describe("get: summary + figures; image: download one figure file; render: re-render figures as PDF/SVG on demand"),
+        action: z.enum(["get", "image", "render", "download"]).describe("get: summary + figures; image: one file; render: lazy PDF/SVG; download: save to disk"),
         job_id: z.string().describe("Job ID"),
         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)"),
+            .describe("For action=get/download: which figures (default headline panels; 'all'; 'none'; or a list of base names)"),
+        folder: z.string().optional().describe("For action=download: directory to save into (relative to workspace). Files land in a per-job subfolder."),
+        include_json: z.boolean().optional().describe("For action=download: also save summary.json and text/CSV artifacts"),
     }, async (args) => {
-        const { action, job_id, filename, format, figures } = args;
+        const { action, job_id, filename, format, figures, folder, include_json } = args;
         if (action === "render") {
             const fmt = format ?? "pdf";
             const submit = (await apiCall("POST", "/v1/cfd/render", { job_id, format: fmt }));
@@ -44,7 +56,7 @@ NOT FOR: Submitting jobs.`, {
                 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}").`,
+                suggested_next_step: `Figures rendered as ${fmt}. Download with barmesh_results(action=download, job_id="${job_id}") or fetch one file with action=image.`,
             });
         }
         if (action === "image") {
@@ -61,7 +73,87 @@ NOT FOR: Submitting jobs.`, {
             }
             return textResult(`${filename} is ${contentType}; saved out-of-band. For vector PDFs, open the downloaded file directly.`);
         }
-        const summary = (await apiCall("GET", `/v1/results/${job_id}`));
+        if (action === "download") {
+            if (!folder)
+                throw new Error("barmesh_results(download) requires folder");
+            let data;
+            try {
+                data = (await apiCall("GET", `/v1/results/${job_id}`));
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (/404|not found/i.test(msg)) {
+                    return textResult({
+                        error: "results_not_ready",
+                        job_id,
+                        note: `Results not found yet. If barmesh_jobs(status) shows completed with a finalize_job_id, poll status until finalize completes, then retry download.`,
+                    });
+                }
+                throw err;
+            }
+            const summary = (data.summary ?? data);
+            const jobLabel = data.label != null && data.label !== "" ? String(data.label) : null;
+            const files = summary.files ?? [];
+            const isImage = (f) => /\.(png|svg|pdf)$/i.test(f);
+            let toDownload;
+            if (figures === "all" || figures === undefined) {
+                toDownload = include_json ? files : files.filter(isImage);
+            }
+            else if (Array.isArray(figures)) {
+                toDownload = figures.flatMap((key) => {
+                    if (/\.(png|pdf|svg|csv|txt|json)$/i.test(key))
+                        return [key];
+                    return files.filter((f) => f.replace(/\.[^.]+$/, "") === key || f === key);
+                });
+            }
+            else if (figures === "none") {
+                toDownload = TEXT_ARTIFACTS.filter((f) => files.includes(f));
+            }
+            else {
+                toDownload = MESH_DEFAULT_FIGURES.flatMap((b) => files.filter((f) => f.startsWith(`${b}.`)));
+            }
+            if (include_json) {
+                for (const t of TEXT_ARTIFACTS) {
+                    if (files.includes(t) && !toDownload.includes(t))
+                        toDownload.push(t);
+                }
+            }
+            toDownload = [...new Set(toDownload)];
+            let resolvedDir = sandboxPath(folder, await getWorkspaceRootAsync(server));
+            const jobSubfolder = `cfd_mesh_convergence_${jobLabel ?? job_id}`.replace(/[^a-zA-Z0-9_.-]/g, "_");
+            resolvedDir = path.join(resolvedDir, jobSubfolder);
+            await fs.mkdir(resolvedDir, { recursive: true });
+            const saved = [];
+            for (const fname of toDownload) {
+                try {
+                    const { data: buf } = await apiRawCall(`/v1/results/${job_id}/image/${fname}`);
+                    await fs.writeFile(path.join(resolvedDir, fname), buf);
+                    saved.push(fname);
+                }
+                catch {
+                    /* skip missing */
+                }
+            }
+            const savedDir = path.join(folder, jobSubfolder);
+            return textResult(saved.length > 0
+                ? `Saved ${saved.length} file(s) to ${savedDir}: ${saved.join(", ")}`
+                : `No files saved. Check job_id and that the job (and cfd_finalize, if any) is completed.`);
+        }
+        let summary;
+        try {
+            summary = (await apiCall("GET", `/v1/results/${job_id}`));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (/404|not found/i.test(msg)) {
+                return textResult({
+                    error: "results_not_ready",
+                    job_id,
+                    note: `Results not available yet (HTTP 404). Compute may be done but cfd_finalize is still rendering figures — poll barmesh_jobs(action=status, job_id="${job_id}") until finalize_job_id completes, then retry barmesh_results(action=get).`,
+                });
+            }
+            throw err;
+        }
         const content = [{ type: "text", text: JSON.stringify(summary, null, 2) }];
         if (figures === "none")
             return { content };
@@ -82,7 +174,6 @@ NOT FOR: Submitting jobs.`, {
                 .filter((f) => f != null);
         }
         else {
-            // default headline panels (PNG) when present
             toFetch = MESH_DEFAULT_FIGURES.map((b) => `${b}.png`).filter((f) => imageFiles.includes(f));
         }
         for (const f of toFetch) {