@barivia/barmesh-mcp 0.5.2 → 0.5.3

package/README.md

@@ -55,7 +55,8 @@ API key; otherwise the analysis calls return HTTP 403. Contact Barivia to enable
 | `barmesh_datasets` | Upload / preview / list / get / subset / delete the mesh CSV. |
 | `barmesh_mesh_convergence` | SOM fingerprint distances (async job). |
 | `barmesh_richardson` | Richardson/GCI on scalar QoIs (async job). |
-| `barmesh_jobs` | Poll job status / list jobs (auto-polls CFD prepare + finalize when applicable). Reports phase, epoch/total, elapsed, ETA, and QE live during the SOM training. |
+| `barmesh_jobs` | Poll job status / block until terminal (`action=monitor`) / list jobs. Auto-polls CFD prepare + finalize when applicable. Reports phase, epoch/total, elapsed, ETA, and QE live during the SOM training. |
+| `barmesh_training_monitor` | Alias for `barmesh_jobs(action=monitor)` — server-side poll with throttled snapshots until terminal (preferred after submit). |
 | `barmesh_results` | Distances, convergence reading, and figures. `action=get` inlines headline PNGs; `action=download` saves artifacts to disk; `action=render` produces publication PDFs on demand. |
 | `barmesh_results_explorer` | Interactive MCP App with a **figure dropdown above the plot** (or standalone localhost page) to browse every figure after a job completes. |
 | `barmesh_send_feedback` | Send a short note or bug report to the Barivia team. |
@@ -76,11 +77,14 @@ API key; otherwise the analysis calls return HTTP 403. Contact Barivia to enable
   figures). PNG previews inline; PDF/SVG offered for download when rendered.
 - **Uploads:** large CSVs use presigned PUT with explicit `Content-Length`; `.csv.gz` /
   `.tsv.gz` accepted. Pin `@barivia/barmesh-mcp@0.5.2` (clear `~/.npm/_npx` if stale).
-- **Live progress:** `barmesh_jobs(action=status)` exposes phase, epoch/total, elapsed,
-  ETA, QE during SOM training, plus cfd_finalize sub-status when figures are deferred.
+- **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
+  terminal or `block_until_sec` (default 900). Waits for `cfd_finalize` by default. One-shot:
+  `barmesh_jobs(action=status)`.
 
 ### Migration notes
 
+- **`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.
 
 ## Data format (mesh_convergence)

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 o,RESOURCE_MIME_TYPE as n}from"@modelcontextprotocol/ext-apps/server";import{startVizServer as t}from"./viz-server.js";import{API_KEY as i,CLIENT_VERSION as a,apiCall as c,apiRawCall as m,loadViewHtml as l,setVizPort as d,setClientSupportsMcpApps as p}from"./shared.js";import{registerGuideTool as h}from"./tools/guide.js";import{registerDatasetsTool as u}from"./tools/datasets.js";import{registerCfdTools as f}from"./tools/cfd.js";import{registerJobsTool as b}from"./tools/jobs.js";import{registerResultsTool as v}from"./tools/results.js";import{registerResultsExplorerTool as y,RESULTS_EXPLORER_URI as _}from"./tools/barmesh_results_explorer.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\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.\n4. barmesh_mesh_convergence (and/or barmesh_richardson) — returns a job id.\n5. barmesh_jobs(action=status) — poll every 10-20s, for minutes if needed.\n6. barmesh_results(action=get) — distances, convergence reading, and figures; then\n   barmesh_results_explorer(job_id) to browse every figure interactively.\n\nThese tools are gated by the 'cfd' entitlement; analysis calls return 403 if your plan\ndoes not include it."});o(i,_,_,{mimeType:n},async()=>{const e=await l("barmesh-results-explorer");return{contents:[{uri:_,mimeType:n,text:e??"<html><body>Results Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),h(i),y(i),u(i),f(i),b(i),v(i),g(i);try{const e=await t(c,m,l);d(e)}catch(e){process.env.BARIVIA_VIZ_PORT&&console.error("barmesh viz server failed to start:",e)}const w=i.server;w.oninitialized=()=>{const e=w.getClientCapabilities(),r=s(e);p(!!r?.mimeTypes?.includes(n))};const j=new r;await i.connect(j),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)});
+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 o,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 c,apiRawCall as m,loadViewHtml as l,setVizPort as d,setClientSupportsMcpApps as h}from"./shared.js";import{registerGuideTool as p}from"./tools/guide.js";import{registerDatasetsTool as b}from"./tools/datasets.js";import{registerCfdTools as f}from"./tools/cfd.js";import{registerJobsTool as u}from"./tools/jobs.js";import{registerResultsTool as _}from"./tools/results.js";import{registerResultsExplorerTool as v,RESULTS_EXPLORER_URI as g}from"./tools/barmesh_results_explorer.js";import{registerTrainingMonitorTool as y}from"./tools/training_monitor.js";import{registerFeedbackTool as j}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\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.\n4. barmesh_mesh_convergence (and/or barmesh_richardson) — returns a job id.\n5. barmesh_training_monitor(job_id) or barmesh_jobs(action=monitor) — blocks with throttled snapshots until done (preferred); 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\nThese tools are gated by the 'cfd' entitlement; analysis calls return 403 if your plan\ndoes not include it."});o(i,g,g,{mimeType:t},async()=>{const e=await l("barmesh-results-explorer");return{contents:[{uri:g,mimeType:t,text:e??"<html><body>Results Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),p(i),v(i),b(i),f(i),u(i),y(i),_(i),j(i);try{const e=await n(c,m,l);d(e)}catch(e){process.env.BARIVIA_VIZ_PORT&&console.error("barmesh viz server failed to start:",e)}const w=i.server;w.oninitialized=()=>{const e=w.getClientCapabilities(),r=s(e);h(!!r?.mimeTypes?.includes(t))};const x=new r;await i.connect(x),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/job_monitor.js

@@ -0,0 +1,208 @@
+/**
+ * Server-side job monitor for barmesh async workflows.
+ * Polls GET /v1/jobs/:id until terminal (or block_until timeout) and emits
+ * compact throttled snapshots so agents avoid manual status poll loops.
+ */
+import { apiCall } from "./shared.js";
+import { formatJobStatusText } from "./job_status_format.js";
+import { pollCfdFinalizeIfPresent, refreshJobAfterFinalize } from "./cfd_finalize.js";
+export const DEFAULT_BLOCK_UNTIL_SEC = 900;
+export const DEFAULT_POLL_INTERVAL_SEC = 5;
+export const MIN_POLL_INTERVAL_SEC = 5;
+export const HEARTBEAT_POLLS = 1;
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+function num(data, key) {
+    const v = data[key];
+    if (v == null || Number.isNaN(Number(v)))
+        return undefined;
+    return Number(v);
+}
+function str(data, key) {
+    const v = data[key];
+    if (v == null || String(v) === "")
+        return undefined;
+    return String(v);
+}
+function tailOrderingErrors(data, n = 4) {
+    const raw = data.ordering_errors;
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    return raw.slice(-n).map((x) => Number(x)).filter((x) => !Number.isNaN(x));
+}
+export function snapshotFromJob(data, elapsedSec, note) {
+    const status = String(data.status ?? "unknown");
+    const progress_pct = (data.progress ?? 0) * 100;
+    const snap = {
+        elapsed_sec: elapsedSec,
+        status,
+        progress_pct: Math.round(progress_pct * 10) / 10,
+    };
+    const phase = str(data, "progress_phase");
+    if (phase)
+        snap.phase = phase;
+    const epoch = num(data, "epoch");
+    const total = num(data, "total_epochs");
+    if (epoch != null)
+        snap.epoch = epoch;
+    if (total != null)
+        snap.total_epochs = total;
+    const qe = num(data, "quantization_error");
+    const te = num(data, "topographic_error");
+    if (qe != null)
+        snap.qe = Math.round(qe * 10_000) / 10_000;
+    if (te != null)
+        snap.te = Math.round(te * 10_000) / 10_000;
+    const eta = num(data, "training_eta_sec");
+    if (eta != null && eta > 0)
+        snap.eta_sec = Math.round(eta);
+    const tail = tailOrderingErrors(data);
+    if (tail && tail.length > 0)
+        snap.ordering_errors_tail = tail;
+    if (note)
+        snap.note = note;
+    return snap;
+}
+/** True when a new snapshot is worth recording (phase/epoch/progress/status change). */
+export function shouldRecordSnapshot(prev, next) {
+    if (!prev)
+        return true;
+    if (prev.status !== next.status)
+        return true;
+    if (next.note)
+        return true;
+    if (prev.phase !== next.phase)
+        return true;
+    if (prev.epoch !== next.epoch)
+        return true;
+    if (Math.abs(prev.progress_pct - next.progress_pct) >= 1)
+        return true;
+    if (prev.qe !== next.qe || prev.te !== next.te)
+        return true;
+    return false;
+}
+export function formatSnapshotLine(s) {
+    const parts = [`[+${s.elapsed_sec}s] ${s.status} ${s.progress_pct.toFixed(1)}%`];
+    if (s.phase)
+        parts.push(`phase ${s.phase}`);
+    if (s.epoch != null && s.total_epochs != null)
+        parts.push(`epoch ${s.epoch}/${s.total_epochs}`);
+    if (s.qe != null)
+        parts.push(`QE ${s.qe.toFixed(4)}`);
+    if (s.te != null)
+        parts.push(`TE ${s.te.toFixed(4)}`);
+    if (s.eta_sec != null)
+        parts.push(`ETA ~${s.eta_sec}s`);
+    if (s.ordering_errors_tail?.length) {
+        parts.push(`ordering_errors tail [${s.ordering_errors_tail.map((x) => x.toFixed(4)).join(", ")}]`);
+    }
+    if (s.note)
+        parts.push(s.note);
+    return parts.join(" | ");
+}
+export function formatMonitorText(result, opts) {
+    const lines = [
+        `Job ${result.job_id} monitor (block_until=${opts.block_until_sec}s, poll=${opts.poll_interval_sec}s):`,
+    ];
+    for (const s of result.snapshots)
+        lines.push(formatSnapshotLine(s));
+    lines.push("");
+    if (result.timed_out) {
+        lines.push(`Timed out before terminal state. Last status: ${result.status_text}`);
+        lines.push(`Re-run barmesh_training_monitor(job_id="${result.job_id}") or barmesh_jobs(action=monitor, job_id="${result.job_id}").`);
+    }
+    else {
+        lines.push(`Terminal: ${result.status_text}`);
+    }
+    lines.push(result.suggested_next_step);
+    return lines.join("\n");
+}
+function suggestedNextStep(job_id, data) {
+    const status = String(data.status ?? "");
+    if (status === "completed") {
+        const finalizeId = str(data, "finalize_job_id");
+        if (finalizeId) {
+            return `Compute done; cfd_finalize may still be running. Poll barmesh_jobs(status) or re-run monitor with wait_finalize=true, then barmesh_results(action=get, job_id="${job_id}").`;
+        }
+        return `Next: barmesh_results(action=get, job_id="${job_id}") or barmesh_results_explorer(job_id="${job_id}").`;
+    }
+    if (status === "failed") {
+        const stage = str(data, "failure_stage");
+        return `Job failed${stage ? ` at ${stage}` : ""}. Read the error above before retrying.`;
+    }
+    if (status === "cancelled")
+        return `Job cancelled. Confirm with barmesh_jobs(action=status, job_id="${job_id}").`;
+    return `Still running — re-run barmesh_training_monitor(job_id="${job_id}") to continue waiting.`;
+}
+async function fetchTrainingLogHint(job_id, data) {
+    const status = String(data.status ?? "");
+    if (status !== "completed" && status !== "failed")
+        return undefined;
+    try {
+        await apiCall("GET", `/v1/results/${job_id}/training-log`);
+        return `Training log available at GET /v1/results/${job_id}/training-log (learning_curve.png in results after finalize).`;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function monitorJob(job_id, options = {}) {
+    const block_until_sec = Math.max(30, options.block_until_sec ?? DEFAULT_BLOCK_UNTIL_SEC);
+    const poll_interval_sec = Math.max(MIN_POLL_INTERVAL_SEC, options.poll_interval_sec ?? DEFAULT_POLL_INTERVAL_SEC);
+    const wait_finalize = options.wait_finalize !== false;
+    const blockMs = block_until_sec * 1000;
+    const pollMs = poll_interval_sec * 1000;
+    const start = Date.now();
+    const snapshots = [];
+    let lastSnap = null;
+    let data = {};
+    let heartbeat = 0;
+    while (Date.now() - start < blockMs) {
+        data = (await apiCall("GET", `/v1/jobs/${job_id}`));
+        const elapsedSec = Math.round((Date.now() - start) / 1000);
+        const snap = snapshotFromJob(data, elapsedSec);
+        heartbeat += 1;
+        const heartbeatDue = heartbeat >= HEARTBEAT_POLLS;
+        if (shouldRecordSnapshot(lastSnap, snap) || heartbeatDue) {
+            snapshots.push(snap);
+            lastSnap = snap;
+            heartbeat = 0;
+        }
+        const status = String(data.status ?? "");
+        if (status === "completed" || status === "failed" || status === "cancelled") {
+            break;
+        }
+        await sleep(pollMs);
+    }
+    const status = String(data.status ?? "");
+    const terminal = status === "completed" || status === "failed" || status === "cancelled";
+    const timed_out = !terminal;
+    if (terminal && status === "completed" && wait_finalize && data.finalize_job_id) {
+        const finalizeId = String(data.finalize_job_id);
+        const elapsedSec = Math.round((Date.now() - start) / 1000);
+        snapshots.push(snapshotFromJob(data, elapsedSec, `cfd_finalize ${finalizeId} started — waiting for figure render`));
+        try {
+            const { note } = await pollCfdFinalizeIfPresent(job_id, data, Math.max(0, blockMs - (Date.now() - start)));
+            data = await refreshJobAfterFinalize(job_id);
+            snapshots.push(snapshotFromJob(data, Math.round((Date.now() - start) / 1000), note ?? `cfd_finalize ${finalizeId} completed`));
+        }
+        catch (err) {
+            snapshots.push(snapshotFromJob(data, Math.round((Date.now() - start) / 1000), `cfd_finalize failed: ${err.message}`));
+        }
+    }
+    const statusText = await formatJobStatusText(job_id, data);
+    const logHint = terminal ? await fetchTrainingLogHint(job_id, data) : undefined;
+    let suggested = suggestedNextStep(job_id, data);
+    if (logHint)
+        suggested += ` ${logHint}`;
+    return {
+        job_id,
+        terminal,
+        timed_out,
+        snapshots,
+        status_text: statusText,
+        data,
+        suggested_next_step: suggested,
+    };
+}

package/dist/shared.js

@@ -22,7 +22,7 @@ export const FETCH_TIMEOUT_MS = parseInt(process.env.BARIVIA_FETCH_TIMEOUT_MS ??
 export const MAX_RETRIES = 2;
 export const RETRYABLE_STATUS = new Set([502, 503, 504]);
 /** Single source of truth for the proxy version. Keep in sync with package.json on bump. */
-export const CLIENT_VERSION = "0.5.2";
+export const CLIENT_VERSION = "0.5.3";
 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

@@ -47,7 +47,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 = `Poll barmesh_jobs(action=status, job_id=${id})${prep}; on completion call barmesh_results(action=get, job_id=${id}).`;
+            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}").`;
         }
         return textResult(data);
     });
@@ -80,7 +80,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 = `Poll barmesh_jobs(action=status, job_id=${id}); on completion call barmesh_results(action=get, job_id=${id}).`;
+            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}").`;
         return textResult(data);
     });
 }

package/dist/tools/guide.js

@@ -2,7 +2,7 @@ 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_jobs(status) -> barmesh_results(get).
+Workflow: barmesh_prepare_mesh_data -> barmesh_datasets(upload) -> barmesh_mesh_convergence / barmesh_richardson -> barmesh_training_monitor (or barmesh_jobs monitor/status) -> barmesh_results(get).
 (API unreachable; this is the 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:

package/dist/tools/jobs.js

@@ -3,16 +3,41 @@ import { registerAuditedTool } from "../audit.js";
 import { apiCall, textResult } from "../shared.js";
 import { pollCfdFinalizeIfPresent, refreshJobAfterFinalize } from "../cfd_finalize.js";
 import { formatJobStatusText } from "../job_status_format.js";
+import { DEFAULT_BLOCK_UNTIL_SEC, DEFAULT_POLL_INTERVAL_SEC } from "../job_monitor.js";
+import { runMonitor } from "./training_monitor.js";
 export function registerJobsTool(server) {
-    registerAuditedTool(server, "barmesh_jobs", `Check job status or list jobs.
+    registerAuditedTool(server, "barmesh_jobs", `Check job status, block until terminal, or list jobs.
 
-BEST FOR: Polling a submitted barmesh_mesh_convergence or barmesh_richardson job until status is completed/failed.
-ASYNC PROTOCOL: Poll action=status every 10-20s. Keep polling for several minutes — datacenter-scale grids plus EMD are slow; do not give up after one poll. When status=completed, call barmesh_results(action=get, job_id=...).
+BEST FOR: action=monitor after submit (one call, throttled snapshots — preferred for agents). action=status for a single one-shot check.
+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=...).
 ESCALATION: status=failed returns an error message and (when available) a failure_stage; read it before retrying.`, {
-        action: z.enum(["status", "list"]).describe("status: check one job; list: recent jobs"),
-        job_id: z.string().optional().describe("Job ID (required for status)"),
+        action: z
+            .enum(["status", "monitor", "list"])
+            .describe("status: one-shot check; monitor: block until terminal with snapshots; list: recent jobs"),
+        job_id: z.string().optional().describe("Job ID (required for status and monitor)"),
+        block_until_sec: z
+            .number()
+            .int()
+            .min(30)
+            .optional()
+            .describe(`action=monitor only: max wait seconds (default ${DEFAULT_BLOCK_UNTIL_SEC})`),
+        poll_interval_sec: z
+            .number()
+            .int()
+            .min(5)
+            .optional()
+            .describe(`action=monitor only: poll interval (default ${DEFAULT_POLL_INTERVAL_SEC})`),
+        wait_finalize: z
+            .boolean()
+            .optional()
+            .describe("action=monitor only: wait for cfd_finalize (default true)"),
     }, async (args) => {
-        const { action, job_id } = args;
+        const { action, job_id, block_until_sec, poll_interval_sec, wait_finalize } = args;
+        if (action === "monitor") {
+            if (!job_id)
+                throw new Error("barmesh_jobs(monitor) requires job_id.");
+            return runMonitor({ job_id, block_until_sec, poll_interval_sec, wait_finalize });
+        }
         if (action === "status") {
             if (!job_id)
                 throw new Error("barmesh_jobs(status) requires job_id.");

package/dist/tools/training_monitor.js

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

package/package.json

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