@barivia/barmesh-mcp 0.7.1 → 0.8.0

package/dist/tools/barmesh_results_explorer.js

@@ -1,9 +1,11 @@
 import { z } from "zod";
 import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
 import { runMcpToolAudit } from "../audit.js";
-import { apiCall, apiRawCall, getClientSupportsMcpApps, getVizPort, getCaptionForImage, mimeForFilename, structuredTextResult, tryAttachImage, } from "../shared.js";
+import { apiCall, apiRawCall, BARMESH_VIZ_VIEWS, buildStandaloneVizPageUrl, buildVizRelatedUrls, getVizPort, getCaptionForImage, mimeForFilename, structuredTextResult, tryAttachImage, } from "../shared.js";
 import { FIGURE_SECTION_LABELS, FIGURE_SECTION_ORDER, figureSection, sortRank, } from "../figure_sections.js";
 import { buildMetadataStrip } from "../results_metadata.js";
+import { appendUiDeliveryContent, buildStandaloneVizUrl, resolveUiDelivery, } from "../ui-delivery.js";
+import { buildBarmeshVizStandaloneUrl } from "../viz_links.js";
 export const RESULTS_EXPLORER_URI = "ui://barmesh/results-explorer";
 export function sortFigures(figures) {
     return [...figures].sort((a, b) => FIGURE_SECTION_ORDER.indexOf(a.section ?? "diagnostics") -
@@ -111,6 +113,10 @@ export function buildPayload(jobId, data, jobMeta) {
     const files = (summary.files ?? []).filter((f) => /\.(png|pdf|svg)$/i.test(f));
     const figures = sortFigures(groupFigures(files));
     const port = getVizPort();
+    const standaloneUrl = buildStandaloneVizPageUrl(port, BARMESH_VIZ_VIEWS.resultsExplorer, jobId) ??
+        buildBarmeshVizStandaloneUrl("barmesh-results-explorer", jobId);
+    const trainingMonitorUrl = buildStandaloneVizPageUrl(port, BARMESH_VIZ_VIEWS.trainingMonitor, jobId) ??
+        buildBarmeshVizStandaloneUrl("barmesh-training-monitor", jobId);
     return {
         type: "barmesh-results-explorer",
         jobId,
@@ -120,9 +126,9 @@ export function buildPayload(jobId, data, jobMeta) {
         metrics: buildMetrics(summary),
         availableFigures: figures,
         defaultFigureKey: resolveDefaultFigureKey(figures),
-        standaloneUrl: port
-            ? `http://localhost:${port}/viz/barmesh-results-explorer?mode=standalone&job_id=${jobId}`
-            : undefined,
+        standaloneUrl,
+        trainingMonitorUrl,
+        relatedUrls: buildVizRelatedUrls(port, jobId, BARMESH_VIZ_VIEWS),
     };
 }
 async function handleResultsExplorer(job_id) {
@@ -131,40 +137,40 @@ async function handleResultsExplorer(job_id) {
         apiCall("GET", `/v1/jobs/${job_id}`).catch(() => ({})),
     ]);
     const payload = buildPayload(job_id, data, jobMeta);
-    const content = [
-        {
-            type: "text",
-            text: [
-                `Mesh convergence results explorer ready for job ${job_id}.`,
-                payload.subtitle ? `Label: ${payload.subtitle}` : "",
-                payload.metadataStrip?.[0] ?? "",
-            ]
-                .filter(Boolean)
-                .join("\n"),
-        },
-    ];
+    const summaryText = [
+        `Mesh convergence results explorer ready for job ${job_id}.`,
+        payload.subtitle ? `Label: ${payload.subtitle}` : "",
+        payload.metadataStrip?.[0] ?? "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+    const content = [{ type: "text", text: summaryText }];
+    let inlineImageAttached = false;
     const defaultFigure = payload.availableFigures.find((f) => f.key === payload.defaultFigureKey);
     if (defaultFigure && /\.(png|svg|jpe?g|webp)$/i.test(defaultFigure.filename)) {
+        const before = content.length;
         await tryAttachImage(content, job_id, defaultFigure.filename);
+        inlineImageAttached = content.length > before && content.some((c) => c.type === "image");
     }
-    if (payload.standaloneUrl) {
-        content.push({
-            type: "text",
-            text: `Standalone results explorer URL (copy if Open is blocked):\n${payload.standaloneUrl}\n` +
-                `AGENT: surface this URL to the user — markdown link or copy/paste into a browser when the inline MCP panel cannot open localhost. ` +
-                `This localhost port is per MCP session and goes stale if the proxy restarts — re-run barmesh_results_explorer for a fresh URL, or set BARIVIA_VIZ_PORT for a persistent port.`,
-        });
-    }
-    if (!getClientSupportsMcpApps() && payload.standaloneUrl) {
+    const uiDelivery = resolveUiDelivery({
+        tool: "results_explorer",
+        jobId: job_id,
+        jobStatus: "completed",
+        inlineImageAttached,
+    });
+    appendUiDeliveryContent(content, uiDelivery, {
+        linkLabel: "Open results explorer",
+        primaryUrl: payload.standaloneUrl ?? buildStandaloneVizUrl("results_explorer", job_id),
+    });
+    const monitorUrl = payload.trainingMonitorUrl ?? buildStandaloneVizUrl("training_monitor", job_id);
+    if (monitorUrl) {
         content.push({
             type: "text",
-            text: `Interactive results explorer: [Open results explorer](${payload.standaloneUrl})\n` +
-                `AGENT: surface this to the user as a clickable markdown link in your reply. ` +
-                `This localhost port is assigned per MCP session and changes if the proxy restarts — re-run barmesh_results_explorer for a fresh URL, or set BARIVIA_VIZ_PORT for a persistent port.`,
+            text: `Review training curves: [Open training monitor](${monitorUrl})`,
         });
     }
     return {
-        ...structuredTextResult(payload, undefined, content),
+        ...structuredTextResult({ ...payload, ui_delivery: uiDelivery }, undefined, content),
         _meta: { ui: { resourceUri: RESULTS_EXPLORER_URI } },
     };
 }

package/dist/tools/cfd.js

@@ -10,14 +10,14 @@ What it does (one call): joint-normalizes all meshes, trains one SOM on a strati
 BEST FOR: A mesh-refinement study where you want a field-level (not just scalar) view of whether the mesh has converged.
 NOT FOR: Single scalar quantities of interest — use barmesh_richardson for classical GCI.
 ASYNC: This is a queued job. It returns a job id immediately. Then poll barmesh_jobs(action=status) every 10-20s; datacenter-scale grids plus EMD can take a few minutes — keep polling. On completion call barmesh_results(action=get).
-COMMON MISTAKES: omitting feature_columns (required); choosing a reference_mesh label that is not present; forgetting the cell-volume column at upload time.`, {
+COMMON MISTAKES: omitting feature_columns (required); choosing a reference_mesh label that is not present; forgetting the cell-volume column at upload time; multi-topology studies (uniform U + graded G meshes) without explicit mesh_order — equal cell counts sort U-then-G and invent bogus stepwise pairs (U160|G20). Pass mesh_order coarse→fine interleaved by refinement (U20,G20,U40,G40,…) or use preset=cavity which defaults interleaved when U/G labels are detected.`, {
         dataset_id: z.string().describe("Dataset ID from barmesh_datasets(upload)"),
         feature_columns: z.array(z.string()).describe("Per-cell numeric feature columns to train the SOM on (e.g. [\"p\",\"U_mag\",\"k\",\"log_epsilon\"])"),
         preset: z.enum(["generic", "cavity", "pitz", "datacenter"]).optional().describe("Hyperparameter preset; defaults to generic. cavity/pitz/datacenter reproduce the published settings."),
         mesh_column: z.string().optional().describe("Column with the mesh label (default mesh_id)"),
         volume_column: z.string().optional().describe("Cell-volume column for fingerprint weights (default V; equal weights if absent)"),
         reference_mesh: z.string().optional().describe("Mesh label used as reference (default: the mesh with the most cells = finest)"),
-        mesh_order: z.array(z.string()).optional().describe("Explicit coarse-to-fine mesh order (default: ascending cell count)"),
+        mesh_order: z.array(z.string()).optional().describe("Explicit coarse-to-fine mesh order (default: ascending cell count; cavity preset and tied U/G cell counts auto-interleave U20→G20→U40→G40→…)"),
         grid: z.array(z.number().int()).optional().describe("SOM grid [rows, cols] (overrides preset)"),
         epochs: z.array(z.number().int()).optional().describe("[ordering, convergence] epochs (overrides preset)"),
         batch_size: z.number().int().optional().describe("SOM batch size (overrides preset)"),
@@ -34,8 +34,10 @@ COMMON MISTAKES: omitting feature_columns (required); choosing a reference_mesh
         normalization_methods: z.record(z.enum(["zscore", "mad", "sigmoidal", "sepd", "none"])).optional().describe("Per-feature normalization override; keys must be in feature_columns."),
         row_range: z.tuple([z.number().int().min(1), z.number().int().min(1)]).optional().describe("1-based inclusive [start, end] row slice applied during preprocessing (and to mesh labels / cell volumes)."),
         label: z.string().optional().describe("Optional job label"),
+        description: z.string().optional().describe("Optional free-text description for inventory"),
+        tags: z.array(z.string()).optional().describe("Optional tags for inventory/navigation"),
     }, async (args) => {
-        const { dataset_id, label, ...rest } = args;
+        const { dataset_id, label, description, tags, ...rest } = args;
         const params = {};
         for (const [k, v] of Object.entries(rest)) {
             if (v !== undefined && v !== null)
@@ -47,6 +49,10 @@ COMMON MISTAKES: omitting feature_columns (required); choosing a reference_mesh
         const body = { dataset_id, params };
         if (typeof label === "string" && label.length > 0)
             body.label = label;
+        if (description !== undefined)
+            body.description = description;
+        if (tags !== undefined)
+            body.tags = tags;
         const data = (await apiCall("POST", "/v1/cfd/mesh-convergence", body));
         await pollCfdPrepareIfPresent(data, "barmesh_mesh_convergence");
         const id = data.id;
@@ -63,7 +69,7 @@ What it does: from a small CSV with one row per mesh (a mesh label, a representa
 BEST FOR: Scalar benchmarks (reattachment length, centerline values, probe readings) where a classical asymptotic-convergence check is expected.
 NOT FOR: High-dimensional field comparison — use barmesh_mesh_convergence (complementary).
 ASYNC: queued job; poll barmesh_jobs(action=status), then barmesh_results(action=get).
-COMMON MISTAKES: not providing h_column or n_cells_column; mixing QoIs with different mesh sets in one CSV.`, {
+COMMON MISTAKES: not providing h_column or n_cells_column; mixing QoIs with different mesh sets in one CSV; mixing uniform (U…) and graded (G…) mesh families in one CSV — classical GCI assumes one topology per job; run separate Richardson jobs per family (e.g. G160|G80|G40 graded, U160|U80|U40 uniform).`, {
         dataset_id: z.string().describe("Dataset ID (one row per mesh)"),
         qoi_columns: z.array(z.string()).describe("Scalar QoI column names to extrapolate"),
         mesh_column: z.string().optional().describe("Mesh label column (default mesh_id)"),
@@ -72,8 +78,10 @@ COMMON MISTAKES: not providing h_column or n_cells_column; mixing QoIs with diff
         dimension: z.number().int().optional().describe("Spatial dimension d for deriving h from cell count (default 3)"),
         safety_factor: z.number().optional().describe("GCI safety factor Fs (default 1.25, Roache)"),
         label: z.string().optional().describe("Optional job label"),
+        description: z.string().optional().describe("Optional free-text description for inventory"),
+        tags: z.array(z.string()).optional().describe("Optional tags for inventory/navigation"),
     }, async (args) => {
-        const { dataset_id, label, ...rest } = args;
+        const { dataset_id, label, description, tags, ...rest } = args;
         const params = {};
         for (const [k, v] of Object.entries(rest)) {
             if (v !== undefined && v !== null)
@@ -82,6 +90,10 @@ COMMON MISTAKES: not providing h_column or n_cells_column; mixing QoIs with diff
         const body = { dataset_id, params };
         if (typeof label === "string" && label.length > 0)
             body.label = label;
+        if (description !== undefined)
+            body.description = description;
+        if (tags !== undefined)
+            body.tags = tags;
         const data = (await apiCall("POST", "/v1/cfd/richardson", body));
         const id = data.id;
         if (id != null)

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"));
+    });
 }