@barivia/barmesh-mcp 0.8.7 → 0.8.9

package/dist/index.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import{McpServer as e}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport as r}from"@modelcontextprotocol/sdk/server/stdio.js";import{getUiCapability as s,registerAppResource as t,RESOURCE_MIME_TYPE as o}from"@modelcontextprotocol/ext-apps/server";import{startVizServer as n}from"./viz-server.js";import{API_KEY as a,CLIENT_VERSION as i,apiCall as l,apiRawCall as c,loadViewHtml as m,setVizPort as d,setClientSupportsMcpApps as h}from"./shared.js";import{registerGuideTool as u}from"./tools/guide.js";import{registerDatasetsTool as p}from"./tools/datasets.js";import{registerCfdTools as b}from"./tools/cfd.js";import{registerJobsTool as f}from"./tools/jobs.js";import{registerResultsTool as _}from"./tools/results.js";import{registerResultsExplorerTool as y,RESULTS_EXPLORER_URI as v}from"./tools/barmesh_results_explorer.js";import{registerTrainingMonitorTool as g,TRAINING_MONITOR_URI as w}from"./tools/training_monitor.js";import{registerFeedbackTool as I}from"./tools/feedback.js";a||(console.error("Error: BARIVIA_API_KEY not set. Set it in your MCP client config."),process.exit(1));(async function(){const a=new e({name:"barmesh",version:i},{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 (optional description/tags for inventory).\n4. barmesh_mesh_convergence (and/or barmesh_richardson) — returns a job id.\n5. barmesh_training_monitor(job_id) — visual MCP App with live curves (default); barmesh_jobs(action=monitor) — headless blocking snapshots; or barmesh_jobs(status) for one-shot polls every 10-20s.\n6. barmesh_results(action=get) — distances, convergence reading, and figures; then\n   barmesh_results_explorer(job_id) to browse every figure interactively.\n\n## Org inventory recipe\n- Prefer `barmesh_jobs(action=inventory)` for a markdown datasets+jobs overview.\n- Or compose `barmesh_datasets(list)` + `barmesh_jobs(action=list, limit=50)` (page with `cursor`; filter with `status`/`job_type`/`has_results=true` for a results catalog).\n- Set `description`+`tags` on upload/submit/update so duplicates stay navigable. List is slim by default (no fat params).\n\n## UI delivery (barmesh_training_monitor, barmesh_results_explorer)\n\nHosts vary: some embed MCP Apps; others list ui:// but never mount them (expected on some Cursor builds). Tool results always lead with a standalone localhost URL and a structured ui_delivery block (delivery, urls, hint_for_agent) — follow hint_for_agent without user prompting.\n\n- Surface the standalone URL as a clickable markdown link. Do not bury it after metrics.\n- Env: BARIVIA_UI_DELIVERY=auto|apps|localhost|inline; BARIVIA_VIZ_PORT pins the viz port across restarts.\n- Standalone pages cross-link training monitor ↔ results explorer for the same job_id.\n\nThese tools are gated by the 'cfd' entitlement; analysis calls return 403 if your plan\ndoes not include it.\n\n## API briefly unavailable (demos)\nIf barmesh_jobs / barmesh_results / barmesh_send_feedback (or any tool) reports the mesh analysis\nAPI temporarily unavailable: say so in one calm line, do not paste HTML/502 pages, and pause\nafter the proxy's burst retries (3 tries ~2s apart; then retry_after_sec≈30). Figures already\ndownloaded stay usable. Keep talking about the last good distances, GCI CSV, and figures —\ndegrade to \"review what we have\", not \"everything failed\". Suggest a later retry for new jobs\nor feedback.\n\n## Outages / feedback\n- barmesh_api_health probes GET /health + /ready (no R2). Use when tools fail with api_unreachable.\n- barmesh_send_feedback queues drafts under ~/.barivia/deferred-feedback when the API/gateway\n  is down and flushes them on the next successful call (shared directory with barsom send_feedback).\n- API errors are slim structured lines (error_code, cause, request_id, retry_after_sec) — never raw Cloudflare HTML."});t(a,v,v,{mimeType:o},async()=>{const e=await m("barmesh-results-explorer");return{contents:[{uri:v,mimeType:o,text:e??"<html><body>Results Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),t(a,w,w,{mimeType:o},async()=>{const e=await m("barmesh-training-monitor");return{contents:[{uri:w,mimeType:o,text:e??"<html><body>Training Monitor view not built yet. Run: npm run build:views</body></html>"}]}}),u(a),y(a),p(a),b(a),f(a),g(a),_(a),I(a);try{const e=await n(l,c,m);d(e)}catch(e){process.env.BARIVIA_VIZ_PORT&&console.error("barmesh viz server failed to start:",e)}const j=a.server;j.oninitialized=()=>{const e=j.getClientCapabilities(),r=s(e);h(!!r?.mimeTypes?.includes(o))};const k=new r;await a.connect(k),console.error(`barmesh-mcp ${i} 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 o,registerAppResource as s,RESOURCE_MIME_TYPE as t}from"@modelcontextprotocol/ext-apps/server";import{startVizServer as n}from"./viz-server.js";import{API_KEY as i,CLIENT_VERSION as a,apiCall as m,apiRawCall as l,loadViewHtml as c,setVizPort as p,setClientSupportsMcpApps as h}from"./shared.js";import{registerGuideTool as d}from"./tools/guide.js";import{registerDatasetsTool as _}from"./tools/datasets.js";import{registerCfdTools as b}from"./tools/cfd.js";import{registerJobsTool as u}from"./tools/jobs.js";import{registerResultsTool as f}from"./tools/results.js";import{registerResultsExplorerTool as v,RESULTS_EXPLORER_URI as y}from"./tools/barmesh_results_explorer.js";import{registerTrainingMonitorTool as I,TRAINING_MONITOR_URI as w}from"./tools/training_monitor.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\n## Bootstrap (do this first)\n\nCall `barmesh_guide_workflow` (plan-scoped) and `barmesh_prepare_mesh_data` before upload/submit. Method details and mesh-prep recipe come from the API when your key has the CFD entitlement.\n\n## Tracks (names only)\n\n- `barmesh_mesh_convergence` — field-level mesh comparison (SOM fingerprints)\n- `barmesh_richardson` — classical Richardson/GCI on scalar QoIs\n\n## Workflow (short)\n\n1. `barmesh_guide_workflow`\n2. `barmesh_prepare_mesh_data`\n3. `barmesh_datasets(upload)` → preview\n4. Submit mesh_convergence and/or richardson → job_id\n5. `barmesh_training_monitor` or `barmesh_jobs(monitor/status)`\n6. `barmesh_results(get)` → `barmesh_results_explorer`\n\nInventory: `barmesh_jobs(inventory)` or list datasets+jobs. Set description/tags on upload/submit.\n\n## UI / outages\n\nTool results lead with a localhost viz URL and `ui_delivery` — follow `hint_for_agent`. Env: `BARIVIA_UI_DELIVERY`, `BARIVIA_VIZ_PORT`.\nOn `api_unreachable`: one calm line; honor `retry_after_sec`; use `barmesh_api_health`; keep reviewing last good figures. `barmesh_send_feedback` queues deferred drafts when the API is down."});s(i,y,y,{mimeType:t},async()=>{const e=await c("barmesh-results-explorer");return{contents:[{uri:y,mimeType:t,text:e??"<html><body>Results Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),s(i,w,w,{mimeType:t},async()=>{const e=await c("barmesh-training-monitor");return{contents:[{uri:w,mimeType:t,text:e??"<html><body>Training Monitor view not built yet. Run: npm run build:views</body></html>"}]}}),d(i),v(i),_(i),b(i),u(i),I(i),f(i),g(i);try{const e=await n(m,l,c);p(e)}catch(e){process.env.BARIVIA_VIZ_PORT&&console.error("barmesh viz server failed to start:",e)}const j=i.server;j.oninitialized=()=>{const e=j.getClientCapabilities(),r=o(e);h(!!r?.mimeTypes?.includes(t))};const A=new r;await i.connect(A),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/shared.js

@@ -35,7 +35,7 @@ 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.8.7";
+export const CLIENT_VERSION = "0.8.9";
 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;

package/dist/tools/cfd.js

@@ -5,34 +5,33 @@ 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.
 
-What it does (one call): joint-normalizes all meshes, trains one SOM on a stratified pooled subsample, projects each mesh to a volume-weighted fingerprint, and computes symmetric KL and Wasserstein-1 (EMD) distances stepwise and against a reference mesh, plus publication figures and an advisory convergence reading.
-
-BEST FOR: A mesh-refinement study where you want a field-level (not just scalar) view of whether the mesh has converged.
-NOT FOR: Single scalar quantities of interest — use barmesh_richardson for classical GCI.
-ASYNC: This is a queued job. It returns a job id immediately. Then poll barmesh_jobs(action=status) every 10-20s; datacenter-scale grids plus EMD can take a few minutes — keep polling. On completion call barmesh_results(action=get).
-COMMON MISTAKES: omitting feature_columns (required); choosing a reference_mesh label that is not present; forgetting the cell-volume column at upload time; multi-topology studies (uniform U + graded G meshes) without explicit mesh_order — equal cell counts sort U-then-G and invent bogus stepwise pairs (U160|G20). Pass mesh_order coarse→fine interleaved by refinement (U20,G20,U40,G40,…) or use preset=cavity which defaults interleaved when U/G labels are detected.`, {
+BEST FOR: Field-level mesh-refinement comparison (not a single scalar QoI).
+NOT FOR: Classical GCI on scalars — use barmesh_richardson.
+ASYNC: Returns job_id; poll barmesh_jobs(status) every 10–20s; then barmesh_results(get).
+Call **barmesh_guide_workflow** / **barmesh_prepare_mesh_data** for method details, mesh_order rules, and prep recipe (API, CFD entitlement).
+COMMON MISTAKES: omitting feature_columns; bad reference_mesh label; missing volume column — see prepare_mesh_data.`, {
         dataset_id: z.string().describe("Dataset ID from barmesh_datasets(upload)"),
-        feature_columns: z.array(z.string()).describe("Per-cell numeric feature columns to train the SOM on (e.g. [\"p\",\"U_mag\",\"k\",\"log_epsilon\"])"),
-        preset: z.enum(["generic", "cavity", "pitz", "datacenter"]).optional().describe("Hyperparameter preset; defaults to generic. cavity/pitz/datacenter reproduce the published settings."),
-        mesh_column: z.string().optional().describe("Column with the mesh label (default mesh_id)"),
-        volume_column: z.string().optional().describe("Cell-volume column for fingerprint weights (default V; equal weights if absent)"),
-        reference_mesh: z.string().optional().describe("Mesh label used as reference (default: the mesh with the most cells = finest)"),
-        mesh_order: z.array(z.string()).optional().describe("Explicit coarse-to-fine mesh order (default: ascending cell count; cavity preset and tied U/G cell counts auto-interleave U20→G20→U40→G40→…)"),
-        grid: z.array(z.number().int()).optional().describe("SOM grid [rows, cols] (overrides preset)"),
-        epochs: z.array(z.number().int()).optional().describe("[ordering, convergence] epochs (overrides preset)"),
-        batch_size: z.number().int().optional().describe("SOM batch size (overrides preset)"),
-        sigma_f: z.number().optional().describe("Final ordering neighborhood width (overrides preset)"),
-        backend: z.enum(["auto", "cpu", "gpu", "gpu_graphs"]).optional().describe("Compute backend (default auto / preset)"),
-        stratify_scale: z.number().optional().describe("[0,1] per-mesh training-row cap; 1 uses all cells (default 1)"),
-        emd_method: z.enum(["exact", "sinkhorn"]).optional().describe("EMD solver: exact LP (default) or sinkhorn (fast approximation for large grids)"),
-        te_panel_size: z.number().int().optional().describe("Fixed evaluation-panel size for live topographic error during training (default clamp(grid_nodes*6, 500, 10000); curve stays on this panel end-to-end)"),
+        feature_columns: z.array(z.string()).describe("Per-cell numeric feature columns for the SOM"),
+        preset: z.enum(["generic", "cavity", "pitz", "datacenter"]).optional().describe("Hyperparameter preset (default generic) — see barmesh_guide_workflow"),
+        mesh_column: z.string().optional().describe("Mesh label column (default mesh_id)"),
+        volume_column: z.string().optional().describe("Cell-volume column (default V)"),
+        reference_mesh: z.string().optional().describe("Reference mesh label (default: finest / most cells)"),
+        mesh_order: z.array(z.string()).optional().describe("Explicit coarse→fine mesh order — see barmesh_prepare_mesh_data"),
+        grid: z.array(z.number().int()).optional().describe("SOM grid [rows, cols] override"),
+        epochs: z.array(z.number().int()).optional().describe("[ordering, convergence] epochs override"),
+        batch_size: z.number().int().optional().describe("SOM batch size override"),
+        sigma_f: z.number().optional().describe("Final ordering neighborhood width override"),
+        backend: z.enum(["auto", "cpu", "gpu", "gpu_graphs"]).optional().describe("Compute backend"),
+        stratify_scale: z.number().optional().describe("[0,1] per-mesh training-row cap"),
+        emd_method: z.enum(["exact", "sinkhorn"]).optional().describe("EMD solver — see barmesh_guide_workflow"),
+        te_panel_size: z.number().int().optional().describe("Live TE evaluation panel size"),
         te_inner_samples: z.number().int().optional().describe("Deprecated alias for te_panel_size"),
-        component_planes_physical: z.boolean().optional().describe("Physical-scale component-plane colorbars (default true)"),
+        component_planes_physical: z.boolean().optional().describe("Physical-scale component-plane colorbars"),
         figures: z.boolean().optional().describe("Generate publication figures (default true)"),
-        transforms: z.record(z.enum(["log", "log1p", "log10", "sqrt", "square", "abs", "invert", "none"])).optional().describe("Per-feature transform applied before normalization (e.g. log1p to compress k/epsilon/omega). Same preprocessing engine as barsom training."),
-        normalize: z.union([z.enum(["all", "auto", "mad", "sigmoidal", "sepd"]), z.array(z.string())]).optional().describe("Normalization mode for SOM features (default auto = joint z-score of non-cyclic features). Use mad for heavy-tailed channels."),
-        normalization_methods: z.record(z.enum(["zscore", "mad", "sigmoidal", "sepd", "none"])).optional().describe("Per-feature normalization override; keys must be in feature_columns."),
-        row_range: z.tuple([z.number().int().min(1), z.number().int().min(1)]).optional().describe("1-based inclusive [start, end] row slice applied during preprocessing (and to mesh labels / cell volumes)."),
+        transforms: z.record(z.enum(["log", "log1p", "log10", "sqrt", "square", "abs", "invert", "none"])).optional().describe("Per-feature transform before normalization"),
+        normalize: z.union([z.enum(["all", "auto", "mad", "sigmoidal", "sepd"]), z.array(z.string())]).optional().describe("SOM feature normalization mode"),
+        normalization_methods: z.record(z.enum(["zscore", "mad", "sigmoidal", "sepd", "none"])).optional().describe("Per-feature normalization override"),
+        row_range: z.tuple([z.number().int().min(1), z.number().int().min(1)]).optional().describe("1-based inclusive [start, end] row slice"),
         label: z.string().optional().describe("Optional job label"),
         description: z.string().optional().describe("Optional free-text description for inventory"),
         tags: z.array(z.string()).optional().describe("Optional tags for inventory/navigation"),
@@ -63,21 +62,20 @@ COMMON MISTAKES: omitting feature_columns (required); choosing a reference_mesh
         }
         return textResult(data);
     });
-    registerAuditedTool(server, "barmesh_richardson", `Run classical Richardson extrapolation / Grid Convergence Index (GCI) on scalar quantities of interest.
-
-What it does: from a small CSV with one row per mesh (a mesh label, a representative cell size h or a cell count, and one or more QoI columns), slides the three-level Celik (2008) GCI over consecutive mesh triplets (finest first) and reports the observed order p, the extrapolated value, and the fine-grid GCI per triplet per QoI.
+    registerAuditedTool(server, "barmesh_richardson", `Run classical Richardson extrapolation / Grid Convergence Index (GCI) on scalar QoIs.
 
-BEST FOR: Scalar benchmarks (reattachment length, centerline values, probe readings) where a classical asymptotic-convergence check is expected.
-NOT FOR: High-dimensional field comparison — use barmesh_mesh_convergence (complementary).
-ASYNC: queued job; poll barmesh_jobs(action=status), then barmesh_results(action=get).
-COMMON MISTAKES: not providing h_column or n_cells_column; mixing QoIs with different mesh sets in one CSV; mixing uniform (U…) and graded (G…) mesh families in one CSV — classical GCI assumes one topology per job; run separate Richardson jobs per family (e.g. G160|G80|G40 graded, U160|U80|U40 uniform).`, {
+BEST FOR: Scalar benchmarks where classical asymptotic-convergence checks are expected.
+NOT FOR: High-dimensional field comparison — use barmesh_mesh_convergence.
+ASYNC: queued job; poll barmesh_jobs(status), then barmesh_results(get).
+Method details (Fs, one-family-per-CSV, triplets): **barmesh_guide_workflow**.
+COMMON MISTAKES: missing h_column or n_cells_column; mixing mesh families — see guide.`, {
         dataset_id: z.string().describe("Dataset ID (one row per mesh)"),
         qoi_columns: z.array(z.string()).describe("Scalar QoI column names to extrapolate"),
         mesh_column: z.string().optional().describe("Mesh label column (default mesh_id)"),
-        h_column: z.string().optional().describe("Representative cell-size column (provide this or n_cells_column)"),
-        n_cells_column: z.string().optional().describe("Cell-count column; h is derived as n_cells^(-1/dimension)"),
-        dimension: z.number().int().optional().describe("Spatial dimension d for deriving h from cell count (default 3)"),
-        safety_factor: z.number().optional().describe("GCI safety factor Fs (default 1.25, Roache)"),
+        h_column: z.string().optional().describe("Representative cell-size column (or use n_cells_column)"),
+        n_cells_column: z.string().optional().describe("Cell-count column (alternative to h_column)"),
+        dimension: z.number().int().optional().describe("Spatial dimension for h from cell count"),
+        safety_factor: z.number().optional().describe("GCI safety factor — see barmesh_guide_workflow"),
         label: z.string().optional().describe("Optional job label"),
         description: z.string().optional().describe("Optional free-text description for inventory"),
         tags: z.array(z.string()).optional().describe("Optional tags for inventory/navigation"),

package/dist/tools/datasets.js

@@ -7,6 +7,10 @@ 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, awaitDatasetStageIfNeeded, streamFileSha256, putPresignedStream, resolveUploadContentType, suggestMeshDatasetPreview, } from "../shared.js";
 import { GZIP_UPLOAD_HINT } from "../upload_hints.js";
 import { formatDatasetInventoryLine, formatTags } from "../inventory_format.js";
+/** Percent-encode header values so Node fetch accepts Unicode (ByteString limit). */
+function encodeHeaderValue(s) {
+    return encodeURIComponent(s);
+}
 /**
  * Normalize a nullable string field from the API. Returns "" for absent values,
  * empty strings, and the literal SQL/serialization sentinels "missing"/"null".
@@ -169,15 +173,15 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
                 if (isGzipInput) {
                     const gzBytes = await fs.readFile(resolved);
                     const gzHeaders = {
-                        "X-Dataset-Name": name,
+                        "X-Dataset-Name": encodeHeaderValue(name),
                         "Content-Type": uploadContentType,
                         "Content-Encoding": "gzip",
                         "Idempotency-Key": createHash("sha256").update(`${name}\n`).update(gzBytes).digest("hex"),
                     };
                     if (description !== undefined)
-                        gzHeaders["X-Dataset-Description"] = description;
+                        gzHeaders["X-Dataset-Description"] = encodeHeaderValue(description);
                     if (tags !== undefined)
-                        gzHeaders["X-Dataset-Tags"] = JSON.stringify(tags);
+                        gzHeaders["X-Dataset-Tags"] = encodeHeaderValue(JSON.stringify(tags));
                     const data = await awaitDatasetStageIfNeeded((await apiCall("POST", "/v1/datasets", gzBytes, gzHeaders, UPLOAD_DATASET_TIMEOUT_MS)));
                     const gid = data.id ?? data.dataset_id;
                     if (gid != null) {
@@ -195,14 +199,14 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
             }
             const GZIP_THRESHOLD = 1024 * 1024;
             const uploadHeaders = {
-                "X-Dataset-Name": name,
+                "X-Dataset-Name": encodeHeaderValue(name),
                 "Content-Type": uploadContentType,
                 "Idempotency-Key": createHash("sha256").update(`${name}\n`).update(body).digest("hex"),
             };
             if (description !== undefined)
-                uploadHeaders["X-Dataset-Description"] = description;
+                uploadHeaders["X-Dataset-Description"] = encodeHeaderValue(description);
             if (tags !== undefined)
-                uploadHeaders["X-Dataset-Tags"] = JSON.stringify(tags);
+                uploadHeaders["X-Dataset-Tags"] = encodeHeaderValue(JSON.stringify(tags));
             let uploadBody = body;
             if (Buffer.byteLength(body, "utf-8") > GZIP_THRESHOLD) {
                 uploadBody = gzipSync(Buffer.from(body, "utf-8"));

package/dist/tools/guide.js

@@ -3,27 +3,12 @@ import { apiCall, probeApiHealth, structuredTextResult, textResult } from "../sh
 import { listDeferredFeedback } from "../deferred_feedback.js";
 const OFFLINE_GUIDE = `Mesh analysis API temporarily unavailable — figures already on disk stay available; new jobs/feedback will wait.
 
-barmesh offline summary (demo-safe): keep reviewing the last good distances, GCI CSV, and downloaded figures. Say the API is unavailable plainly; the proxy already burst-retried (~3×2s) — wait ~30s before another round. Do not treat the session as failed.
+Say the API is unavailable plainly; the proxy already burst-retried (~3×2s) — wait ~30s before another round. Keep reviewing the last good distances/figures; do not treat the session as failed.
 
-Two tracks (when API returns):
-- barmesh_mesh_convergence — SOM volume-fingerprint distances (symmetric KL + Wasserstein-1 vs reference and stepwise)
-- barmesh_richardson — classical Richardson / GCI on scalar QoIs (one mesh family per CSV: uniform OR graded, not mixed)
+When reconnecting (BARIVIA_API_KEY / BARIVIA_API_URL), call barmesh_guide_workflow again for the plan-scoped workflow.`;
+const OFFLINE_PREP = `API unreachable — cannot load the CFD mesh-prep recipe.
 
-Workflow (when API returns):
-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
-   - Multi-topology cavity studies: pass mesh_order interleaved (U20,G20,U40,G40,…) or preset=cavity
-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 (mesh_convergence) or richardson_gci.csv summary (Richardson)
-
-(Set BARIVIA_API_KEY / BARIVIA_API_URL when reconnecting.)`;
-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.
-- keep the SAME feature columns across every mesh; pick the finest mesh as the reference.
-- multi-topology (U + G): pass mesh_order coarse→fine interleaved by refinement (U20,G20,U40,G40,U80,G80,U160,G160) or use preset=cavity.
-Then: barmesh_datasets(upload) -> barmesh_mesh_convergence. (Set BARIVIA_API_KEY / BARIVIA_API_URL.)`;
+Retry when BARIVIA_API_KEY / BARIVIA_API_URL reconnect, then call barmesh_prepare_mesh_data again (entitlement-scoped).`;
 export function registerGuideTool(server) {
     registerAuditedTool(server, "barmesh_guide_workflow", `Get the barmesh CFD mesh-convergence workflow and tool map from the API (tier-scoped).
 
@@ -49,7 +34,7 @@ UNAVAILABLE: If the API is down, this tool returns a calm offline summary — sa
 
 BEST FOR: Before barmesh_datasets(upload) — tells you which physical channels to extract, how to label meshes (mesh_id), the cell-volume column (V), and how to pick the reference mesh.
 NOT FOR: Submitting jobs — after preparing the CSV, use barmesh_datasets(upload) then barmesh_mesh_convergence.
-COMMON MISTAKES: forgetting the per-cell cell-volume column; using different channels across meshes; not log-compressing turbulence quantities (k, epsilon, omega); multi-topology U+G studies without mesh_order (use interleaved U20,G20,U40,G40,… or preset=cavity).`, {}, async () => {
+COMMON MISTAKES: missing volume column; mismatched channels across meshes; multi-topology order issues — full recipe is in the API response when entitled.`, {}, async () => {
         try {
             const data = (await apiCall("GET", "/v1/cfd/prep"));
             return textResult({ recipe: data.recipe, entitled: data.entitled });

package/dist/tools/jobs.js

@@ -15,18 +15,19 @@ export function registerJobsTool(server) {
 | status | One-shot progress check |
 | list | Slim recent jobs (filter/page with limit/cursor/status/job_type/has_results) |
 | update | Edit label / description / tags |
+| delete | Permanently remove a job and its result files |
 | inventory | Markdown overview of datasets + recent jobs |
 
-BEST FOR: action=monitor after submit (one call, throttled snapshots — preferred for agents). action=status for a single one-shot check. action=inventory for a durable org catalog.
+BEST FOR: action=monitor after submit (one call, throttled snapshots — preferred for agents). action=status for a single one-shot check. action=inventory for a durable org catalog. action=delete for cleanup by known job_id (do not deep-page list to find IDs).
 MONITOR MODES: barmesh_training_monitor — default visual MCP App (live curves, post-hoc review on completed jobs). barmesh_jobs(action=monitor) — headless blocking snapshots for agents (live or post-hoc review; attaches learning_curve.png when already completed).
 ASYNC PROTOCOL: monitor blocks server-side until completed/failed or block_until timeout (default ${DEFAULT_BLOCK_UNTIL_SEC}s, poll every ${DEFAULT_POLL_INTERVAL_SEC}s). status is one-shot; poll every 10-20s manually if not using monitor. When status=completed, call barmesh_results(action=get, job_id=...) then barmesh_results_explorer(job_id=...).
 LIST: slim by default (label,id,status,job_type,dataset_id,created_at,result_ref,description,tags — no fat params). has_results=true is the results catalog.
 ESCALATION: status=failed returns an error message and (when available) a failure_stage; read it before retrying.
 UNAVAILABLE: If the mesh analysis API is temporarily unavailable, say so plainly, pause (proxy already burst-retried; wait ~retry_after_sec), and keep reviewing the last good distances/figures — do not treat the demo as failed. Suggest retry later.`, {
         action: z
-            .enum(["status", "monitor", "list", "update", "inventory"])
-            .describe("status: one-shot check; monitor: block until terminal; list: slim paginated jobs; update: metadata; inventory: datasets+jobs overview"),
-        job_id: z.string().optional().describe("Job ID (required for status, monitor, update)"),
+            .enum(["status", "monitor", "list", "update", "delete", "inventory"])
+            .describe("status: one-shot check; monitor: block until terminal; list: slim paginated jobs; update: metadata; delete: remove job+results; inventory: datasets+jobs overview"),
+        job_id: z.string().optional().describe("Job ID (required for status, monitor, update, delete)"),
         block_until_sec: z
             .number()
             .int()
@@ -123,6 +124,12 @@ UNAVAILABLE: If the mesh analysis API is temporarily unavailable, say so plainly
             const data = await apiCall("PATCH", `/v1/jobs/${job_id}`, body);
             return textResult(data);
         }
+        if (action === "delete") {
+            if (!job_id)
+                throw new Error("barmesh_jobs(delete) requires job_id.");
+            const data = await apiCall("DELETE", `/v1/jobs/${job_id}`);
+            return textResult(data);
+        }
         if (action === "inventory") {
             const jobLimit = limit && limit > 0 ? Math.min(Math.floor(limit), 100) : 50;
             const [datasetsRaw, jobsRaw] = await Promise.all([

package/dist/tools/results.js

@@ -235,7 +235,8 @@ NOT FOR: Submitting jobs.`, {
             }
             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, "_");
+            const prefix = isRichardsonJob(summary) ? "cfd_richardson" : "cfd_mesh_convergence";
+            const jobSubfolder = `${prefix}_${jobLabel ?? job_id}`.replace(/[^a-zA-Z0-9_.-]/g, "_");
             resolvedDir = path.join(resolvedDir, jobSubfolder);
             await fs.mkdir(resolvedDir, { recursive: true });
             const saved = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barivia/barmesh-mcp",
-  "version": "0.8.7",
+  "version": "0.8.9",
   "description": "barmesh MCP proxy — SOM-based CFD mesh-convergence and Richardson/GCI analysis on the Barivia cloud API",
   "keywords": [
     "mcp",