@barivia/barmesh-mcp 0.6.3 → 0.7.1

package/README.md

@@ -79,12 +79,13 @@ API key; otherwise the analysis calls return HTTP 403. Contact Barivia to enable
 - **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
+  server-side with compact snapshots (phase, epoch, QE, **panel/map 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
 
+- **Fixed-panel live TE (0.6.3 / barsom 0.20.4):** mid-training TE uses a fixed evaluation panel (`te_panel_size`; `te_inner_samples` alias). Curves stay on panel TE; monitors show **Panel TE** and **Map TE** separately — no snap-to-map on the curve tail.
 - **`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.
 

package/dist/audit.js

@@ -2,6 +2,7 @@
  * MCP tool audit wrapper — tool name, action, latency, outcome; no secrets.
  */
 import { logAudit } from "./logger.js";
+import { runWithTrace } from "./shared.js";
 const AUDIT_PARAM_KEYS = new Set([
     "action",
     "preset",
@@ -87,6 +88,7 @@ export function registerAuditedTool(server, name, description, schema, handler)
     server.tool(name, description, schema, (async (args) => {
         const rec = args;
         const action = typeof rec.action === "string" && rec.action.length > 0 ? rec.action : "default";
-        return runMcpToolAudit(name, action, rec, () => handler(args));
+        // One trace per tool invocation (every apiCall inside shares one trace_id).
+        return runWithTrace(() => runMcpToolAudit(name, action, rec, () => handler(args)));
     }));
 }

package/dist/job_monitor.js

@@ -55,6 +55,14 @@ export function snapshotFromJob(data, elapsedSec, note) {
         snap.qe = Math.round(qe * 10_000) / 10_000;
     if (te != null)
         snap.te = Math.round(te * 10_000) / 10_000;
+    const panelTe = num(data, "panel_topographic_error");
+    if (panelTe != null)
+        snap.panel_te = Math.round(panelTe * 10_000) / 10_000;
+    if (data.kernel_complete === true)
+        snap.kernel_complete = true;
+    const failureStage = str(data, "failure_stage");
+    if (failureStage)
+        snap.failure_stage = failureStage;
     const eta = num(data, "training_eta_sec");
     if (eta != null && eta > 0)
         snap.eta_sec = Math.round(eta);
@@ -79,7 +87,11 @@ export function shouldRecordSnapshot(prev, next) {
         return true;
     if (Math.abs(prev.progress_pct - next.progress_pct) >= 1)
         return true;
-    if (prev.qe !== next.qe || prev.te !== next.te)
+    if (prev.qe !== next.qe || prev.te !== next.te || prev.panel_te !== next.panel_te)
+        return true;
+    if (prev.kernel_complete !== next.kernel_complete)
+        return true;
+    if (prev.failure_stage !== next.failure_stage)
         return true;
     return false;
 }
@@ -93,6 +105,12 @@ export function formatSnapshotLine(s) {
         parts.push(`QE ${s.qe.toFixed(4)}`);
     if (s.te != null)
         parts.push(`Epoch TE ${s.te.toFixed(4)}`);
+    if (s.panel_te != null)
+        parts.push(`Panel TE ${s.panel_te.toFixed(4)}`);
+    if (s.kernel_complete)
+        parts.push("kernel complete");
+    if (s.failure_stage)
+        parts.push(`failure_stage ${s.failure_stage}`);
     if (s.eta_sec != null)
         parts.push(`ETA ~${s.eta_sec}s`);
     if (s.ordering_errors_tail?.length) {
@@ -119,6 +137,22 @@ export function formatMonitorText(result, opts) {
     lines.push(result.suggested_next_step);
     return lines.join("\n");
 }
+function failureStageHint(stage, error) {
+    const err = (error ?? "").toLowerCase();
+    if (stage === "preprocessing") {
+        return "Check barmesh_datasets(action=preview) and prepare job status.";
+    }
+    if (stage === "training") {
+        if (err.includes("memory") || err.includes("readonlymemory")) {
+            return "Reduce grid size or batch_size and retrain.";
+        }
+        return "Review mesh convergence parameters (grid, batch_size, features).";
+    }
+    if (stage === "visualization" || stage === "upload" || stage === "metrics") {
+        return "Re-run barmesh_training_monitor with wait_finalize=true or barmesh_results(action=render) for figures.";
+    }
+    return "Read the error above before retrying.";
+}
 function suggestedNextStep(job_id, data) {
     const status = String(data.status ?? "");
     if (status === "completed") {
@@ -130,7 +164,9 @@ function suggestedNextStep(job_id, data) {
     }
     if (status === "failed") {
         const stage = str(data, "failure_stage");
-        return `Job failed${stage ? ` at ${stage}` : ""}. Read the error above before retrying.`;
+        const err = str(data, "error");
+        const hint = stage ? failureStageHint(stage, err) : "Read the error above before retrying.";
+        return `Job failed${stage ? ` at ${stage}` : ""}. ${hint}`;
     }
     if (status === "cancelled")
         return `Job cancelled. Confirm with barmesh_jobs(action=status, job_id="${job_id}").`;

package/dist/logger.js

@@ -29,6 +29,9 @@ function emit(fields) {
 export function logInfo(msg, fields = {}) {
     emit({ ...fields, level: "info", msg });
 }
+export function logWarn(msg, fields = {}) {
+    emit({ ...fields, level: "warn", msg });
+}
 export function logAudit(fields) {
     emit({ ...fields, event: "mcp_tool_call", level: "info", msg: "mcp_tool_call" });
 }

package/dist/shared.js

@@ -7,22 +7,31 @@ import fs from "node:fs/promises";
 import { createReadStream, createWriteStream } from "node:fs";
 import { createGzip } from "node:zlib";
 import { createHash, randomUUID } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { logInfo } from "./logger.js";
+import { logInfo, logWarn } from "./logger.js";
 // ---------------------------------------------------------------------------
 // Config
 // ---------------------------------------------------------------------------
-export const API_URL = process.env.BARIVIA_API_URL ?? process.env.BARSOM_API_URL ?? "https://api.barivia.se";
-export const API_KEY = process.env.BARIVIA_API_KEY ?? process.env.BARSOM_API_KEY ?? "";
+export const API_URL = process.env.BARIVIA_API_URL ?? "https://api.barivia.se";
+export const API_KEY = process.env.BARIVIA_API_KEY ?? "";
 export const FETCH_TIMEOUT_MS = parseInt(process.env.BARIVIA_FETCH_TIMEOUT_MS ?? "60000", 10);
 export const MAX_RETRIES = 2;
+export const RETRY_BASE_MS = parseInt(process.env.BARIVIA_RETRY_BASE_MS ?? "1000", 10);
 export const RETRYABLE_STATUS = new Set([502, 503, 504]);
+/** Exponential backoff for transient API retries (attempt 0 → base, 1 → 2×, …). */
+export function retryDelayMs(attempt) {
+    return RETRY_BASE_MS * 2 ** attempt;
+}
+function newRequestId() {
+    return randomUUID();
+}
 /** Single source of truth for the proxy version. Keep in sync with package.json on bump. */
-export const CLIENT_VERSION = "0.6.2";
+export const CLIENT_VERSION = "0.7.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;
@@ -32,6 +41,21 @@ export const LARGE_UPLOAD_BYTES = 64 * 1024 * 1024; // 64 MB
 export const PRESIGNED_PUT_TIMEOUT_MS = 30 * 60_000; // 30 min
 /** Poll window for the async stage_dataset job. */
 export const POLL_STAGE_MAX_MS = 30 * 60_000; // 30 min
+/** Map a local upload path to the API Content-Type (csv vs tsv; ignores .gz suffix). */
+export function resolveUploadContentType(filePath) {
+    const lower = filePath.toLowerCase();
+    const base = lower.endsWith(".gz") ? lower.slice(0, -3) : lower;
+    return path.extname(base) === ".tsv" ? "text/tab-separated-values" : "text/csv";
+}
+export function suggestMeshDatasetPreview(datasetId) {
+    return `barmesh_datasets(action=preview, dataset_id=${datasetId}) to verify mesh, feature, and volume columns.`;
+}
+export function suggestAfterCfdSubmit(jobId, prepSuffix = "") {
+    return `Run barmesh_training_monitor(job_id="${jobId}") or barmesh_jobs(action=monitor, job_id="${jobId}")${prepSuffix}; on completion call barmesh_results(action=get, job_id="${jobId}").`;
+}
+export function suggestAfterRender(parentJobId, fmt) {
+    return `Figures rendered as ${fmt}. Download with barmesh_results(action=download, job_id="${parentJobId}") or barmesh_results(action=image, job_id="${parentJobId}", filename=<figure>.${fmt}).`;
+}
 /** Streaming SHA-256 of a file (idempotency key) without reading it into memory. */
 export async function streamFileSha256(srcPath) {
     return new Promise((resolve, reject) => {
@@ -79,7 +103,11 @@ export async function putPresignedStream(url, srcPath, contentType, timeoutMs =
         const resp = await fetch(url, {
             method: "PUT",
             body: webStream,
-            headers: { "Content-Type": contentType, "Content-Length": String(contentLength) },
+            headers: {
+                "Content-Type": contentType,
+                "Content-Length": String(contentLength),
+                "Content-Encoding": "gzip",
+            },
             duplex: "half",
             signal: controller.signal,
         });
@@ -146,7 +174,7 @@ export async function fetchWithTimeout(url, init, timeoutMs = FETCH_TIMEOUT_MS)
 // Path / sandbox helpers
 // ---------------------------------------------------------------------------
 export function getSandboxRoot() {
-    const raw = process.env.BARIVIA_WORKSPACE_ROOT ?? process.env.BARSOM_WORKSPACE_ROOT;
+    const raw = process.env.BARIVIA_WORKSPACE_ROOT;
     if (raw)
         return path.resolve(process.cwd(), raw);
     const workspaceFolder = process.env.CURSOR_WORKSPACE_FOLDER ?? process.env.WORKSPACE_FOLDER;
@@ -260,14 +288,33 @@ function throwApiError(status, bodyText, requestId) {
     err.httpStatus = status;
     throw err;
 }
+// ---- Distributed-trace context (W3C traceparent) ----
+// One trace per logical tool action (scoped via AsyncLocalStorage in registerAuditedTool),
+// so the API + job chain reconstruct end-to-end. Fresh span per API call; falls back to a
+// per-call trace if no scope is set. Mirrors the barsom proxy.
+const _traceStore = new AsyncLocalStorage();
+function _newTraceId() {
+    return randomUUID().replace(/-/g, "");
+}
+function _newSpanId() {
+    return randomUUID().replace(/-/g, "").slice(0, 16);
+}
+/** Run `fn` within a fresh trace scope so all apiCall()s inside share one trace_id. */
+export function runWithTrace(fn) {
+    return _traceStore.run(_newTraceId(), fn);
+}
+function _traceparentHeader() {
+    return `00-${_traceStore.getStore() ?? _newTraceId()}-${_newSpanId()}-01`;
+}
 export async function apiCall(method, pathPart, body, extraHeaders, requestTimeoutMs) {
     const url = `${API_URL}${pathPart}`;
     const contentType = extraHeaders?.["Content-Type"] ?? "application/json";
-    const requestId = Math.random().toString(36).slice(2, 10);
+    const requestId = newRequestId();
     const headers = {
         Authorization: `Bearer ${API_KEY}`,
         "Content-Type": contentType,
         "X-Request-ID": requestId,
+        traceparent: _traceparentHeader(),
         "X-Barmesh-Client-Version": CLIENT_VERSION,
         ...extraHeaders,
     };
@@ -290,7 +337,17 @@ export async function apiCall(method, pathPart, body, extraHeaders, requestTimeo
             const text = await resp.text();
             if (!resp.ok) {
                 if (attempt < MAX_RETRIES && isTransientError(null, resp.status)) {
-                    await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
+                    const delayMs = retryDelayMs(attempt);
+                    logWarn("API retry", {
+                        rid: requestId,
+                        action: method,
+                        path: pathPart,
+                        attempt: attempt + 1,
+                        max_retries: MAX_RETRIES,
+                        delay_ms: delayMs,
+                        error_code: `http_${resp.status}`,
+                    });
+                    await new Promise((r) => setTimeout(r, delayMs));
                     continue;
                 }
                 logInfo("API response", { rid: requestId, outcome: "error", duration_ms: Date.now() - t0, error_code: `http_${resp.status}` });
@@ -302,7 +359,17 @@ export async function apiCall(method, pathPart, body, extraHeaders, requestTimeo
         catch (err) {
             lastError = err;
             if (attempt < MAX_RETRIES && isTransientError(err)) {
-                await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
+                const delayMs = retryDelayMs(attempt);
+                logWarn("API retry", {
+                    rid: requestId,
+                    action: method,
+                    path: pathPart,
+                    attempt: attempt + 1,
+                    max_retries: MAX_RETRIES,
+                    delay_ms: delayMs,
+                    error_code: err instanceof Error ? err.name : "fetch_error",
+                });
+                await new Promise((r) => setTimeout(r, delayMs));
                 continue;
             }
             if (err instanceof DOMException && err.name === "AbortError" && !err.httpStatus) {
@@ -316,15 +383,24 @@ export async function apiCall(method, pathPart, body, extraHeaders, requestTimeo
 /** Fetch raw bytes from the API (for image downloads). */
 export async function apiRawCall(pathPart, requestTimeoutMs) {
     const url = `${API_URL}${pathPart}`;
-    const requestId = Math.random().toString(36).slice(2, 10);
+    const requestId = newRequestId();
     const effectiveTimeout = requestTimeoutMs ?? FETCH_TIMEOUT_MS;
     let lastError;
     for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
         try {
-            const resp = await fetchWithTimeout(url, { method: "GET", headers: { Authorization: `Bearer ${API_KEY}`, "X-Request-ID": requestId } }, effectiveTimeout);
+            const resp = await fetchWithTimeout(url, { method: "GET", headers: { Authorization: `Bearer ${API_KEY}`, "X-Request-ID": requestId, traceparent: _traceparentHeader() } }, effectiveTimeout);
             if (!resp.ok) {
                 if (attempt < MAX_RETRIES && isTransientError(null, resp.status)) {
-                    await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
+                    const delayMs = retryDelayMs(attempt);
+                    logWarn("API retry", {
+                        rid: requestId,
+                        path: pathPart,
+                        attempt: attempt + 1,
+                        max_retries: MAX_RETRIES,
+                        delay_ms: delayMs,
+                        error_code: `http_${resp.status}`,
+                    });
+                    await new Promise((r) => setTimeout(r, delayMs));
                     continue;
                 }
                 const text = await resp.text();
@@ -339,7 +415,16 @@ export async function apiRawCall(pathPart, requestTimeoutMs) {
         catch (err) {
             lastError = err;
             if (attempt < MAX_RETRIES && isTransientError(err)) {
-                await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
+                const delayMs = retryDelayMs(attempt);
+                logWarn("API retry", {
+                    rid: requestId,
+                    path: pathPart,
+                    attempt: attempt + 1,
+                    max_retries: MAX_RETRIES,
+                    delay_ms: delayMs,
+                    error_code: err instanceof Error ? err.name : "fetch_error",
+                });
+                await new Promise((r) => setTimeout(r, delayMs));
                 continue;
             }
             if (err instanceof DOMException && err.name === "AbortError" && !err.httpStatus) {

package/dist/tools/barmesh_results_explorer.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
-import { registerAuditedTool, runMcpToolAudit } from "../audit.js";
+import { runMcpToolAudit } from "../audit.js";
 import { apiCall, apiRawCall, getClientSupportsMcpApps, getVizPort, getCaptionForImage, mimeForFilename, structuredTextResult, tryAttachImage, } from "../shared.js";
 import { FIGURE_SECTION_LABELS, FIGURE_SECTION_ORDER, figureSection, sortRank, } from "../figure_sections.js";
 import { buildMetadataStrip } from "../results_metadata.js";
@@ -178,9 +178,14 @@ export function registerResultsExplorerTool(server) {
         _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))));
-    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(),
+    registerAppTool(server, "_barmesh_fetch_figure", {
+        title: "Fetch figure (internal)",
+        description: "[INTERNAL — MCP App only; agents MUST NOT call.] Lazy-loads one raster figure as base64 for the Mesh Convergence Results Explorer.",
+        inputSchema: {
+            job_id: z.string(),
+            filename: z.string(),
+        },
+        _meta: { ui: { resourceUri: RESULTS_EXPLORER_URI, visibility: ["app"] } },
     }, async ({ job_id, filename }) => {
         const safeFilename = filename.replace(/[^a-zA-Z0-9._-]/g, "");
         const mime = mimeForFilename(safeFilename);

package/dist/tools/cfd.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
-import { apiCall, textResult } from "../shared.js";
+import { apiCall, textResult, suggestAfterCfdSubmit } from "../shared.js";
 import { pollCfdPrepareIfPresent } from "../cfd_prepare.js";
 export function registerCfdTools(server) {
     registerAuditedTool(server, "barmesh_mesh_convergence", `Run SOM-based mesh-convergence analysis on an uploaded combined per-cell CSV.
@@ -52,7 +52,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 = `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}").`;
+            data.suggested_next_step = suggestAfterCfdSubmit(String(id), prep);
         }
         return textResult(data);
     });
@@ -85,7 +85,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 = `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}").`;
+            data.suggested_next_step = suggestAfterCfdSubmit(String(id));
         return textResult(data);
     });
 }

package/dist/tools/datasets.js

@@ -4,7 +4,7 @@ import { z } from "zod";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { registerAuditedTool } from "../audit.js";
-import { apiCall, getWorkspaceRootAsync, resolveFilePathForUpload, textResult, pollUntilComplete, UPLOAD_DATASET_TIMEOUT_MS, LARGE_UPLOAD_BYTES, PRESIGNED_PUT_TIMEOUT_MS, POLL_STAGE_MAX_MS, streamFileSha256, putPresignedStream, } from "../shared.js";
+import { apiCall, getWorkspaceRootAsync, resolveFilePathForUpload, textResult, pollUntilComplete, UPLOAD_DATASET_TIMEOUT_MS, LARGE_UPLOAD_BYTES, PRESIGNED_PUT_TIMEOUT_MS, POLL_STAGE_MAX_MS, streamFileSha256, putPresignedStream, resolveUploadContentType, suggestMeshDatasetPreview, } from "../shared.js";
 import { GZIP_UPLOAD_HINT } from "../upload_hints.js";
 /**
  * Normalize a nullable string field from the API. Returns "" for absent values,
@@ -91,9 +91,11 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
             if (!name)
                 throw new Error("barmesh_datasets(upload) requires name.");
             let body;
+            let uploadContentType = "text/csv";
             if (file_path && file_path.length > 0) {
                 await apiCall("GET", "/v1/system/info");
                 const resolved = await resolveFilePathForUpload(file_path, server);
+                uploadContentType = resolveUploadContentType(resolved);
                 const lower = resolved.toLowerCase();
                 const isGzipInput = lower.endsWith(".gz");
                 const baseExt = path.extname(isGzipInput ? lower.slice(0, -3) : lower);
@@ -134,10 +136,10 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
                             id: datasetId,
                             status: init.status,
                             idempotent_replay: true,
-                            suggested_next_step: `barmesh_datasets(action=preview, dataset_id=${datasetId})`,
+                            suggested_next_step: suggestMeshDatasetPreview(datasetId),
                         });
                     }
-                    await putPresignedStream(init.upload_url, resolved, init.content_type ?? "application/octet-stream", PRESIGNED_PUT_TIMEOUT_MS, isGzipInput);
+                    await putPresignedStream(init.upload_url, resolved, init.content_type ?? uploadContentType, PRESIGNED_PUT_TIMEOUT_MS, isGzipInput);
                     const fin = (await apiCall("POST", `/v1/datasets/${datasetId}/finalize`, {}));
                     const jobId = (fin.id ?? fin.job_id);
                     const poll = await pollUntilComplete(jobId, POLL_STAGE_MAX_MS);
@@ -150,21 +152,21 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
                         status: ready ? "ready" : "staging",
                         job_id: jobId,
                         suggested_next_step: ready
-                            ? `barmesh_datasets(action=preview, dataset_id=${datasetId}) to verify mesh, feature, and volume columns.`
-                            : `Still staging; poll barmesh_jobs(action=status, job_id="${jobId}") then barmesh_datasets(action=preview, dataset_id=${datasetId}).`,
+                            ? suggestMeshDatasetPreview(datasetId)
+                            : `Still staging; poll barmesh_jobs(action=status, job_id="${jobId}") then ${suggestMeshDatasetPreview(datasetId)}.`,
                     });
                 }
                 if (isGzipInput) {
                     const gzBytes = await fs.readFile(resolved);
                     const data = (await apiCall("POST", "/v1/datasets", gzBytes, {
                         "X-Dataset-Name": name,
-                        "Content-Type": "text/csv",
+                        "Content-Type": uploadContentType,
                         "Content-Encoding": "gzip",
                         "Idempotency-Key": createHash("sha256").update(`${name}\n`).update(gzBytes).digest("hex"),
                     }, UPLOAD_DATASET_TIMEOUT_MS));
                     const gid = data.id ?? data.dataset_id;
                     if (gid != null) {
-                        data.suggested_next_step = `Next: barmesh_datasets(action=preview, dataset_id=${gid}) to verify the mesh, feature, and volume columns.`;
+                        data.suggested_next_step = suggestMeshDatasetPreview(String(gid));
                     }
                     return textResult(data);
                 }
@@ -179,7 +181,7 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
             const GZIP_THRESHOLD = 1024 * 1024;
             const uploadHeaders = {
                 "X-Dataset-Name": name,
-                "Content-Type": "text/csv",
+                "Content-Type": uploadContentType,
                 "Idempotency-Key": createHash("sha256").update(`${name}\n`).update(body).digest("hex"),
             };
             let uploadBody = body;
@@ -190,7 +192,7 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
             const data = (await apiCall("POST", "/v1/datasets", uploadBody, uploadHeaders, UPLOAD_DATASET_TIMEOUT_MS));
             const id = data.id ?? data.dataset_id;
             if (id != null) {
-                data.suggested_next_step = `Next: barmesh_datasets(action=preview, dataset_id=${id}) to verify the mesh, feature, and volume columns.`;
+                data.suggested_next_step = suggestMeshDatasetPreview(String(id));
             }
             return textResult(data);
         }

package/dist/tools/guide.js

@@ -1,9 +1,19 @@
 import { registerAuditedTool } from "../audit.js";
 import { apiCall, textResult } from "../shared.js";
 const OFFLINE_GUIDE = `barmesh: CFD mesh-convergence on the Barivia API.
-Two tracks: barmesh_mesh_convergence (SOM fingerprint distances) and barmesh_richardson (classical GCI).
-Workflow: barmesh_prepare_mesh_data -> barmesh_datasets(upload) -> barmesh_mesh_convergence / barmesh_richardson -> barmesh_training_monitor (default visual MCP App; post-hoc review when already done) or barmesh_jobs(monitor/status) headless fallback -> barmesh_results(get) -> barmesh_results_explorer for figures.
-(API unreachable; this is the offline summary. Set BARIVIA_API_KEY / BARIVIA_API_URL.)`;
+
+Two tracks:
+- barmesh_mesh_convergence — SOM volume-fingerprint distances (symmetric KL + Wasserstein-1 vs reference and stepwise)
+- barmesh_richardson — classical Richardson / GCI on scalar QoIs
+
+Workflow:
+1. barmesh_prepare_mesh_data — recipe for the combined per-cell CSV (mesh_id + features + cell volume V)
+2. barmesh_datasets(upload) → barmesh_datasets(preview)
+3. barmesh_mesh_convergence and/or barmesh_richardson — returns job_id
+4. barmesh_training_monitor (visual MCP App) or barmesh_jobs(action=monitor) headless — poll until complete
+5. barmesh_results(action=get) → barmesh_results_explorer for figures
+
+(API unreachable; 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:
 - one row per cell; a mesh label column (mesh_id); the physical channels you want compared (e.g. p, U_mag, k, log_epsilon — log-compress turbulence quantities); and a cell-volume column (V) for fingerprint weighting.

package/dist/tools/results.js

@@ -2,7 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
-import { apiCall, apiRawCall, getWorkspaceRootAsync, sandboxPath, textResult, tryAttachImage, resetInlineAttachBudget, pollUntilComplete, POLL_STAGE_MAX_MS, } from "../shared.js";
+import { apiCall, apiRawCall, getWorkspaceRootAsync, sandboxPath, textResult, tryAttachImage, resetInlineAttachBudget, pollUntilComplete, POLL_STAGE_MAX_MS, suggestAfterRender, } from "../shared.js";
 import { formatConvergenceReading } from "../convergence_reading.js";
 const MESH_DEFAULT_FIGURES = ["combined", "overview_distances", "plot_vol_all_meshes", "plot_vol_steps", "learning_curve"];
 function formatMeshResultsSummary(jobId, data, summary) {
@@ -84,7 +84,7 @@ NOT FOR: Submitting jobs.`, {
                 status: "completed",
                 render_job_id: renderId,
                 format: fmt,
-                suggested_next_step: `Figures rendered as ${fmt}. Download with barmesh_results(action=download, job_id="${job_id}") or fetch one file with action=image.`,
+                suggested_next_step: suggestAfterRender(job_id, fmt),
             });
         }
         if (action === "image") {

package/dist/training_monitor_curve.js

@@ -16,7 +16,7 @@ export function isKernelTrainingComplete(data, status) {
         return true;
     return status === "completed";
 }
-export function teCurveLabel(base, _kernelComplete = false) {
+export function teCurveLabel(base) {
     return `${base} (panel)`;
 }
 export function formatCurveSourceNote(data) {