@barivia/barmesh-mcp 0.7.1 → 0.8.0

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,6 +17,8 @@ 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) {
@@ -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 } },

package/dist/ui-delivery.js

@@ -0,0 +1,155 @@
+/**
+ * Client-capability adaptation for barmesh MCP App tools.
+ * Mirrors barsom ui-delivery; uses barmesh viz paths via viz_links.
+ */
+import { getClientSupportsMcpApps, getVizPort, } from "./shared.js";
+import { buildBarmeshVizStandaloneUrl } from "./viz_links.js";
+export function parseUiDeliveryOverride() {
+    const raw = (process.env.BARIVIA_UI_DELIVERY ?? "auto").trim().toLowerCase();
+    if (raw === "apps" || raw === "localhost" || raw === "inline" || raw === "auto") {
+        return raw;
+    }
+    return "auto";
+}
+function vizPortPinned() {
+    return Boolean(process.env.BARIVIA_VIZ_PORT?.trim());
+}
+function viewForTool(tool) {
+    return tool === "training_monitor" ? "barmesh-training-monitor" : "barmesh-results-explorer";
+}
+export function buildStandaloneVizUrl(view, jobId) {
+    return buildBarmeshVizStandaloneUrl(viewForTool(view), jobId);
+}
+export function buildHealthUrl(jobId) {
+    const port = getVizPort();
+    if (!port)
+        return undefined;
+    const base = `http://localhost:${port}/api/health`;
+    return jobId ? `${base}?job_id=${encodeURIComponent(jobId)}` : base;
+}
+function hintForTier(tier, tool, opts) {
+    const label = tool === "training_monitor" ? "training monitor" : "results explorer";
+    switch (tier) {
+        case "embedded":
+            return `The ${label} MCP App panel may embed. Always mention the standalone URL — some hosts list ui:// but never mount widgets.`;
+        case "localhost":
+            return opts.standaloneUrl
+                ? `AGENT: Post a clickable markdown link (e.g. "[Open ${label}](${opts.standaloneUrl})") — do not bury it after metrics.`
+                : `AGENT: Viz server unavailable — use barmesh_jobs(status) and barmesh_results(get).`;
+        case "inline_image":
+            return `AGENT: Inline raster figure(s) are attached. Summarize metrics; offer barmesh_results_explorer for more figures.`;
+        case "text_only":
+            return `AGENT: No embedded panel or localhost viz — use barmesh_jobs(status) and barmesh_results(get).`;
+    }
+}
+export function resolveUiDelivery(options) {
+    const override = parseUiDeliveryOverride();
+    const mcpApps = getClientSupportsMcpApps();
+    const port = getVizPort() || null;
+    const standaloneUrl = buildStandaloneVizUrl(options.tool, options.jobId);
+    let delivery;
+    if (override === "apps") {
+        delivery = mcpApps ? "embedded" : port ? "localhost" : "text_only";
+    }
+    else if (override === "localhost") {
+        delivery = port ? "localhost" : options.inlineImageAttached ? "inline_image" : "text_only";
+    }
+    else if (override === "inline") {
+        delivery = options.inlineImageAttached ? "inline_image" : "text_only";
+    }
+    else if (mcpApps) {
+        delivery = "embedded";
+    }
+    else if (port) {
+        delivery = "localhost";
+    }
+    else if (options.inlineImageAttached) {
+        delivery = "inline_image";
+    }
+    else {
+        delivery = "text_only";
+    }
+    const urls = [];
+    if (standaloneUrl && (delivery === "embedded" || delivery === "localhost")) {
+        urls.push(standaloneUrl);
+    }
+    const healthUrl = buildHealthUrl(options.jobId);
+    if (healthUrl && delivery === "localhost") {
+        urls.push(healthUrl);
+    }
+    const crossLink = options.tool === "training_monitor" && options.jobStatus === "completed"
+        ? buildStandaloneVizUrl("results_explorer", options.jobId)
+        : options.tool === "results_explorer"
+            ? buildStandaloneVizUrl("training_monitor", options.jobId)
+            : undefined;
+    if (crossLink && !urls.includes(crossLink)) {
+        urls.push(crossLink);
+    }
+    return {
+        delivery,
+        urls: urls.length > 0 ? urls : undefined,
+        hint_for_agent: hintForTier(delivery, options.tool, { standaloneUrl }),
+        mcp_apps_supported: mcpApps,
+        viz_port: port,
+        port_pinned: vizPortPinned(),
+        override,
+    };
+}
+/** Prepend prominent standalone URL + structured ui_delivery (Apps handshake may lie). */
+export function appendUiDeliveryContent(content, block, options) {
+    const primary = options?.primaryUrl ?? block.urls?.[0];
+    const label = options?.linkLabel ?? "Open interactive view";
+    const prefix = [];
+    if (primary) {
+        const embedNote = block.delivery === "embedded"
+            ? "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.";
+        prefix.push({
+            type: "text",
+            text: `${embedNote}\n` +
+                `Standalone URL (copy if Open is blocked):\n${primary}\n` +
+                `[${label}](${primary})\n` +
+                `${block.hint_for_agent}`,
+        });
+    }
+    prefix.push({
+        type: "text",
+        text: "```json\n" + JSON.stringify({ ui_delivery: block }, null, 2) + "\n```",
+    });
+    if (primary && !block.port_pinned && block.delivery !== "text_only") {
+        prefix.push({
+            type: "text",
+            text: "Tip: set BARIVIA_VIZ_PORT in MCP env for a session-stable localhost port; re-run this tool if the page stops updating.",
+        });
+    }
+    content.unshift(...prefix);
+}
+export function getMcpClientDiagnostics() {
+    const override = parseUiDeliveryOverride();
+    const mcpApps = getClientSupportsMcpApps();
+    const port = getVizPort() || null;
+    let activeTier = "text_only";
+    if (override === "apps") {
+        activeTier = mcpApps ? "embedded" : port ? "localhost" : "text_only";
+    }
+    else if (override === "localhost") {
+        activeTier = port ? "localhost" : "text_only";
+    }
+    else if (override === "inline") {
+        activeTier = "inline_image";
+    }
+    else if (mcpApps) {
+        activeTier = "embedded";
+    }
+    else if (port) {
+        activeTier = "localhost";
+    }
+    return {
+        mcp_apps_supported: mcpApps,
+        viz_port: port,
+        viz_port_pinned: vizPortPinned(),
+        ui_delivery_override: override,
+        active_delivery_tier: activeTier,
+        health_url: buildHealthUrl(),
+    };
+}