@barivia/barmesh-mcp 0.8.4 → 0.8.8

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 s}from"@modelcontextprotocol/sdk/server/stdio.js";import{getUiCapability as r,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 j}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- Cleanup: `barmesh_jobs(action=delete, job_id=…)` + `barmesh_datasets(action=delete)` for known IDs — do not deep-page list to find them.\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),j(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 I=a.server;I.oninitialized=()=>{const e=I.getClientCapabilities(),s=r(e);h(!!s?.mimeTypes?.includes(o))};const k=new s;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)});

package/dist/job_monitor.js

@@ -35,14 +35,25 @@ function tailOrderingErrors(data, n = 4) {
 export function snapshotFromJob(data, elapsedSec, note) {
     const status = String(data.status ?? "unknown");
     const progress_pct = (data.progress ?? 0) * 100;
+    const kernelComplete = data.kernel_complete === true;
+    const awaitingFinalize = kernelComplete &&
+        status !== "completed" &&
+        status !== "failed" &&
+        status !== "cancelled";
     const snap = {
         elapsed_sec: elapsedSec,
         status,
-        progress_pct: Math.round(progress_pct * 10) / 10,
+        progress_pct: awaitingFinalize
+            ? Math.min(Math.round(progress_pct * 10) / 10, 99.0)
+            : Math.round(progress_pct * 10) / 10,
     };
     const phase = str(data, "progress_phase");
-    if (phase)
+    if (awaitingFinalize) {
+        snap.phase = phase && phase !== "complete" ? `${phase}+awaiting_finalize` : "awaiting_finalize";
+    }
+    else if (phase) {
         snap.phase = phase;
+    }
     const epoch = num(data, "epoch");
     const total = num(data, "total_epochs");
     if (epoch != null)
@@ -58,7 +69,7 @@ export function snapshotFromJob(data, elapsedSec, note) {
     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)
+    if (kernelComplete)
         snap.kernel_complete = true;
     const failureStage = str(data, "failure_stage");
     if (failureStage)
@@ -69,8 +80,12 @@ export function snapshotFromJob(data, elapsedSec, note) {
     const tail = tailOrderingErrors(data);
     if (tail && tail.length > 0)
         snap.ordering_errors_tail = tail;
-    if (note)
+    if (note) {
         snap.note = note;
+    }
+    else if (awaitingFinalize) {
+        snap.note = "kernel complete — awaiting finalize (not fully done)";
+    }
     return snap;
 }
 /** True when a new snapshot is worth recording (phase/epoch/progress/status change). */
@@ -96,7 +111,10 @@ export function shouldRecordSnapshot(prev, next) {
     return false;
 }
 export function formatSnapshotLine(s) {
-    const parts = [`[+${s.elapsed_sec}s] ${s.status} ${s.progress_pct.toFixed(1)}%`];
+    const progressLabel = s.kernel_complete && s.status !== "completed" && s.status !== "failed" && s.status !== "cancelled"
+        ? `kernel ${s.progress_pct.toFixed(1)}% (awaiting finalize)`
+        : `${s.progress_pct.toFixed(1)}%`;
+    const parts = [`[+${s.elapsed_sec}s] ${s.status} ${progressLabel}`];
     if (s.phase)
         parts.push(`phase ${s.phase}`);
     if (s.epoch != null && s.total_epochs != null)
@@ -107,8 +125,9 @@ export function formatSnapshotLine(s) {
         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)
+    if (s.kernel_complete && (s.status === "completed" || s.status === "failed" || s.status === "cancelled")) {
         parts.push("kernel complete");
+    }
     if (s.failure_stage)
         parts.push(`failure_stage ${s.failure_stage}`);
     if (s.eta_sec != null)

package/dist/job_status_format.js

@@ -42,7 +42,12 @@ export async function formatJobStatusText(job_id, data) {
     const runConfig = formatRunConfigTable(data);
     if (runConfig)
         parts.push(runConfig);
-    parts.push(`${jobDesc}: ${status} (${progress.toFixed(1)}%)`);
+    const kernelComplete = data.kernel_complete === true;
+    const awaitingFinalize = kernelComplete && status !== "completed" && status !== "failed" && status !== "cancelled";
+    const progressBit = awaitingFinalize
+        ? `kernel ${Math.min(progress, 99).toFixed(1)}% — awaiting finalize`
+        : `${progress.toFixed(1)}%`;
+    parts.push(`${jobDesc}: ${status} (${progressBit})`);
     const attempt = data.attempt != null ? Number(data.attempt) : null;
     if (attempt != null && attempt > 1) {
         parts.push(`attempt ${attempt} (job was requeued after worker timeout — not stuck from scratch)`);

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.4";
+export const CLIENT_VERSION = "0.8.8";
 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;
@@ -45,6 +45,94 @@ 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
+/** Normalize upload JSON after staging completes — never leave staging:true with train_ready. */
+function finalizeStagedUploadResponse(data, ready) {
+    const merged = ready
+        ? { ...data, ...ready }
+        : { ...data };
+    const trainReady = merged.train_ready === true || String(merged.status ?? "") === "ready";
+    if (trainReady) {
+        merged.status = ready?.status ?? merged.status ?? "ready";
+        merged.train_ready = true;
+        merged.staging = false;
+        if (ready?.stage_job_id == null)
+            delete merged.stage_job_id;
+    }
+    return merged;
+}
+/**
+ * After a small POST /v1/datasets upload, poll stage_job_id until the dataset is
+ * train-ready (mirrors the large-upload finalize path).
+ */
+export async function awaitDatasetStageIfNeeded(data) {
+    const stageJobId = data.stage_job_id != null ? String(data.stage_job_id) : "";
+    if (!stageJobId) {
+        if (data.train_ready === true || data.status === "ready") {
+            return finalizeStagedUploadResponse(data);
+        }
+        return data;
+    }
+    if (data.train_ready === true || data.status === "ready") {
+        return finalizeStagedUploadResponse(data);
+    }
+    const poll = await pollUntilComplete(stageJobId, POLL_STAGE_MAX_MS);
+    if (poll.status === "failed") {
+        throw new Error(`Dataset staging failed (stage_job_id=${stageJobId}): ${poll.error ?? "unknown error"}`);
+    }
+    if (poll.status === "timeout") {
+        throw new Error(`Dataset staging timed out after ${POLL_STAGE_MAX_MS / 60000} min (stage_job_id=${stageJobId}). Poll barmesh_jobs(action=status, job_id="${stageJobId}").`);
+    }
+    const datasetId = String(data.id ?? data.dataset_id ?? "");
+    if (datasetId) {
+        try {
+            const ready = (await apiCall("GET", `/v1/datasets/${datasetId}`));
+            return finalizeStagedUploadResponse(data, ready);
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    return finalizeStagedUploadResponse({ ...data, status: "ready", train_ready: true });
+}
+/**
+ * Before mesh_convergence submit: ensure the dataset has finished staging.
+ */
+export async function ensureDatasetTrainReady(datasetId) {
+    const ds = (await apiCall("GET", `/v1/datasets/${datasetId}`));
+    if (ds.train_ready === true)
+        return;
+    if (String(ds.status) === "failed") {
+        const err = ds.ingest_error != null ? String(ds.ingest_error) : "staging failed";
+        throw new Error(`Dataset ${datasetId} staging failed: ${err}`);
+    }
+    const stageJobId = ds.stage_job_id != null ? String(ds.stage_job_id) : "";
+    if (stageJobId) {
+        const poll = await pollUntilComplete(stageJobId, POLL_STAGE_MAX_MS);
+        if (poll.status === "failed") {
+            throw new Error(`Dataset staging failed (stage_job_id=${stageJobId}): ${poll.error ?? "unknown error"}`);
+        }
+        if (poll.status === "timeout") {
+            throw new Error(`Dataset staging timed out (stage_job_id=${stageJobId}). Poll barmesh_jobs(action=status, job_id="${stageJobId}").`);
+        }
+        return;
+    }
+    const deadline = Date.now() + 60_000;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 1000));
+        const again = (await apiCall("GET", `/v1/datasets/${datasetId}`));
+        if (again.train_ready === true)
+            return;
+        if (String(again.status) === "failed") {
+            const err = again.ingest_error != null ? String(again.ingest_error) : "staging failed";
+            throw new Error(`Dataset ${datasetId} staging failed: ${err}`);
+        }
+        if (again.stage_job_id != null) {
+            await ensureDatasetTrainReady(datasetId);
+            return;
+        }
+    }
+    throw new Error(`Dataset ${datasetId} is not train_ready (status=${ds.status ?? "?"}). Wait for staging or poll barmesh_datasets(action=get).`);
+}
 /** Map a local upload path to the API Content-Type (csv vs tsv; ignores .gz suffix). */
 export function resolveUploadContentType(filePath) {
     const lower = filePath.toLowerCase();
@@ -261,9 +349,48 @@ function enforceWorkspaceSandboxUpload() {
         return false;
     return true;
 }
+/** Extra realpath roots allowed for uploads (comma- or colon-separated absolute paths). */
+export function getWorkspaceExtraRoots() {
+    const raw = process.env.BARIVIA_WORKSPACE_EXTRA_ROOTS ?? "";
+    if (!raw.trim())
+        return [];
+    return raw
+        .split(/[,:]/)
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((s) => path.resolve(s));
+}
+async function realpathIfExists(p) {
+    try {
+        return await fs.realpath(p);
+    }
+    catch {
+        return null;
+    }
+}
+export async function isPathUnderSandboxRoots(realPath, workspaceRoot) {
+    const candidates = [workspaceRoot, ...getWorkspaceExtraRoots()];
+    for (const root of candidates) {
+        const realRoot = await realpathIfExists(root);
+        if (!realRoot)
+            continue;
+        if (realPath === realRoot || realPath.startsWith(realRoot + path.sep))
+            return true;
+    }
+    return false;
+}
+function sandboxEscapeError(realPath, workspaceRoot) {
+    const extras = getWorkspaceExtraRoots();
+    const extraHint = extras.length > 0
+        ? ` Also checked BARIVIA_WORKSPACE_EXTRA_ROOTS (${extras.join(", ")}).`
+        : " Set BARIVIA_WORKSPACE_EXTRA_ROOTS to allow shared fixture dirs, or copy the file into the workspace.";
+    return new Error(`Resolved path escapes workspace — symlink resolves outside BARIVIA_WORKSPACE_ROOT` +
+        ` (${workspaceRoot}). Target: ${realPath}.${extraHint}`);
+}
 /**
  * Resolve file_path for dataset upload. Rejects "..", enforces workspace sandbox
  * by default (set BARIVIA_ENFORCE_WORKSPACE_SANDBOX=0 to allow absolute paths).
+ * Symlink targets under BARIVIA_WORKSPACE_EXTRA_ROOTS are allowed when sandbox is on.
  */
 export async function resolveFilePathForUpload(filePath, mcpServer) {
     const trimmed = filePath.trim();
@@ -272,9 +399,8 @@ export async function resolveFilePathForUpload(filePath, mcpServer) {
     const checkUnder = async (p) => {
         const root = await getWorkspaceRootAsync(mcpServer);
         const real = await fs.realpath(p);
-        const realRoot = await fs.realpath(root);
-        if (real !== realRoot && !real.startsWith(realRoot + path.sep)) {
-            throw new Error(`Path outside the workspace is disabled (BARIVIA_ENFORCE_WORKSPACE_SANDBOX). Workspace root: ${realRoot}`);
+        if (!(await isPathUnderSandboxRoots(real, root))) {
+            throw sandboxEscapeError(real, root);
         }
         const stat = await fs.stat(real);
         if (!stat.isFile())
@@ -294,6 +420,9 @@ export async function resolveFilePathForUpload(filePath, mcpServer) {
     }
     const root = await getWorkspaceRootAsync(mcpServer);
     const resolved = path.resolve(root, trimmed);
+    if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+        throw new Error("Path must be within the workspace directory.");
+    }
     return checkUnder(resolved);
 }
 function looksLikeHtml(bodyText) {
@@ -357,7 +486,15 @@ export function classifyApiError(status, bodyText, requestId) {
     }
     else if (status === 409) {
         cause = "client";
-        hint = "The job may not be in the expected state.";
+        if (apiCode === "staging_not_ready") {
+            const stageId = parsed?.stage_job_id != null ? String(parsed.stage_job_id) : "";
+            hint = stageId
+                ? `Wait for stage_dataset to finish: barmesh_jobs(action=monitor, job_id="${stageId}"), then retry. Prefer barmesh_datasets(action=get) train_ready=true.`
+                : "Wait for dataset staging (status=ready with staged_prefix / train_ready=true), then retry.";
+        }
+        else {
+            hint = "The job may not be in the expected state.";
+        }
         retryable = false;
     }
     else if (status === 429) {
@@ -685,20 +822,65 @@ export function textResult(data) {
 }
 export async function pollUntilComplete(jobId, maxWaitMs = 30_000, intervalMs = 2000) {
     const start = Date.now();
+    /** Brief 404s happen when finalize_job_id is visible before the child row is readable. */
+    let notFoundStreak = 0;
+    const maxNotFoundRetries = 5;
     while (Date.now() - start < maxWaitMs) {
-        const data = (await apiCall("GET", `/v1/jobs/${jobId}`));
-        const status = data.status;
-        if (status === "completed" || status === "failed" || status === "cancelled") {
-            return {
-                status,
-                result_ref: data.result_ref,
-                error: data.error,
-            };
+        try {
+            const data = (await apiCall("GET", `/v1/jobs/${jobId}`));
+            notFoundStreak = 0;
+            const status = data.status;
+            if (status === "completed" || status === "failed" || status === "cancelled") {
+                return {
+                    status,
+                    result_ref: data.result_ref,
+                    error: data.error,
+                };
+            }
+        }
+        catch (err) {
+            const status = err?.httpStatus;
+            if (status === 404 && notFoundStreak < maxNotFoundRetries) {
+                notFoundStreak += 1;
+                await new Promise((r) => setTimeout(r, intervalMs));
+                continue;
+            }
+            throw err;
         }
         await new Promise((r) => setTimeout(r, intervalMs));
     }
     return { status: "timeout" };
 }
+const RESULTS_FIGURE_ENUMS = new Set(["default", "all", "none"]);
+/**
+ * Coerce host-stringified figures args (e.g. `'["all"]'`) and singleton enum arrays
+ * (`["all"]` → `"all"`) before Zod validation.
+ */
+export function coerceFiguresArg(v) {
+    if (v === undefined || v === null)
+        return v;
+    let val = v;
+    if (typeof val === "string") {
+        const trimmed = val.trim();
+        if ((trimmed.startsWith("[") && trimmed.endsWith("]")) ||
+            (trimmed.startsWith('"') && trimmed.endsWith('"'))) {
+            try {
+                val = JSON.parse(trimmed);
+            }
+            catch {
+                return v;
+            }
+        }
+    }
+    if (Array.isArray(val)) {
+        const asStrings = val.map((x) => String(x));
+        if (asStrings.length === 1 && RESULTS_FIGURE_ENUMS.has(asStrings[0])) {
+            return asStrings[0];
+        }
+        return asStrings;
+    }
+    return val;
+}
 // ---------------------------------------------------------------------------
 // Image helpers
 // ---------------------------------------------------------------------------

package/dist/tools/cfd.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
-import { apiCall, textResult, suggestAfterCfdSubmit } from "../shared.js";
+import { apiCall, ensureDatasetTrainReady, 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.
@@ -53,6 +53,7 @@ COMMON MISTAKES: omitting feature_columns (required); choosing a reference_mesh
             body.description = description;
         if (tags !== undefined)
             body.tags = tags;
+        await ensureDatasetTrainReady(String(dataset_id));
         const data = (await apiCall("POST", "/v1/cfd/mesh-convergence", body));
         await pollCfdPrepareIfPresent(data, "barmesh_mesh_convergence");
         const id = data.id;

package/dist/tools/datasets.js

@@ -4,9 +4,13 @@ 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, resolveUploadContentType, suggestMeshDatasetPreview, } from "../shared.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,16 +173,16 @@ 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);
-                    const data = (await apiCall("POST", "/v1/datasets", gzBytes, gzHeaders, UPLOAD_DATASET_TIMEOUT_MS));
+                        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) {
                         data.suggested_next_step = suggestMeshDatasetPreview(String(gid));
@@ -195,20 +199,20 @@ 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"));
                 uploadHeaders["Content-Encoding"] = "gzip";
             }
-            const data = (await apiCall("POST", "/v1/datasets", uploadBody, uploadHeaders, UPLOAD_DATASET_TIMEOUT_MS));
+            const data = await awaitDatasetStageIfNeeded((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 = suggestMeshDatasetPreview(String(id));
@@ -259,16 +263,20 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
                 throw new Error("barmesh_datasets(get) requires dataset_id.");
             const ds = (await apiCall("GET", `/v1/datasets/${dataset_id}`));
             const tagStr = formatTags(ds.tags);
+            const trainReady = ds.train_ready === true;
             const lines = [
                 `Dataset: ${ds.name ?? "?"} (${ds.id ?? dataset_id})`,
-                `Status: ${ds.status ?? "ready"}`,
+                `Status: ${ds.status ?? "unknown"}`,
+                `Train ready: ${trainReady ? "yes" : "no"}`,
                 `Rows × cols: ${ds.rows ?? "?"} × ${ds.cols ?? "?"}`,
                 ds.size_bytes != null ? `Size: ${Number(ds.size_bytes).toLocaleString()} bytes` : "",
                 ds.description != null && String(ds.description).trim() !== "" ? `Description: ${String(ds.description)}` : "",
                 tagStr ? `Tags: ${tagStr}` : "",
                 ds.staged_prefix != null ? `Staged prefix: ${String(ds.staged_prefix)}` : "",
                 ds.staged_version != null ? `Staged version: ${String(ds.staged_version)}` : "",
-                ds.stage_job_id != null ? `Stage job: ${String(ds.stage_job_id)} (poll barmesh_jobs(action=status))` : "",
+                !trainReady && ds.stage_job_id != null
+                    ? `Stage job: ${String(ds.stage_job_id)} (poll barmesh_jobs(action=status) until train_ready)`
+                    : "",
                 cleanNullable(ds.ingest_error) ? `Ingest error: ${cleanNullable(ds.ingest_error)}` : "",
                 ds.created_at != null ? `Created: ${String(ds.created_at)}` : "",
             ].filter(Boolean);

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

@@ -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, suggestAfterRender, } from "../shared.js";
+import { apiCall, apiRawCall, getWorkspaceRootAsync, sandboxPath, textResult, tryAttachImage, resetInlineAttachBudget, pollUntilComplete, POLL_STAGE_MAX_MS, suggestAfterRender, coerceFiguresArg, } from "../shared.js";
 import { formatConvergenceReading } from "../convergence_reading.js";
 import { formatRichardsonResultsSummary, isRichardsonJob } from "../richardson_results.js";
 const MESH_DEFAULT_FIGURES = ["combined", "overview_distances", "plot_vol_all_meshes", "plot_vol_steps", "learning_curve"];
@@ -73,7 +73,7 @@ export function registerResultsTool(server) {
 | feature_divergences | Refresh feature-plane KL matrices / optional Wasserstein on SOM component planes (async; not mesh fingerprint KL). |
 
 BEST FOR: After barmesh_jobs(action=status) shows completed (and finalize finished if defer_figures was used).
-FIGURES: Default bundle is combined.png, overview_distances.png (all KL/EMD panels), plot_vol_all_meshes.png, plot_vol_steps.png, and learning_curve.png — not redundant per-feature PNGs or divergence_kl. action=get inlines the headline set; pass figures="all" for every artifact listed in summary.files, figures="none" for metrics only (recommended for agents).
+FIGURES: Default bundle is combined.png, overview_distances.png (all KL/EMD panels), plot_vol_all_meshes.png, plot_vol_steps.png, and learning_curve.png — not redundant per-feature PNGs or divergence_kl. Prefer string figures="all" / "none" (not an array); arrays are for specific base names or filenames. Hosts that stringify arrays are coerced. action=get inlines the headline set; pass figures="all" for every artifact listed in summary.files, figures="none" for metrics only (recommended for agents).
 FEATURE-PLANE KL: mesh SKL/EMD (KL_ref, EMD_*) compare meshes; divergence_kl / feature_divergences.json compare SOM component planes (barsom-parallel). Finalize already writes symmetric KL; use action=feature_divergences for W1 or a refresh.
 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.
@@ -85,10 +85,10 @@ NOT FOR: Submitting jobs.`, {
         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
+        figures: z.preprocess(coerceFiguresArg, z
             .union([z.enum(["default", "all", "none"]), z.array(z.string())])
             .optional()
-            .describe("For action=get/download: which figures (default headline panels; 'all'; 'none'; or a list of base names)"),
+            .describe("Prefer string 'all'/'none'. get/download: omit=headline panels; 'all'; 'none'; or array of base names/filenames. Stringified JSON arrays from hosts are accepted.")),
         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"),
         metrics: z
@@ -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.4",
+  "version": "0.8.8",
   "description": "barmesh MCP proxy — SOM-based CFD mesh-convergence and Richardson/GCI analysis on the Barivia cloud API",
   "keywords": [
     "mcp",