@barivia/barmesh-mcp 0.7.1 → 0.8.2

package/dist/tools/datasets.js

@@ -6,6 +6,7 @@ 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 { GZIP_UPLOAD_HINT } from "../upload_hints.js";
+import { formatDatasetInventoryLine, formatTags } from "../inventory_format.js";
 /**
  * Normalize a nullable string field from the API. Returns "" for absent values,
  * empty strings, and the literal SQL/serialization sentinels "missing"/"null".
@@ -23,12 +24,14 @@ Formats: plain CSV/TSV or gzip (.csv.gz / .tsv.gz). For files above ~64 MB, pref
 
 | Action | Use when |
 |--------|----------|
-| upload | You have prepared a combined per-cell CSV (mesh_id + feature columns + cell volume V). Do this first. |
+| upload | You have prepared a combined per-cell CSV (mesh_id + feature columns + cell volume V). Do this first. Optional description/tags help inventory. |
 | preview | After upload — verify the mesh column, feature columns, and volume column are present and numeric. |
-| get | Fetch one dataset by id — status, staging fields, ingest_error (use after upload or when staging is slow). |
-| list | Find dataset IDs for analysis. |
+| get | Fetch one dataset by id — status, staging fields, ingest_error, description/tags (use after upload or when staging is slow). |
+| list | Find dataset IDs for analysis (includes description/tags). |
+| update | Edit name / description / tags on an existing dataset. |
 | subset | Shrink a huge per-cell table server-side (row_range, filters, or sample_n). |
 | delete | Remove a dataset permanently. |
+| inventory | Prefer barmesh_jobs(action=inventory) for a full datasets+jobs markdown overview. |
 
 action=upload: PREFER file_path — server reads from workspace root (token-efficient). Accepts .csv, .tsv, .csv.gz, .tsv.gz. Use csv_data only for small inline pastes (<10KB). If plain CSV exceeds the 5 GB upload cap, gzip it first (.csv.gz).
 
@@ -37,9 +40,11 @@ NOT FOR: Raw OpenFOAM case directories — extract a per-cell CSV first (see bar
 COMMON MISTAKES: omitting the cell-volume column (defaults to equal weights, which weakens the fingerprint); inconsistent feature columns across meshes.
 ESCALATION: If preview shows a feature column as non-numeric, fix the extraction and re-upload.`, {
         action: z
-            .enum(["upload", "preview", "list", "get", "subset", "delete"])
-            .describe("upload: add CSV or .csv.gz; preview: inspect columns; list: see all datasets; get: fetch one dataset metadata (status/staging); subset: create filtered subset; delete: remove dataset"),
-        name: z.string().optional().describe("Dataset name (required for upload and subset)"),
+            .enum(["upload", "preview", "list", "get", "update", "subset", "delete"])
+            .describe("upload: add CSV or .csv.gz; preview: inspect columns; list: see all datasets; get: fetch one dataset metadata (status/staging); update: edit name/description/tags; subset: create filtered subset; delete: remove dataset"),
+        name: z.string().optional().describe("Dataset name (required for upload and subset; optional for update)"),
+        description: z.string().optional().describe("Optional free-text description (upload/update)"),
+        tags: z.array(z.string()).optional().describe("Optional tags for inventory/navigation (upload/update)"),
         file_path: z
             .string()
             .optional()
@@ -86,7 +91,7 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
             .int()
             .optional()
             .describe("action=subset: RNG seed for sample_n (default 42)."),
-    }, async ({ action, name, file_path, csv_data, dataset_id, n_rows, row_range, filters, filter, sample_n, sample_seed, }) => {
+    }, async ({ action, name, description, tags, file_path, csv_data, dataset_id, n_rows, row_range, filters, filter, sample_n, sample_seed, }) => {
         if (action === "upload") {
             if (!name)
                 throw new Error("barmesh_datasets(upload) requires name.");
@@ -121,7 +126,12 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
                     const idem = await streamFileSha256(resolved);
                     let init;
                     try {
-                        init = (await apiCall("POST", "/v1/datasets/upload-url", { name, size_bytes: stat.size }, { "Idempotency-Key": idem }));
+                        const uploadUrlBody = { name, size_bytes: stat.size };
+                        if (description !== undefined)
+                            uploadUrlBody.description = description;
+                        if (tags !== undefined)
+                            uploadUrlBody.tags = tags;
+                        init = (await apiCall("POST", "/v1/datasets/upload-url", uploadUrlBody, { "Idempotency-Key": idem }));
                     }
                     catch (e) {
                         const msg = e instanceof Error ? e.message : String(e);
@@ -158,12 +168,17 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
                 }
                 if (isGzipInput) {
                     const gzBytes = await fs.readFile(resolved);
-                    const data = (await apiCall("POST", "/v1/datasets", gzBytes, {
+                    const gzHeaders = {
                         "X-Dataset-Name": name,
                         "Content-Type": uploadContentType,
                         "Content-Encoding": "gzip",
                         "Idempotency-Key": createHash("sha256").update(`${name}\n`).update(gzBytes).digest("hex"),
-                    }, UPLOAD_DATASET_TIMEOUT_MS));
+                    };
+                    if (description !== undefined)
+                        gzHeaders["X-Dataset-Description"] = description;
+                    if (tags !== undefined)
+                        gzHeaders["X-Dataset-Tags"] = JSON.stringify(tags);
+                    const data = (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));
@@ -184,6 +199,10 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
                 "Content-Type": uploadContentType,
                 "Idempotency-Key": createHash("sha256").update(`${name}\n`).update(body).digest("hex"),
             };
+            if (description !== undefined)
+                uploadHeaders["X-Dataset-Description"] = description;
+            if (tags !== undefined)
+                uploadHeaders["X-Dataset-Tags"] = JSON.stringify(tags);
             let uploadBody = body;
             if (Buffer.byteLength(body, "utf-8") > GZIP_THRESHOLD) {
                 uploadBody = gzipSync(Buffer.from(body, "utf-8"));
@@ -227,15 +246,9 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
             const data = (await apiCall("GET", "/v1/datasets"));
             if (Array.isArray(data)) {
                 const lines = data.map((ds) => {
-                    const id = String(ds.id ?? "");
-                    const dsName = String(ds.name ?? "");
-                    const rows = ds.rows != null ? Number(ds.rows) : "?";
-                    const cols = ds.cols != null ? Number(ds.cols) : "?";
-                    const st = ds.status != null ? String(ds.status) : "ready";
-                    const statusBit = st !== "ready" ? ` | status=${st}` : "";
+                    const base = formatDatasetInventoryLine(ds);
                     const ingestErr = cleanNullable(ds.ingest_error);
-                    const err = ingestErr ? ` | ingest_error=${ingestErr}` : "";
-                    return `${dsName} (${id}) — ${rows}×${cols}${statusBit}${err}`;
+                    return ingestErr ? `${base} | ingest_error=${ingestErr}` : base;
                 });
                 return { content: [{ type: "text", text: lines.length > 0 ? lines.join("\n") : "No datasets." }] };
             }
@@ -245,11 +258,14 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
             if (!dataset_id)
                 throw new Error("barmesh_datasets(get) requires dataset_id.");
             const ds = (await apiCall("GET", `/v1/datasets/${dataset_id}`));
+            const tagStr = formatTags(ds.tags);
             const lines = [
                 `Dataset: ${ds.name ?? "?"} (${ds.id ?? dataset_id})`,
                 `Status: ${ds.status ?? "ready"}`,
                 `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))` : "",
@@ -258,6 +274,22 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
             ].filter(Boolean);
             return { content: [{ type: "text", text: lines.join("\n") }] };
         }
+        if (action === "update") {
+            if (!dataset_id)
+                throw new Error("barmesh_datasets(update) requires dataset_id.");
+            const body = {};
+            if (name !== undefined)
+                body.name = name;
+            if (description !== undefined)
+                body.description = description;
+            if (tags !== undefined)
+                body.tags = tags;
+            if (Object.keys(body).length === 0) {
+                throw new Error("barmesh_datasets(update) requires at least one of name, description, tags");
+            }
+            const data = await apiCall("PATCH", `/v1/datasets/${dataset_id}`, body);
+            return textResult(data);
+        }
         if (action === "delete") {
             if (!dataset_id)
                 throw new Error("barmesh_datasets(delete) requires dataset_id.");

package/dist/tools/feedback.js

@@ -1,10 +1,29 @@
 import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
-import { apiCall, API_URL, fetchWithTimeout, textResult } from "../shared.js";
+import { apiCall, API_URL, fetchWithTimeout, probeApiHealth, structuredTextResult, } from "../shared.js";
+import { enqueueDeferredFeedback, flushDeferredFeedback, listDeferredFeedback, } from "../deferred_feedback.js";
+function isDeferworthy(err) {
+    const e = err;
+    if (e?.retryable)
+        return true;
+    if (e?.cause === "api_unreachable" || e?.cause === "storage" || e?.cause === "network")
+        return true;
+    const status = e?.httpStatus;
+    if (status === 502 || status === 503 || status === 504)
+        return true;
+    if (err instanceof TypeError)
+        return true;
+    if (err instanceof Error && /fetch failed|ECONNREFUSED|ENOTFOUND|ECONNRESET|network|timed out/i.test(err.message)) {
+        return true;
+    }
+    return false;
+}
 export function registerFeedbackTool(server) {
     registerAuditedTool(server, "barmesh_send_feedback", `Send feedback or feature requests to Barivia developers (CFD mesh-convergence / barmesh workflow). Use when the user has suggestions, ran into issues, or wants something improved. Do NOT call without asking the user first — but after a mesh-convergence or Richardson session, you SHOULD prepare feedback based on the user's workflow or errors encountered, show it to them, and ask for permission to send it. Once they accept, call this tool.
 
-For a substantial issue, prefer feedback_items: submit several focused instances (each max 1400 chars) covering, e.g., symptoms, exact reproduction steps, environment, and concrete asks — they are stored together as one batch so developers see the full picture. Use the single feedback field for a short one-off note.`, {
+For a substantial issue, prefer feedback_items: submit several focused instances (each max 1400 chars) covering, e.g., symptoms, exact reproduction steps, environment, and concrete asks — they are stored together as one batch so developers see the full picture. Use the single feedback field for a short one-off note.
+
+If the API or object storage is unavailable (e.g. gateway HTML 502 mid-demo), this tool queues feedback locally (~/.barivia/deferred-feedback, shared with barsom send_feedback) and returns deferred=true with request_id + api_health from GET /health (no R2). Call again later to flush.`, {
         feedback: z.string().max(1400).optional().describe("Single feedback note (max 1400 characters). Use feedback_items instead for a multi-part report."),
         feedback_items: z.array(z.string().max(1400)).max(10).optional().describe("Several feedback instances (each max 1400 characters, up to 10), stored together as one batch. Prefer this for a detailed issue: split it into focused parts (symptoms, reproduction, environment, asks)."),
     }, async ({ feedback, feedback_items }) => {
@@ -15,9 +34,19 @@ For a substantial issue, prefer feedback_items: submit several focused instances
             throw new Error("barmesh_send_feedback requires feedback or feedback_items (at least one non-empty entry).");
         }
         const body = items.length === 1 ? { feedback: items[0] } : { feedback_items: items };
+        const submit = async (b) => apiCall("POST", "/v1/feedback", b);
+        const flushed = await flushDeferredFeedback("barmesh", submit).catch(() => null);
         try {
-            const data = await apiCall("POST", "/v1/feedback", body);
-            return textResult(data);
+            const data = (await submit(body));
+            return structuredTextResult({
+                ...data,
+                deferred: false,
+                ...(flushed && flushed.flushed > 0
+                    ? { flushed_deferred: flushed.flushed, deferred_remaining: flushed.remaining }
+                    : {}),
+            }, typeof data.message === "string"
+                ? data.message
+                : "Feedback received. Thank you.");
         }
         catch (err) {
             if (err?.httpStatus === 401) {
@@ -31,10 +60,46 @@ For a substantial issue, prefer feedback_items: submit several focused instances
                     const text = await resp.text();
                     if (resp.ok) {
                         const parsed = JSON.parse(text);
-                        return textResult({ ...parsed, note: "Feedback sent anonymously (API key invalid or expired)." });
+                        return structuredTextResult({ ...parsed, deferred: false, note: "Feedback sent anonymously (API key invalid or expired)." }, "Feedback sent anonymously (API key invalid or expired).");
                     }
                 }
-                catch { /* fall through to original error */ }
+                catch { /* fall through */ }
+            }
+            if (isDeferworthy(err)) {
+                const e = err;
+                const queued = await enqueueDeferredFeedback("barmesh", body, {
+                    status: e.httpStatus,
+                    error_code: e.errorCode,
+                    request_id: e.requestId,
+                    message: e.message,
+                });
+                const api_health = await probeApiHealth().catch(() => ({
+                    liveness: "down",
+                    readiness: "unknown",
+                    storage: "not_probed",
+                }));
+                const pending = await listDeferredFeedback("barmesh");
+                return structuredTextResult({
+                    ok: true,
+                    deferred: true,
+                    deferred_id: queued.id,
+                    deferred_path: queued.path,
+                    deferred_pending: pending.length,
+                    error_code: e.errorCode ?? "api_unreachable",
+                    cause: e.cause ?? "api_unreachable",
+                    request_id: e.requestId ?? null,
+                    api_health,
+                    message: "API/storage unavailable — feedback saved locally and will be sent on the next successful barmesh_send_feedback call.",
+                }, [
+                    "Feedback deferred (API/storage unavailable).",
+                    `Saved to ${queued.path}`,
+                    e.requestId ? `request_id=${e.requestId}` : null,
+                    e.errorCode ? `error_code=${e.errorCode}` : null,
+                    `api_health.liveness=${api_health.liveness} (storage not_probed)`,
+                    "Retry barmesh_send_feedback later to flush the local queue.",
+                ]
+                    .filter(Boolean)
+                    .join(" | "));
             }
             throw err;
         }

package/dist/tools/guide.js

@@ -1,30 +1,36 @@
 import { registerAuditedTool } from "../audit.js";
-import { apiCall, textResult } from "../shared.js";
-const OFFLINE_GUIDE = `barmesh: CFD mesh-convergence on the Barivia API.
+import { apiCall, probeApiHealth, structuredTextResult, textResult } from "../shared.js";
+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.
 
-Two tracks:
+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.
+
+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
+- barmesh_richardson — classical Richardson / GCI on scalar QoIs (one mesh family per CSV: uniform OR graded, not mixed)
 
-Workflow:
+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
+5. barmesh_results(action=get) → barmesh_results_explorer for figures (mesh_convergence) or richardson_gci.csv summary (Richardson)
 
-(API unreachable; offline summary. Set BARIVIA_API_KEY / BARIVIA_API_URL.)`;
+(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.)`;
 export function registerGuideTool(server) {
     registerAuditedTool(server, "barmesh_guide_workflow", `Get the barmesh CFD mesh-convergence workflow and tool map from the API (tier-scoped).
 
 BEST FOR: First call in a session — orients you on the two tracks (SOM fingerprint distances and Richardson/GCI), the upload->submit->poll->results flow, and what your plan allows.
 NOT FOR: Step-by-step mesh-data preparation — use barmesh_prepare_mesh_data for that.
-ESCALATION: If the response says your plan does not include CFD tools, the analysis tools will return 403; contact Barivia to enable the cfd entitlement.`, {}, async () => {
+ESCALATION: If the response says your plan does not include CFD tools, the analysis tools will return 403; contact Barivia to enable the cfd entitlement.
+UNAVAILABLE: If the API is down, this tool returns a calm offline summary — say so plainly, keep reviewing last good results, and suggest retry later (~30s).`, {}, async () => {
         try {
             const data = (await apiCall("GET", "/v1/cfd/guide"));
             return textResult({
@@ -43,7 +49,7 @@ ESCALATION: If the response says your plan does not include CFD tools, the analy
 
 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).`, {}, async () => {
+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 () => {
         try {
             const data = (await apiCall("GET", "/v1/cfd/prep"));
             return textResult({ recipe: data.recipe, entitled: data.entitled });
@@ -54,4 +60,22 @@ COMMON MISTAKES: forgetting the per-cell cell-volume column; using different cha
             return textResult(OFFLINE_PREP);
         }
     });
+    registerAuditedTool(server, "barmesh_api_health", `Probe Barivia API liveness/readiness without touching object storage (R2).
+
+BEST FOR: Mid-demo outages — distinguish "API process up" from storage/gateway failures when barmesh_send_feedback or uploads fail.
+Uses GET /health (always 200 if process alive) and GET /ready (DB; Redis best-effort). storage is always not_probed.
+Also reports how many deferred barmesh feedback drafts are queued locally.`, {}, async () => {
+        const health = await probeApiHealth();
+        const deferred = await listDeferredFeedback("barmesh").catch(() => []);
+        const lines = [
+            `API liveness: ${health.liveness}`,
+            `API readiness: ${health.readiness}`,
+            health.db ? `DB: ${health.db}` : null,
+            health.redis ? `Redis: ${health.redis}` : null,
+            `Object storage (R2): ${health.storage} (intentionally not checked)`,
+            health.detail ? `Detail: ${health.detail}` : null,
+            `Deferred feedback drafts (barmesh): ${deferred.length}`,
+        ].filter(Boolean);
+        return structuredTextResult({ ...health, deferred_feedback_pending: deferred.length }, lines.join("\n"));
+    });
 }

package/dist/tools/jobs.js

@@ -5,17 +5,28 @@ import { pollCfdFinalizeIfPresent, refreshJobAfterFinalize } from "../cfd_finali
 import { formatJobStatusText } from "../job_status_format.js";
 import { DEFAULT_BLOCK_UNTIL_SEC, DEFAULT_POLL_INTERVAL_SEC } from "../job_monitor.js";
 import { runBlockingMonitor } from "../blocking_monitor.js";
+import { buildJobsListQuery, extractJobsList, formatDatasetInventoryLine, formatJobInventoryLine, } from "../inventory_format.js";
 export function registerJobsTool(server) {
-    registerAuditedTool(server, "barmesh_jobs", `Check job status, block until terminal, or list jobs.
+    registerAuditedTool(server, "barmesh_jobs", `Check job status, block until terminal, list/update jobs, or rebuild an org inventory.
 
-BEST FOR: action=monitor after submit (one call, throttled snapshots — preferred for agents). action=status for a single one-shot check.
+| Action | Use when |
+|--------|----------|
+| monitor | After async submit — blocks with snapshots until terminal (preferred for agents) |
+| status | One-shot progress check |
+| list | Slim recent jobs (filter/page with limit/cursor/status/job_type/has_results) |
+| update | Edit label / description / tags |
+| 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.
 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=...).
-ESCALATION: status=failed returns an error message and (when available) a failure_stage; read it before retrying.`, {
+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"])
-            .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)"),
+            .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)"),
         block_until_sec: z
             .number()
             .int()
@@ -32,8 +43,33 @@ ESCALATION: status=failed returns an error message and (when available) a failur
             .boolean()
             .optional()
             .describe("action=monitor only: wait for cfd_finalize (default true)"),
+        dataset_id: z.string().optional().describe("action=list: filter by dataset ID"),
+        status: z
+            .enum(["pending", "running", "completed", "failed", "cancelled"])
+            .optional()
+            .describe("action=list: filter by status"),
+        job_type: z
+            .string()
+            .optional()
+            .describe("action=list: MCP job_type label (e.g. cfd_mesh_convergence, cfd_richardson)"),
+        has_results: z
+            .boolean()
+            .optional()
+            .describe("action=list: true = completed jobs with result_ref"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .optional()
+            .describe("action=list/inventory: page size (default 50)"),
+        cursor: z.string().optional().describe("action=list: next_cursor from a prior page"),
+        fields: z.enum(["slim", "full"]).optional().describe("action=list: slim (default) or full"),
+        label: z.string().optional().describe("action=update: new label"),
+        description: z.string().optional().describe("action=update: free-text description"),
+        tags: z.array(z.string()).optional().describe("action=update: replace tags"),
     }, async (args) => {
-        const { action, job_id, block_until_sec, poll_interval_sec, wait_finalize } = args;
+        const { action, job_id, block_until_sec, poll_interval_sec, wait_finalize, dataset_id, status, job_type, has_results, limit, cursor, fields, label, description, tags, } = args;
         if (action === "monitor") {
             if (!job_id)
                 throw new Error("barmesh_jobs(monitor) requires job_id.");
@@ -43,16 +79,86 @@ ESCALATION: status=failed returns an error message and (when available) a failur
             if (!job_id)
                 throw new Error("barmesh_jobs(status) requires job_id.");
             let data = (await apiCall("GET", `/v1/jobs/${job_id}`));
-            const status = String(data.status ?? "");
+            const statusVal = String(data.status ?? "");
             let note = null;
-            if (status === "completed" && data.finalize_job_id) {
+            if (statusVal === "completed" && data.finalize_job_id) {
                 ({ note } = await pollCfdFinalizeIfPresent(job_id, data));
                 data = await refreshJobAfterFinalize(job_id);
             }
             const statusText = await formatJobStatusText(job_id, data);
             return textResult({ ...data, status_text: note ? `${statusText}\n${note}` : statusText });
         }
-        const data = await apiCall("GET", "/v1/jobs");
-        return textResult(data);
+        if (action === "list") {
+            const listPath = buildJobsListQuery({
+                dataset_id, status, job_type, has_results, limit, cursor, fields,
+            });
+            const data = await apiCall("GET", listPath);
+            const { jobs, next_cursor } = extractJobsList(data);
+            const lines = jobs.map((job) => formatJobInventoryLine(job));
+            if (next_cursor) {
+                lines.push("");
+                lines.push(`next_cursor: ${next_cursor}`);
+                lines.push(`Tip: barmesh_jobs(action=list, cursor="${next_cursor}", limit=${limit ?? 50}) for the next page.`);
+            }
+            return {
+                content: [{
+                        type: "text",
+                        text: lines.length > 0 ? lines.join("\n") : "No jobs found.",
+                    }],
+            };
+        }
+        if (action === "update") {
+            if (!job_id)
+                throw new Error("barmesh_jobs(update) requires job_id.");
+            const body = {};
+            if (label !== undefined)
+                body.label = label;
+            if (description !== undefined)
+                body.description = description;
+            if (tags !== undefined)
+                body.tags = tags;
+            if (Object.keys(body).length === 0) {
+                throw new Error("barmesh_jobs(update) requires at least one of label, description, tags");
+            }
+            const data = await apiCall("PATCH", `/v1/jobs/${job_id}`, body);
+            return textResult(data);
+        }
+        if (action === "inventory") {
+            const jobLimit = limit && limit > 0 ? Math.min(Math.floor(limit), 100) : 50;
+            const [datasetsRaw, jobsRaw] = await Promise.all([
+                apiCall("GET", "/v1/datasets"),
+                apiCall("GET", buildJobsListQuery({ limit: jobLimit })),
+            ]);
+            const datasets = Array.isArray(datasetsRaw) ? datasetsRaw : [];
+            const { jobs, next_cursor } = extractJobsList(jobsRaw);
+            const lines = [
+                `# Org inventory (barmesh)`,
+                ``,
+                `## Datasets (${datasets.length})`,
+            ];
+            if (datasets.length === 0) {
+                lines.push("(none)");
+            }
+            else {
+                for (const ds of datasets)
+                    lines.push(`- ${formatDatasetInventoryLine(ds)}`);
+            }
+            lines.push(``, `## Jobs (latest ${jobs.length}${next_cursor ? ", more available" : ""})`);
+            if (jobs.length === 0) {
+                lines.push("(none)");
+            }
+            else {
+                for (const job of jobs)
+                    lines.push(`- ${formatJobInventoryLine(job)}`);
+            }
+            if (next_cursor) {
+                lines.push(``);
+                lines.push(`More jobs: barmesh_jobs(action=list, cursor="${next_cursor}", limit=${jobLimit})`);
+            }
+            lines.push(``);
+            lines.push(`Tips: set description/tags on barmesh_datasets(upload|update) and barmesh_mesh_convergence / barmesh_jobs(update).`);
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        throw new Error("Invalid action");
     });
 }

package/dist/tools/results.js

@@ -4,6 +4,7 @@ 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 { 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"];
 function formatMeshResultsSummary(jobId, data, summary) {
     const label = data.label != null && data.label !== "" ? String(data.label) : null;
@@ -39,13 +40,14 @@ const TEXT_ARTIFACTS = [
     "distances_to_ref.txt",
     "emd_stepwise.txt",
     "cfd_metrics.json",
+    "richardson_gci.csv",
 ];
 export function registerResultsTool(server) {
-    registerAuditedTool(server, "barmesh_results", `Fetch results of a completed CFD job: distances, convergence reading, and figures.
+    registerAuditedTool(server, "barmesh_results", `Fetch results of a completed CFD job: distances, convergence reading, and figures (mesh_convergence) or Richardson/GCI triplets (richardson).
 
 | Action | Use when |
 |--------|----------|
-| get | Read the summary (distances per mesh, stepwise, convergence reading) and inline key figures. |
+| get | Read the summary. mesh_convergence: distances + inline figures. richardson: triplet p/GCI table + topology_warning; see richardson_gci.csv. |
 | image | Download one figure by filename (e.g. KL_ref.png, combined.pdf). |
 | render | Re-render the figures as publication PDFs (or SVG) on demand — PDFs are NOT generated by default. |
 | download | Save figures and metrics to a local folder (headless / agent path). |
@@ -54,6 +56,7 @@ BEST FOR: After barmesh_jobs(action=status) shows completed (and finalize finish
 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. action=get inlines the headline set; pass figures="all" for every artifact listed in summary.files, figures="none" for metrics only (recommended for agents).
 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.
+UNAVAILABLE: If the mesh analysis API is temporarily unavailable, say so plainly and suggest retry later (~retry_after_sec). Figures already downloaded stay usable.
 NOT FOR: Submitting jobs.`, {
         action: z.enum(["get", "image", "render", "download"]).describe("get: summary + figures; image: one file; render: lazy PDF/SVG; download: save to disk"),
         job_id: z.string().describe("Job ID"),
@@ -193,7 +196,10 @@ NOT FOR: Submitting jobs.`, {
             throw err;
         }
         const summary = (data.summary ?? {});
-        const content = [{ type: "text", text: formatMeshResultsSummary(job_id, data, summary) }];
+        const summaryText = isRichardsonJob(summary)
+            ? formatRichardsonResultsSummary(job_id, data, summary)
+            : formatMeshResultsSummary(job_id, data, summary);
+        const content = [{ type: "text", text: summaryText }];
         if (figures === "none")
             return { content };
         const allFiles = summary.files ?? [];

package/dist/tools/training_monitor.js

@@ -1,13 +1,15 @@
 import { z } from "zod";
 import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
 import { runMcpToolAudit } from "../audit.js";
-import { apiCall, getClientSupportsMcpApps, getVizPort, structuredTextResult, } from "../shared.js";
+import { apiCall, BARMESH_VIZ_VIEWS, buildStandaloneVizPageUrl, buildVizRelatedUrls, getVizPort, structuredTextResult, } from "../shared.js";
+import { appendUiDeliveryContent, resolveUiDelivery, } from "../ui-delivery.js";
 import { enrichWithTrainingLog, needsTrainingLogEnrichment } from "../training_review.js";
 import { formatRunConfigTable } from "../run_config.js";
 export const TRAINING_MONITOR_URI = "ui://barmesh/training-monitor";
 export const TRAINING_MONITOR_REFRESH_MS = 5000;
-function buildStructuredContent(job_id, data) {
+function buildStructuredContent(job_id, data, port) {
     const id = String(data.id ?? job_id);
+    const standaloneUrl = buildStandaloneVizPageUrl(port, BARMESH_VIZ_VIEWS.trainingMonitor, id);
     return {
         ...data,
         type: "barmesh-training-monitor",
@@ -15,12 +17,14 @@ function buildStructuredContent(job_id, data) {
         id,
         job_id: id,
         refresh_interval_ms: TRAINING_MONITOR_REFRESH_MS,
+        standaloneUrl,
+        relatedUrls: buildVizRelatedUrls(port, id, BARMESH_VIZ_VIEWS),
     };
 }
 export function registerTrainingMonitorTool(server) {
     registerAppTool(server, "barmesh_training_monitor", {
         title: "Mesh Convergence Training Monitor",
-        description: "Default visual monitor for mesh_convergence jobs after submit. Embedded MCP App auto-refreshes every 5s: epoch progress bar, phase, ETA, live QE/TE curves (uniformly subsampled to ≤1000 batch samples per phase), and a per-epoch hit-grid heatmap when available. On already-completed jobs, replays training-log curves in review mode (same entry point). Also exposes a standalone localhost URL — copy it if window.open is blocked in your MCP host. Headless fallback: barmesh_jobs(action=monitor) blocks with compact text snapshots (live or post-hoc review). barmesh_jobs(action=status) remains a one-shot poll. After completion, use barmesh_results_explorer for figures.",
+        description: "Default visual monitor for mesh_convergence jobs after submit. Embedded MCP App auto-refreshes every 5s: epoch progress bar, phase, ETA, live QE/TE curves (uniformly subsampled to ≤1000 batch samples per phase; SOM batch-step labels — not FLooP unless job_type is FLooP), panel fingerprint ΔKL curve (mean/max SKL→ref on the TE panel), and a per-epoch hit-grid heatmap when available. On already-completed jobs, replays training-log curves in review mode (same entry point). Also exposes a standalone localhost URL — copy it if window.open is blocked in your MCP host. In MCP App context, use Copy results explorer link when Open results explorer cannot navigate. Headless fallback: barmesh_jobs(action=monitor) blocks with compact text snapshots (live or post-hoc review). barmesh_jobs(action=status) remains a one-shot poll. After completion, use barmesh_results_explorer for figures.",
         inputSchema: {
             job_id: z.string().describe("Job ID from barmesh_mesh_convergence or barmesh_richardson"),
             fetch_training_log: z
@@ -37,7 +41,7 @@ export function registerTrainingMonitorTool(server) {
         if (fetch_training_log || needsTrainingLogEnrichment(data)) {
             data = await enrichWithTrainingLog(job_id, data);
         }
-        const structuredContent = buildStructuredContent(job_id, data);
+        const structuredContent = buildStructuredContent(job_id, data, getVizPort());
         const progress = (data.progress ?? 0) * 100;
         const etaSec = data.training_eta_sec != null ? Number(data.training_eta_sec) : null;
         const elapsedSec = data.training_elapsed_sec != null ? Number(data.training_elapsed_sec) : null;
@@ -56,24 +60,25 @@ export function registerTrainingMonitorTool(server) {
         const text = (runConfigNote ? `${runConfigNote}\n` : "") +
             `Training monitor (visual MCP App, refreshes every ${TRAINING_MONITOR_REFRESH_MS / 1000}s): job ${job_id} — ${jobStatus} (${progress.toFixed(1)}%).${modeNote}${timingNote}`;
         const content = [{ type: "text", text }];
-        const port = getVizPort();
-        const standaloneUrl = port
-            ? `http://localhost:${port}/viz/barmesh-training-monitor?mode=standalone&job_id=${encodeURIComponent(job_id)}`
-            : undefined;
-        if (standaloneUrl) {
-            content.push({
-                type: "text",
-                text: `Standalone training monitor URL (copy if Open is blocked):\n${standaloneUrl}\n` +
-                    `AGENT: surface this URL to the user — use a markdown link or tell them to copy/paste into a browser when the inline panel cannot open localhost. Re-post after the job completes so they can review curves.\n` +
-                    `This localhost port is per MCP session and goes stale if the proxy restarts — re-run barmesh_training_monitor for a fresh URL, or set BARIVIA_VIZ_PORT for a persistent port. Health check: http://localhost:${port}/api/health?job_id=${encodeURIComponent(job_id)}`,
-            });
-        }
-        if (!getClientSupportsMcpApps() && standaloneUrl) {
-            content.push({
-                type: "text",
-                text: `Interactive training monitor: [Open training monitor](${standaloneUrl})`,
-            });
+        const uiDelivery = resolveUiDelivery({
+            tool: "training_monitor",
+            jobId: job_id,
+            jobStatus,
+        });
+        appendUiDeliveryContent(content, uiDelivery, {
+            linkLabel: "Open training monitor",
+            primaryUrl: structuredContent.standaloneUrl,
+        });
+        if (jobStatus === "completed" && uiDelivery.urls?.length) {
+            const resultsUrl = uiDelivery.urls.find((u) => u.includes("results-explorer"));
+            if (resultsUrl) {
+                content.push({
+                    type: "text",
+                    text: `Job completed — browse figures: [Open results explorer](${resultsUrl})`,
+                });
+            }
         }
+        structuredContent.ui_delivery = uiDelivery;
         return {
             ...structuredTextResult(structuredContent, text, content),
             _meta: { ui: { resourceUri: TRAINING_MONITOR_URI } },