@barivia/barmesh-mcp 0.5.4 → 0.6.1

package/dist/tools/training_monitor.js

@@ -1,56 +1,79 @@
 import { z } from "zod";
-import { registerAuditedTool } from "../audit.js";
-import { textResult } from "../shared.js";
-import { DEFAULT_BLOCK_UNTIL_SEC, DEFAULT_POLL_INTERVAL_SEC, formatMonitorText, monitorJob, } from "../job_monitor.js";
-const MONITOR_DESCRIPTION = `Block until a barmesh_mesh_convergence or barmesh_richardson job reaches a terminal state, emitting compact progress snapshots along the way.
-
-BEST FOR: After job submit — one call replaces manual barmesh_jobs(status) poll loops (10–20s × several minutes).
-ASYNC PROTOCOL: Server-side poll every ~5s (configurable) until completed/failed/cancelled or block_until timeout. Snapshots include phase, epoch/total, QE/TE, ETA, and ordering_errors tail when live.
-FINALIZE: When defer_figures is used, waits for cfd_finalize and adds a snapshot when figure render starts/completes.
-NOT REQUIRED: barmesh_jobs(action=status) still works for one-shot checks; this tool is the agent-friendly blocking variant (barsom training_monitor parity for headless workflows).
-ESCALATION: On timeout, re-run with a higher block_until_sec; on failed, read failure_stage in the final snapshot.`;
-const monitorSchema = {
-    job_id: z.string().describe("Job ID from barmesh_mesh_convergence or barmesh_richardson"),
-    block_until_sec: z
-        .number()
-        .int()
-        .min(30)
-        .optional()
-        .describe(`Max seconds to wait (default ${DEFAULT_BLOCK_UNTIL_SEC}; mesh jobs often need 6–10 min)`),
-    poll_interval_sec: z
-        .number()
-        .int()
-        .min(5)
-        .optional()
-        .describe(`Seconds between status polls (default ${DEFAULT_POLL_INTERVAL_SEC}; do not go below 5)`),
-    wait_finalize: z
-        .boolean()
-        .optional()
-        .describe("When true (default), wait for cfd_finalize after compute completes before returning"),
-};
-async function runMonitor(args) {
-    const block_until_sec = args.block_until_sec ?? DEFAULT_BLOCK_UNTIL_SEC;
-    const poll_interval_sec = args.poll_interval_sec ?? DEFAULT_POLL_INTERVAL_SEC;
-    const result = await monitorJob(args.job_id, {
-        block_until_sec,
-        poll_interval_sec,
-        wait_finalize: args.wait_finalize,
-    });
-    const text = formatMonitorText(result, { block_until_sec, poll_interval_sec });
-    return textResult({
-        ...result.data,
-        monitor: {
-            job_id: result.job_id,
-            terminal: result.terminal,
-            timed_out: result.timed_out,
-            snapshots: result.snapshots,
-            status_text: result.status_text,
-            suggested_next_step: result.suggested_next_step,
-        },
-        status_text: text,
-    });
+import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
+import { runMcpToolAudit } from "../audit.js";
+import { apiCall, getClientSupportsMcpApps, getVizPort, structuredTextResult, } from "../shared.js";
+import { enrichWithTrainingLog, needsTrainingLogEnrichment } from "../training_review.js";
+export const TRAINING_MONITOR_URI = "ui://barmesh/training-monitor";
+export const TRAINING_MONITOR_REFRESH_MS = 5000;
+function buildStructuredContent(job_id, data) {
+    const id = String(data.id ?? job_id);
+    return {
+        ...data,
+        type: "barmesh-training-monitor",
+        jobId: id,
+        id,
+        job_id: id,
+        refresh_interval_ms: TRAINING_MONITOR_REFRESH_MS,
+    };
 }
 export function registerTrainingMonitorTool(server) {
-    registerAuditedTool(server, "barmesh_training_monitor", MONITOR_DESCRIPTION, monitorSchema, runMonitor);
+    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.",
+        inputSchema: {
+            job_id: z.string().describe("Job ID from barmesh_mesh_convergence or barmesh_richardson"),
+            fetch_training_log: z
+                .boolean()
+                .optional()
+                .describe("Internal: merge completed-job training-log arrays when live progress is empty"),
+        },
+        _meta: { ui: { resourceUri: TRAINING_MONITOR_URI } },
+    }, async (args) => runMcpToolAudit("barmesh_training_monitor", "default", args, async () => {
+        const { job_id, fetch_training_log } = args;
+        let data = (await apiCall("GET", `/v1/jobs/${job_id}`));
+        const jobStatus = String(data.status ?? "");
+        const terminal = jobStatus === "completed" || jobStatus === "failed";
+        if (fetch_training_log || needsTrainingLogEnrichment(data)) {
+            data = await enrichWithTrainingLog(job_id, data);
+        }
+        const structuredContent = buildStructuredContent(job_id, data);
+        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;
+        const epoch = data.epoch != null ? Number(data.epoch) : null;
+        const totalEpochs = data.total_epochs != null ? Number(data.total_epochs) : null;
+        const timingParts = [];
+        if (elapsedSec != null && elapsedSec >= 0)
+            timingParts.push(`elapsed ${Math.round(elapsedSec)}s`);
+        if (etaSec != null && etaSec > 0)
+            timingParts.push(`ETA ~${Math.round(etaSec)}s`);
+        if (epoch != null && totalEpochs != null)
+            timingParts.push(`epoch ${epoch}/${totalEpochs}`);
+        const timingNote = timingParts.length > 0 ? ` ${timingParts.join(", ")}.` : "";
+        const modeNote = terminal ? " (post-hoc review — training-log curves)" : "";
+        const text = `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})`,
+            });
+        }
+        return {
+            ...structuredTextResult(structuredContent, text, content),
+            _meta: { ui: { resourceUri: TRAINING_MONITOR_URI } },
+        };
+    }));
 }
-export { runMonitor, MONITOR_DESCRIPTION, monitorSchema };

package/dist/training_monitor_curve.js

@@ -0,0 +1,60 @@
+/** Batch-sample x-axis helpers for the barmesh_training_monitor MCP App chart. */
+export function batchSampleAxis(n, offset = 0) {
+    if (n <= 0)
+        return [];
+    return Array.from({ length: n }, (_, i) => offset + i + 1);
+}
+export function combinedBatchAxis(nOrd, nConv) {
+    if (nOrd <= 0 && nConv <= 0)
+        return [];
+    return [...batchSampleAxis(nOrd, 0), ...batchSampleAxis(nConv, nOrd)];
+}
+export function formatCurveSourceNote(data) {
+    const src = data.training_curve_source_batches;
+    if (!src)
+        return null;
+    const parts = [];
+    const ordTotal = typeof src.ordering === "number" ? src.ordering : null;
+    const convTotal = typeof src.convergence === "number" ? src.convergence : null;
+    const ordShown = Array.isArray(data.ordering_errors) ? data.ordering_errors.length : 0;
+    const convShown = Array.isArray(data.convergence_errors) ? data.convergence_errors.length : 0;
+    if (ordTotal != null && ordTotal > ordShown) {
+        parts.push(`${ordShown} of ${ordTotal.toLocaleString()} ordering batch samples`);
+    }
+    if (convTotal != null && convTotal > convShown) {
+        parts.push(`${convShown} of ${convTotal.toLocaleString()} convergence batch samples`);
+    }
+    if (parts.length === 0)
+        return null;
+    return `Displaying uniformly subsampled QE+TE curves (≤1000 points/phase, joint indices): ${parts.join("; ")}.`;
+}
+/** Map TE onto QE batch axis; when batch-aligned (same length), use values directly. */
+export function alignTeToQeAxis(te, qeLen) {
+    if (qeLen <= 0)
+        return [];
+    if (te.length === qeLen)
+        return te;
+    if (te.length === 0)
+        return Array(qeLen).fill(null);
+    if (te.length >= qeLen)
+        return te.slice(0, qeLen);
+    const pad = qeLen - te.length;
+    return [...Array(pad).fill(null), ...te];
+}
+/**
+ * Last sampled TE point from the (batch-aligned) live TE curve. This is the most
+ * recent per-epoch TE estimate, distinct from the final trained-map TE in the summary.
+ */
+export function lastEpochTeFromCurves(data) {
+    const conv = data.convergence_topographic_errors;
+    if (Array.isArray(conv) && conv.length > 0) {
+        const v = Number(conv[conv.length - 1]);
+        return Number.isFinite(v) ? v : null;
+    }
+    const ord = data.ordering_topographic_errors;
+    if (Array.isArray(ord) && ord.length > 0) {
+        const v = Number(ord[ord.length - 1]);
+        return Number.isFinite(v) ? v : null;
+    }
+    return null;
+}

package/dist/training_review.js

@@ -0,0 +1,222 @@
+/**
+ * Post-hoc review mode for barmesh_training_monitor on already-terminal jobs.
+ * Replays QE curves from training-log and surfaces final timing/metrics.
+ */
+import { apiCall } from "./shared.js";
+import { formatSnapshotLine, snapshotFromJob, } from "./job_monitor.js";
+import { formatJobStatusText } from "./job_status_format.js";
+import { lastEpochTeFromCurves } from "./training_monitor_curve.js";
+export const REVIEW_MAX_SNAPSHOTS = 16;
+function isTerminalStatus(status) {
+    return status === "completed" || status === "failed" || status === "cancelled";
+}
+export function hasTeCurveArrays(data) {
+    const ord = data.ordering_topographic_errors;
+    const conv = data.convergence_topographic_errors;
+    return ((Array.isArray(ord) && ord.length > 0) || (Array.isArray(conv) && conv.length > 0));
+}
+function hasCurveArrays(data) {
+    const ord = data.ordering_errors;
+    const conv = data.convergence_errors;
+    return ((Array.isArray(ord) && ord.length > 0) ||
+        (Array.isArray(conv) && conv.length > 0) ||
+        hasTeCurveArrays(data));
+}
+/** True when a terminal job still needs training-log curves or the final map TE. */
+export function needsTrainingLogEnrichment(data) {
+    const status = String(data.status ?? "");
+    if (!isTerminalStatus(status))
+        return false;
+    if (!hasCurveArrays(data))
+        return true;
+    if (!hasTeCurveArrays(data))
+        return true;
+    if (data.map_topographic_error == null && data.topographic_error == null)
+        return true;
+    return false;
+}
+export async function enrichWithTrainingLog(job_id, data) {
+    const status = String(data.status ?? "");
+    const epochTe = data.epoch_topographic_error ??
+        data.topographic_error ??
+        lastEpochTeFromCurves(data);
+    try {
+        const log = (await apiCall("GET", `/v1/results/${job_id}/training-log`));
+        const merged = {
+            ...data,
+            ordering_errors: log.ordering_errors ?? data.ordering_errors,
+            convergence_errors: log.convergence_errors ?? data.convergence_errors,
+            ordering_topographic_errors: log.ordering_topographic_errors ?? data.ordering_topographic_errors,
+            convergence_topographic_errors: log.convergence_topographic_errors ?? data.convergence_topographic_errors,
+            quantization_error: log.quantization_error ?? data.quantization_error,
+            grid: log.grid ?? data.grid,
+            epochs: log.epochs ?? data.epochs,
+            training_duration_seconds: log.training_duration_seconds ?? data.training_duration_seconds,
+            training_curve_source_batches: log.training_curve_source_batches ?? data.training_curve_source_batches,
+        };
+        const mapTe = log.topographic_error ?? data.map_topographic_error ?? data.topographic_error;
+        merged.epoch_topographic_error = epochTe ?? lastEpochTeFromCurves(merged);
+        merged.map_topographic_error = mapTe;
+        if (isTerminalStatus(status)) {
+            merged.topographic_error = mapTe;
+        }
+        return merged;
+    }
+    catch {
+        if (epochTe != null) {
+            return { ...data, epoch_topographic_error: epochTe };
+        }
+        return data;
+    }
+}
+/** Evenly sample indices for a compact epoch/QE timeline in review mode. */
+export function sampleReviewIndices(length, maxPoints = REVIEW_MAX_SNAPSHOTS) {
+    if (length <= 0)
+        return [];
+    if (length <= maxPoints)
+        return Array.from({ length }, (_, i) => i);
+    const out = [];
+    for (let i = 0; i < maxPoints; i += 1) {
+        out.push(Math.round((i * (length - 1)) / (maxPoints - 1)));
+    }
+    return [...new Set(out)].sort((a, b) => a - b);
+}
+export function buildCurveSnapshots(ordering, convergence, orderingEpochs) {
+    const snaps = [];
+    const ordIdx = sampleReviewIndices(ordering.length);
+    for (const i of ordIdx) {
+        const qe = ordering[i];
+        if (qe == null || Number.isNaN(Number(qe)))
+            continue;
+        const epoch = ordering.length > 1 && orderingEpochs > 0
+            ? Math.max(1, Math.round(((i + 1) / ordering.length) * orderingEpochs))
+            : i + 1;
+        snaps.push({
+            elapsed_sec: 0,
+            status: "completed",
+            progress_pct: 100,
+            phase: "ordering",
+            epoch,
+            total_epochs: orderingEpochs > 0 ? orderingEpochs : undefined,
+            qe: Math.round(Number(qe) * 10_000) / 10_000,
+            note: i === ordIdx[ordIdx.length - 1] ? "ordering (review)" : undefined,
+        });
+    }
+    if (convergence.length > 0) {
+        const convIdx = sampleReviewIndices(convergence.length, Math.min(6, REVIEW_MAX_SNAPSHOTS));
+        for (const i of convIdx) {
+            const qe = convergence[i];
+            if (qe == null || Number.isNaN(Number(qe)))
+                continue;
+            snaps.push({
+                elapsed_sec: 0,
+                status: "completed",
+                progress_pct: 100,
+                phase: "convergence",
+                qe: Math.round(Number(qe) * 10_000) / 10_000,
+                note: i === convIdx[convIdx.length - 1] ? "convergence (review)" : undefined,
+            });
+        }
+    }
+    return snaps;
+}
+export function formatPhaseBreakdown(data) {
+    const epochs = data.epochs;
+    if (!epochs || epochs.length < 2)
+        return null;
+    const [ord, conv] = epochs;
+    const ordN = Array.isArray(data.ordering_errors) ? data.ordering_errors.length : 0;
+    const convN = Array.isArray(data.convergence_errors) ? data.convergence_errors.length : 0;
+    const parts = [`ordering ${ord} epoch(s)`];
+    if (ordN > 0)
+        parts.push(`${ordN} batch samples logged`);
+    if (conv > 0) {
+        parts.push(`convergence ${conv} epoch(s)`);
+        if (convN > 0)
+            parts.push(`${convN} batch samples`);
+    }
+    return parts.join(", ");
+}
+export function formatTimingSummary(data) {
+    const wall = data.wall_elapsed_sec != null && !Number.isNaN(Number(data.wall_elapsed_sec))
+        ? Math.round(Number(data.wall_elapsed_sec))
+        : null;
+    const kernel = data.kernel_elapsed_sec != null && !Number.isNaN(Number(data.kernel_elapsed_sec))
+        ? Math.round(Number(data.kernel_elapsed_sec))
+        : data.training_elapsed_sec != null && !Number.isNaN(Number(data.training_elapsed_sec))
+            ? Math.round(Number(data.training_elapsed_sec))
+            : data.training_duration_seconds != null
+                ? Math.round(Number(data.training_duration_seconds))
+                : null;
+    if (wall != null && kernel != null && Math.abs(wall - kernel) >= 2) {
+        return `wall ${wall}s, kernel training ${kernel}s`;
+    }
+    if (wall != null)
+        return `wall ${wall}s`;
+    if (kernel != null)
+        return `kernel training ${kernel}s`;
+    return null;
+}
+export function formatReviewMonitorText(result, review) {
+    const lines = [
+        `Job ${result.job_id} monitor (post-hoc review — job already ${result.data.status ?? "terminal"}):`,
+    ];
+    if (review.phaseBreakdown)
+        lines.push(`Phases: ${review.phaseBreakdown}`);
+    if (review.timing)
+        lines.push(`Timing: ${review.timing}`);
+    const qe = result.data.quantization_error;
+    const mapTe = result.data.map_topographic_error ?? result.data.topographic_error;
+    const epochTe = result.data.epoch_topographic_error;
+    if (qe != null || mapTe != null || epochTe != null) {
+        const qeS = qe != null ? `QE ${Number(qe).toFixed(4)}` : "";
+        const mapS = mapTe != null ? `Map TE ${Number(mapTe).toFixed(4)}` : "";
+        const epochS = epochTe != null &&
+            mapTe != null &&
+            Math.abs(Number(epochTe) - Number(mapTe)) > 0.0005
+            ? `Last epoch TE ${Number(epochTe).toFixed(4)}`
+            : epochTe != null && mapTe == null
+                ? `Epoch TE ${Number(epochTe).toFixed(4)}`
+                : "";
+        lines.push(`Final: ${[qeS, mapS, epochS].filter(Boolean).join(", ")}`);
+    }
+    lines.push("");
+    lines.push("Training curve (sampled from ordering_errors / convergence_errors):");
+    for (const s of result.snapshots)
+        lines.push(formatSnapshotLine(s));
+    lines.push("");
+    lines.push(`Terminal: ${result.status_text}`);
+    lines.push(result.suggested_next_step);
+    lines.push("Tip: learning_curve.png is attached when available; use barmesh_results_explorer for all figures.");
+    return lines.join("\n");
+}
+export async function buildPostHocReview(job_id, data, suggested_next_step) {
+    const enriched = await enrichWithTrainingLog(job_id, data);
+    const ordering = enriched.ordering_errors ?? [];
+    const convergence = enriched.convergence_errors ?? [];
+    const epochs = enriched.epochs ?? [];
+    const orderingEpochs = epochs.length > 0 ? Number(epochs[0]) || 0 : 0;
+    let snapshots = buildCurveSnapshots(ordering, convergence, orderingEpochs);
+    if (snapshots.length === 0) {
+        snapshots = [snapshotFromJob(enriched, 0, "post-hoc review (no training-log curves)")];
+    }
+    const statusText = await formatJobStatusText(job_id, enriched);
+    const phaseBreakdown = formatPhaseBreakdown(enriched);
+    const timing = formatTimingSummary(enriched);
+    const result = {
+        job_id,
+        terminal: true,
+        timed_out: false,
+        snapshots,
+        status_text: statusText,
+        data: { ...enriched, monitor_mode: "review" },
+        suggested_next_step,
+    };
+    result.data.status_text = formatReviewMonitorText(result, {
+        phaseBreakdown,
+        timing,
+        mode: "review",
+    });
+    return result;
+}
+export { isTerminalStatus, hasCurveArrays };