@barivia/barmesh-mcp 0.7.0 → 0.8.0

package/dist/shared.js

@@ -13,17 +13,29 @@ import { pipeline } from "node:stream/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { logInfo } from "./logger.js";
+import { logInfo, logWarn } from "./logger.js";
 // ---------------------------------------------------------------------------
 // Config
 // ---------------------------------------------------------------------------
-export const API_URL = process.env.BARIVIA_API_URL ?? process.env.BARSOM_API_URL ?? "https://api.barivia.se";
-export const API_KEY = process.env.BARIVIA_API_KEY ?? process.env.BARSOM_API_KEY ?? "";
+export const API_URL = process.env.BARIVIA_API_URL ?? "https://api.barivia.se";
+export const API_KEY = process.env.BARIVIA_API_KEY ?? "";
 export const FETCH_TIMEOUT_MS = parseInt(process.env.BARIVIA_FETCH_TIMEOUT_MS ?? "60000", 10);
-export const MAX_RETRIES = 2;
+/** Retries after the first attempt; default 2 → 3 total tries. Override with BARIVIA_MAX_RETRIES. */
+export const MAX_RETRIES = parseInt(process.env.BARIVIA_MAX_RETRIES ?? "2", 10);
+/** Delay between burst retries (ms). Default 2000 → ~2s between each of the 3 attempts. */
+export const RETRY_BASE_MS = parseInt(process.env.BARIVIA_RETRY_BASE_MS ?? "2000", 10);
 export const RETRYABLE_STATUS = new Set([502, 503, 504]);
+/** Cool-down hint after the burst is exhausted — agents should wait before another round. */
+export const UNAVAILABLE_RETRY_AFTER_SEC = 30;
+/** Fixed delay between burst retries (not exponential). */
+export function retryDelayMs(_attempt) {
+    return RETRY_BASE_MS;
+}
+function newRequestId() {
+    return randomUUID();
+}
 /** Single source of truth for the proxy version. Keep in sync with package.json on bump. */
-export const CLIENT_VERSION = "0.7.0";
+export const CLIENT_VERSION = "0.8.0";
 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;
@@ -33,6 +45,21 @@ export const LARGE_UPLOAD_BYTES = 64 * 1024 * 1024; // 64 MB
 export const PRESIGNED_PUT_TIMEOUT_MS = 30 * 60_000; // 30 min
 /** Poll window for the async stage_dataset job. */
 export const POLL_STAGE_MAX_MS = 30 * 60_000; // 30 min
+/** Map a local upload path to the API Content-Type (csv vs tsv; ignores .gz suffix). */
+export function resolveUploadContentType(filePath) {
+    const lower = filePath.toLowerCase();
+    const base = lower.endsWith(".gz") ? lower.slice(0, -3) : lower;
+    return path.extname(base) === ".tsv" ? "text/tab-separated-values" : "text/csv";
+}
+export function suggestMeshDatasetPreview(datasetId) {
+    return `barmesh_datasets(action=preview, dataset_id=${datasetId}) to verify mesh, feature, and volume columns.`;
+}
+export function suggestAfterCfdSubmit(jobId, prepSuffix = "") {
+    return `Run barmesh_training_monitor(job_id="${jobId}") or barmesh_jobs(action=monitor, job_id="${jobId}")${prepSuffix}; on completion call barmesh_results(action=get, job_id="${jobId}").`;
+}
+export function suggestAfterRender(parentJobId, fmt) {
+    return `Figures rendered as ${fmt}. Download with barmesh_results(action=download, job_id="${parentJobId}") or barmesh_results(action=image, job_id="${parentJobId}", filename=<figure>.${fmt}).`;
+}
 /** Streaming SHA-256 of a file (idempotency key) without reading it into memory. */
 export async function streamFileSha256(srcPath) {
     return new Promise((resolve, reject) => {
@@ -80,7 +107,11 @@ export async function putPresignedStream(url, srcPath, contentType, timeoutMs =
         const resp = await fetch(url, {
             method: "PUT",
             body: webStream,
-            headers: { "Content-Type": contentType, "Content-Length": String(contentLength) },
+            headers: {
+                "Content-Type": contentType,
+                "Content-Length": String(contentLength),
+                "Content-Encoding": "gzip",
+            },
             duplex: "half",
             signal: controller.signal,
         });
@@ -112,6 +143,51 @@ export function getClientSupportsMcpApps() {
 export function setClientSupportsMcpApps(value) {
     _clientSupportsMcpApps = value;
 }
+export const BARMESH_VIZ_VIEWS = {
+    trainingMonitor: "barmesh-training-monitor",
+    resultsExplorer: "barmesh-results-explorer",
+};
+export function buildStandaloneVizPageUrl(port, viewPath, jobId) {
+    if (!port)
+        return undefined;
+    return `http://localhost:${port}/viz/${viewPath}?mode=standalone&job_id=${encodeURIComponent(jobId)}`;
+}
+export function buildVizRelatedUrls(port, jobId, views) {
+    if (!port)
+        return undefined;
+    return {
+        trainingMonitor: buildStandaloneVizPageUrl(port, views.trainingMonitor, jobId),
+        resultsExplorer: buildStandaloneVizPageUrl(port, views.resultsExplorer, jobId),
+    };
+}
+/** Prominent standalone URL blocks for tool results — always emitted when a viz port exists. */
+export function buildVizUrlContentBlocks(options) {
+    const { label, toolName, standaloneUrl, port, jobId, clientSupportsMcpApps } = options;
+    if (!standaloneUrl)
+        return [];
+    const embedNote = clientSupportsMcpApps
+        ? "Embedded panel if your host supports MCP Apps — otherwise open the standalone URL below (expected on some Cursor builds)."
+        : "Open the standalone URL below when no inline panel appears.";
+    const health = port > 0
+        ? ` Health check: http://localhost:${port}/api/health?job_id=${encodeURIComponent(jobId)}`
+        : "";
+    const blocks = [
+        {
+            type: "text",
+            text: `${embedNote}\n` +
+                `Standalone ${label} URL (copy if Open is blocked):\n${standaloneUrl}\n` +
+                `AGENT: surface this URL prominently in your reply — use a markdown link "[Open ${label}](${standaloneUrl})" or tell the user to copy/paste into a browser. Do not bury it after metrics.\n` +
+                `This localhost port is per MCP session and goes stale if the proxy restarts — re-run ${toolName} for a fresh URL, or set BARIVIA_VIZ_PORT for a persistent port.${health}`,
+        },
+    ];
+    if (!clientSupportsMcpApps) {
+        blocks.push({
+            type: "text",
+            text: `[Open ${label}](${standaloneUrl})`,
+        });
+    }
+    return blocks;
+}
 /** Tool result carrying both a structured payload (for the MCP App view) and text/image content. */
 export function structuredTextResult(structuredContent, text, content) {
     return {
@@ -147,7 +223,7 @@ export async function fetchWithTimeout(url, init, timeoutMs = FETCH_TIMEOUT_MS)
 // Path / sandbox helpers
 // ---------------------------------------------------------------------------
 export function getSandboxRoot() {
-    const raw = process.env.BARIVIA_WORKSPACE_ROOT ?? process.env.BARSOM_WORKSPACE_ROOT;
+    const raw = process.env.BARIVIA_WORKSPACE_ROOT;
     if (raw)
         return path.resolve(process.cwd(), raw);
     const workspaceFolder = process.env.CURSOR_WORKSPACE_FOLDER ?? process.env.WORKSPACE_FOLDER;
@@ -220,47 +296,227 @@ export async function resolveFilePathForUpload(filePath, mcpServer) {
     const resolved = path.resolve(root, trimmed);
     return checkUnder(resolved);
 }
-export function formatApiErrorMessage(status, bodyText, requestId) {
+function looksLikeHtml(bodyText) {
+    const t = bodyText.trim().slice(0, 200).toLowerCase();
+    return t.startsWith("<!doctype") || t.startsWith("<html") || /<\s*html[\s>]/.test(t);
+}
+function isStorageErrorCode(code) {
+    if (!code)
+        return false;
+    const c = code.toLowerCase();
+    return c === "storage_upload_failed" || (c.includes("storage") && !c.includes("unavailable"));
+}
+/**
+ * Classify an HTTP API failure into a compact structured error.
+ * Gateway HTML 502/503 bodies are never echoed — they become api_unreachable.
+ */
+export function classifyApiError(status, bodyText, requestId) {
     let parsed = null;
-    try {
-        const j = JSON.parse(bodyText);
-        if (j && typeof j === "object")
-            parsed = j;
-    }
-    catch {
-        /* ignore */
+    const html = looksLikeHtml(bodyText);
+    if (!html && bodyText.trim()) {
+        try {
+            const j = JSON.parse(bodyText);
+            if (j && typeof j === "object")
+                parsed = j;
+        }
+        catch {
+            /* non-JSON */
+        }
     }
-    const detail = (parsed?.error != null && String(parsed.error)) ||
-        (bodyText.trim() ? bodyText.trim() : `HTTP ${status}`);
-    const code = parsed?.error_code != null ? ` (error_code: ${parsed.error_code})` : "";
+    const apiCode = parsed?.error_code != null ? String(parsed.error_code) : "";
+    const apiMsg = parsed?.error != null && String(parsed.error).trim()
+        ? String(parsed.error).trim()
+        : "";
+    let cause = "server";
+    let error_code = apiCode || `http_${status}`;
+    let message = apiMsg || `HTTP ${status}`;
+    let hint = "";
+    let retryable = status === 502 || status === 503 || status === 504;
     const accountHint = ` Regenerate or verify your key via ${PUBLIC_SITE_ORIGIN} if needed.`;
-    const hint = status === 400
-        ? " Check parameter types and required fields."
-        : status === 401
-            ? ` Check BARIVIA_API_KEY in your MCP config.${accountHint}`
-            : status === 403
-                ? ` Access denied — your plan does not include the CFD capability. Add the CFD capability at ${PUBLIC_SITE_ORIGIN}/dashboard to enable the barmesh tools.`
-                : status === 404
-                    ? " The resource may not exist or may have been deleted."
-                    : status === 409
-                        ? " The job may not be in the expected state."
-                        : status === 429
-                            ? " Plan limit or rate limit — read the error above; delete unused datasets or wait and retry."
-                            : status === 502
-                                ? " Object storage error from API — retry later."
-                                : status === 503
-                                    ? " API or database temporarily unavailable — retry later."
-                                    : status >= 500
-                                        ? " Server error — retry later."
-                                        : "";
-    const rid = ` (request id: ${requestId} — include if contacting support)`;
-    return `${detail}${code}${hint}${rid}`;
+    if (status === 400) {
+        cause = "client";
+        hint = "Check parameter types and required fields.";
+        retryable = false;
+    }
+    else if (status === 401) {
+        cause = "auth";
+        error_code = apiCode || "unauthorized";
+        hint = `Check BARIVIA_API_KEY in your MCP config.${accountHint}`;
+        retryable = false;
+    }
+    else if (status === 403) {
+        cause = "auth";
+        error_code = apiCode || "forbidden";
+        hint = `Access denied — your plan does not include the CFD capability. Add the CFD capability at ${PUBLIC_SITE_ORIGIN}/dashboard to enable the barmesh tools.`;
+        retryable = false;
+    }
+    else if (status === 404) {
+        cause = "client";
+        hint = "The resource may not exist or may have been deleted.";
+        retryable = false;
+    }
+    else if (status === 409) {
+        cause = "client";
+        hint = "The job may not be in the expected state.";
+        retryable = false;
+    }
+    else if (status === 429) {
+        cause = "rate_limit";
+        hint = "Plan limit or rate limit — delete unused datasets or wait and retry.";
+        retryable = true;
+    }
+    else if (status === 502 || status === 503 || status === 504) {
+        if (isStorageErrorCode(apiCode) || /object storage|r2\/s3|storage upload/i.test(apiMsg)) {
+            cause = "storage";
+            error_code = apiCode || "storage_upload_failed";
+            message = apiMsg || "Object storage (R2/S3) error from API.";
+            hint = "Retry later; feedback may still succeed via DB when storage is degraded.";
+        }
+        else if (html || !parsed) {
+            cause = "api_unreachable";
+            error_code = apiCode || "api_unreachable";
+            message = "Mesh analysis API temporarily unavailable (gateway/tunnel returned a non-JSON error).";
+            hint =
+                `Proxy already tried 3 times (~2s apart). Wait ~${UNAVAILABLE_RETRY_AFTER_SEC}s, then retry. ` +
+                    "Use barmesh_api_health — /health does not depend on R2. Keep reviewing last good distances/figures; do not paste HTML.";
+        }
+        else if (apiCode === "feedback_unavailable" || apiCode === "database_error") {
+            cause = "server";
+            error_code = apiCode;
+            message = apiMsg || "API or database temporarily unavailable.";
+            hint =
+                `Wait ~${UNAVAILABLE_RETRY_AFTER_SEC}s; barmesh_send_feedback queues locally if the API stays down.`;
+        }
+        else {
+            cause = "server";
+            message = apiMsg || `HTTP ${status}`;
+            hint = `API or database temporarily unavailable — wait ~${UNAVAILABLE_RETRY_AFTER_SEC}s, then retry.`;
+        }
+    }
+    else if (status >= 500) {
+        cause = "server";
+        hint = `Server error — wait ~${UNAVAILABLE_RETRY_AFTER_SEC}s, then retry.`;
+        retryable = true;
+    }
+    else if (!apiMsg && html) {
+        cause = "api_unreachable";
+        error_code = "api_unreachable";
+        message = `HTTP ${status} (non-JSON gateway body)`;
+        hint = `Wait ~${UNAVAILABLE_RETRY_AFTER_SEC}s, then retry. Do not paste HTML.`;
+        retryable = status >= 500;
+    }
+    const retry_after_sec = retryable ? UNAVAILABLE_RETRY_AFTER_SEC : undefined;
+    return {
+        status,
+        error_code,
+        message,
+        hint,
+        request_id: requestId,
+        retryable,
+        cause,
+        ...(retry_after_sec !== undefined ? { retry_after_sec } : {}),
+    };
+}
+/** User-visible API error line (slim; includes request id). Exported for tests. */
+export function formatApiErrorMessage(status, bodyText, requestId) {
+    const c = classifyApiError(status, bodyText, requestId);
+    const parts = [
+        c.message,
+        `error_code=${c.error_code}`,
+        `cause=${c.cause}`,
+        c.retry_after_sec != null ? `retry_after_sec=${c.retry_after_sec}` : "",
+        c.hint,
+        `request_id=${c.request_id}`,
+    ].filter((p) => p && String(p).trim());
+    return parts.join(" | ");
 }
 function throwApiError(status, bodyText, requestId) {
+    const classified = classifyApiError(status, bodyText, requestId);
     const err = new Error(formatApiErrorMessage(status, bodyText, requestId));
     err.httpStatus = status;
+    err.errorCode = classified.error_code;
+    err.requestId = requestId;
+    err.retryable = classified.retryable;
+    err.cause = classified.cause;
+    err.retryAfterSec = classified.retry_after_sec;
+    err.classified = classified;
     throw err;
 }
+/** Final network failure after the burst — same calm shape as gateway HTML 502. */
+function throwNetworkUnreachable(requestId, err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    const classified = {
+        status: 0,
+        error_code: "api_unreachable",
+        message: "Mesh analysis API temporarily unavailable (network error).",
+        hint: `Proxy already tried 3 times (~2s apart). Wait ~${UNAVAILABLE_RETRY_AFTER_SEC}s, then retry. ` +
+            `Detail: ${detail.slice(0, 120)}`,
+        request_id: requestId,
+        retryable: true,
+        cause: "api_unreachable",
+        retry_after_sec: UNAVAILABLE_RETRY_AFTER_SEC,
+    };
+    const msg = [
+        classified.message,
+        `error_code=${classified.error_code}`,
+        `cause=${classified.cause}`,
+        `retry_after_sec=${classified.retry_after_sec}`,
+        classified.hint,
+        `request_id=${classified.request_id}`,
+    ].join(" | ");
+    const out = new Error(msg);
+    out.httpStatus = 0;
+    out.errorCode = classified.error_code;
+    out.requestId = requestId;
+    out.retryable = true;
+    out.cause = "api_unreachable";
+    out.retryAfterSec = UNAVAILABLE_RETRY_AFTER_SEC;
+    out.classified = classified;
+    throw out;
+}
+/**
+ * Liveness (+ optional readiness) probe against the API origin.
+ * Uses GET /health which never touches R2 — safe during storage outages.
+ */
+export async function probeApiHealth() {
+    const base = { storage: "not_probed" };
+    try {
+        const live = await fetchWithTimeout(`${API_URL}/health`, { method: "GET" }, 8_000);
+        const liveText = await live.text();
+        if (!live.ok) {
+            return { ...base, liveness: "down", readiness: "unknown", detail: `health HTTP ${live.status}` };
+        }
+        let readiness = "unknown";
+        let db;
+        let redis;
+        try {
+            const ready = await fetchWithTimeout(`${API_URL}/ready`, { method: "GET" }, 8_000);
+            const readyText = await ready.text();
+            try {
+                const j = JSON.parse(readyText);
+                readiness = ready.ok && j.status === "ready" ? "ready" : "not_ready";
+                db = j.db;
+                redis = j.redis;
+            }
+            catch {
+                readiness = ready.ok ? "ready" : "not_ready";
+            }
+        }
+        catch {
+            readiness = "unknown";
+        }
+        void liveText;
+        return { ...base, liveness: "ok", readiness, db, redis };
+    }
+    catch (err) {
+        return {
+            ...base,
+            liveness: "down",
+            readiness: "unknown",
+            detail: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
 // ---- Distributed-trace context (W3C traceparent) ----
 // One trace per logical tool action (scoped via AsyncLocalStorage in registerAuditedTool),
 // so the API + job chain reconstruct end-to-end. Fresh span per API call; falls back to a
@@ -282,7 +538,7 @@ function _traceparentHeader() {
 export async function apiCall(method, pathPart, body, extraHeaders, requestTimeoutMs) {
     const url = `${API_URL}${pathPart}`;
     const contentType = extraHeaders?.["Content-Type"] ?? "application/json";
-    const requestId = Math.random().toString(36).slice(2, 10);
+    const requestId = newRequestId();
     const headers = {
         Authorization: `Bearer ${API_KEY}`,
         "Content-Type": contentType,
@@ -310,7 +566,17 @@ export async function apiCall(method, pathPart, body, extraHeaders, requestTimeo
             const text = await resp.text();
             if (!resp.ok) {
                 if (attempt < MAX_RETRIES && isTransientError(null, resp.status)) {
-                    await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
+                    const delayMs = retryDelayMs(attempt);
+                    logWarn("API retry", {
+                        rid: requestId,
+                        action: method,
+                        path: pathPart,
+                        attempt: attempt + 1,
+                        max_retries: MAX_RETRIES,
+                        delay_ms: delayMs,
+                        error_code: `http_${resp.status}`,
+                    });
+                    await new Promise((r) => setTimeout(r, delayMs));
                     continue;
                 }
                 logInfo("API response", { rid: requestId, outcome: "error", duration_ms: Date.now() - t0, error_code: `http_${resp.status}` });
@@ -322,21 +588,35 @@ export async function apiCall(method, pathPart, body, extraHeaders, requestTimeo
         catch (err) {
             lastError = err;
             if (attempt < MAX_RETRIES && isTransientError(err)) {
-                await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
+                const delayMs = retryDelayMs(attempt);
+                logWarn("API retry", {
+                    rid: requestId,
+                    action: method,
+                    path: pathPart,
+                    attempt: attempt + 1,
+                    max_retries: MAX_RETRIES,
+                    delay_ms: delayMs,
+                    error_code: err instanceof Error ? err.name : "fetch_error",
+                });
+                await new Promise((r) => setTimeout(r, delayMs));
                 continue;
             }
             if (err instanceof DOMException && err.name === "AbortError" && !err.httpStatus) {
                 throw new Error(`Request timed out after ${effectiveTimeout}ms. Increase BARIVIA_FETCH_TIMEOUT_MS (e.g. 120000) for slow or large requests. (request id: ${requestId})`);
             }
+            if (err instanceof TypeError)
+                throwNetworkUnreachable(requestId, err);
             throw err;
         }
     }
+    if (lastError instanceof TypeError)
+        throwNetworkUnreachable(requestId, lastError);
     throw lastError;
 }
 /** Fetch raw bytes from the API (for image downloads). */
 export async function apiRawCall(pathPart, requestTimeoutMs) {
     const url = `${API_URL}${pathPart}`;
-    const requestId = Math.random().toString(36).slice(2, 10);
+    const requestId = newRequestId();
     const effectiveTimeout = requestTimeoutMs ?? FETCH_TIMEOUT_MS;
     let lastError;
     for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
@@ -344,7 +624,16 @@ export async function apiRawCall(pathPart, requestTimeoutMs) {
             const resp = await fetchWithTimeout(url, { method: "GET", headers: { Authorization: `Bearer ${API_KEY}`, "X-Request-ID": requestId, traceparent: _traceparentHeader() } }, effectiveTimeout);
             if (!resp.ok) {
                 if (attempt < MAX_RETRIES && isTransientError(null, resp.status)) {
-                    await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
+                    const delayMs = retryDelayMs(attempt);
+                    logWarn("API retry", {
+                        rid: requestId,
+                        path: pathPart,
+                        attempt: attempt + 1,
+                        max_retries: MAX_RETRIES,
+                        delay_ms: delayMs,
+                        error_code: `http_${resp.status}`,
+                    });
+                    await new Promise((r) => setTimeout(r, delayMs));
                     continue;
                 }
                 const text = await resp.text();
@@ -359,15 +648,28 @@ export async function apiRawCall(pathPart, requestTimeoutMs) {
         catch (err) {
             lastError = err;
             if (attempt < MAX_RETRIES && isTransientError(err)) {
-                await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
+                const delayMs = retryDelayMs(attempt);
+                logWarn("API retry", {
+                    rid: requestId,
+                    path: pathPart,
+                    attempt: attempt + 1,
+                    max_retries: MAX_RETRIES,
+                    delay_ms: delayMs,
+                    error_code: err instanceof Error ? err.name : "fetch_error",
+                });
+                await new Promise((r) => setTimeout(r, delayMs));
                 continue;
             }
             if (err instanceof DOMException && err.name === "AbortError" && !err.httpStatus) {
                 throw new Error(`Image request timed out after ${effectiveTimeout}ms. Increase BARIVIA_FETCH_TIMEOUT_MS (e.g. 120000) for large images. (request id: ${requestId})`);
             }
+            if (err instanceof TypeError)
+                throwNetworkUnreachable(requestId, err);
             throw err;
         }
     }
+    if (lastError instanceof TypeError)
+        throwNetworkUnreachable(requestId, lastError);
     throw lastError;
 }
 // ---------------------------------------------------------------------------

package/dist/tools/barmesh_results_explorer.js

@@ -1,9 +1,11 @@
 import { z } from "zod";
 import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
-import { registerAuditedTool, runMcpToolAudit } from "../audit.js";
-import { apiCall, apiRawCall, getClientSupportsMcpApps, getVizPort, getCaptionForImage, mimeForFilename, structuredTextResult, tryAttachImage, } from "../shared.js";
+import { runMcpToolAudit } from "../audit.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 } },
     };
 }
@@ -178,9 +184,14 @@ export function registerResultsExplorerTool(server) {
         _meta: { ui: { resourceUri: RESULTS_EXPLORER_URI } },
     };
     registerAppTool(server, "barmesh_results_explorer", toolConfig, async (args) => runMcpToolAudit("barmesh_results_explorer", "default", args, () => handleResultsExplorer(String(args.job_id))));
-    registerAuditedTool(server, "_barmesh_fetch_figure", "[INTERNAL — host / MCP App only; agents MUST NOT call this.] The Mesh Convergence Results Explorer view uses it to lazy-load one raster figure as base64. From chat, use barmesh_results(action=get) or barmesh_results_explorer instead.", {
-        job_id: z.string(),
-        filename: z.string(),
+    registerAppTool(server, "_barmesh_fetch_figure", {
+        title: "Fetch figure (internal)",
+        description: "[INTERNAL — MCP App only; agents MUST NOT call.] Lazy-loads one raster figure as base64 for the Mesh Convergence Results Explorer.",
+        inputSchema: {
+            job_id: z.string(),
+            filename: z.string(),
+        },
+        _meta: { ui: { resourceUri: RESULTS_EXPLORER_URI, visibility: ["app"] } },
     }, async ({ job_id, filename }) => {
         const safeFilename = filename.replace(/[^a-zA-Z0-9._-]/g, "");
         const mime = mimeForFilename(safeFilename);