@barivia/barmesh-mcp 0.5.1 → 0.5.3

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) {

package/dist/tools/training_monitor.js

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import { registerAuditedTool } from "../audit.js";
+import { textResult } from "../shared.js";
+import { DEFAULT_BLOCK_UNTIL_SEC, DEFAULT_POLL_INTERVAL_SEC, formatMonitorText, monitorJob, } from "../job_monitor.js";
+const MONITOR_DESCRIPTION = `Block until a barmesh_mesh_convergence or barmesh_richardson job reaches a terminal state, emitting compact progress snapshots along the way.
+
+BEST FOR: After job submit — one call replaces manual barmesh_jobs(status) poll loops (10–20s × several minutes).
+ASYNC PROTOCOL: Server-side poll every ~5s (configurable) until completed/failed/cancelled or block_until timeout. Snapshots include phase, epoch/total, QE/TE, ETA, and ordering_errors tail when live.
+FINALIZE: When defer_figures is used, waits for cfd_finalize and adds a snapshot when figure render starts/completes.
+NOT REQUIRED: barmesh_jobs(action=status) still works for one-shot checks; this tool is the agent-friendly blocking variant (barsom training_monitor parity for headless workflows).
+ESCALATION: On timeout, re-run with a higher block_until_sec; on failed, read failure_stage in the final snapshot.`;
+const monitorSchema = {
+    job_id: z.string().describe("Job ID from barmesh_mesh_convergence or barmesh_richardson"),
+    block_until_sec: z
+        .number()
+        .int()
+        .min(30)
+        .optional()
+        .describe(`Max seconds to wait (default ${DEFAULT_BLOCK_UNTIL_SEC}; mesh jobs often need 6–10 min)`),
+    poll_interval_sec: z
+        .number()
+        .int()
+        .min(5)
+        .optional()
+        .describe(`Seconds between status polls (default ${DEFAULT_POLL_INTERVAL_SEC}; do not go below 5)`),
+    wait_finalize: z
+        .boolean()
+        .optional()
+        .describe("When true (default), wait for cfd_finalize after compute completes before returning"),
+};
+async function runMonitor(args) {
+    const block_until_sec = args.block_until_sec ?? DEFAULT_BLOCK_UNTIL_SEC;
+    const poll_interval_sec = args.poll_interval_sec ?? DEFAULT_POLL_INTERVAL_SEC;
+    const result = await monitorJob(args.job_id, {
+        block_until_sec,
+        poll_interval_sec,
+        wait_finalize: args.wait_finalize,
+    });
+    const text = formatMonitorText(result, { block_until_sec, poll_interval_sec });
+    return textResult({
+        ...result.data,
+        monitor: {
+            job_id: result.job_id,
+            terminal: result.terminal,
+            timed_out: result.timed_out,
+            snapshots: result.snapshots,
+            status_text: result.status_text,
+            suggested_next_step: result.suggested_next_step,
+        },
+        status_text: text,
+    });
+}
+export function registerTrainingMonitorTool(server) {
+    registerAuditedTool(server, "barmesh_training_monitor", MONITOR_DESCRIPTION, monitorSchema, runMonitor);
+}
+export { runMonitor, MONITOR_DESCRIPTION, monitorSchema };