@barivia/barmesh-mcp 0.8.3 → 0.8.7

package/dist/job_monitor.js

@@ -35,14 +35,25 @@ function tailOrderingErrors(data, n = 4) {
 export function snapshotFromJob(data, elapsedSec, note) {
     const status = String(data.status ?? "unknown");
     const progress_pct = (data.progress ?? 0) * 100;
+    const kernelComplete = data.kernel_complete === true;
+    const awaitingFinalize = kernelComplete &&
+        status !== "completed" &&
+        status !== "failed" &&
+        status !== "cancelled";
     const snap = {
         elapsed_sec: elapsedSec,
         status,
-        progress_pct: Math.round(progress_pct * 10) / 10,
+        progress_pct: awaitingFinalize
+            ? Math.min(Math.round(progress_pct * 10) / 10, 99.0)
+            : Math.round(progress_pct * 10) / 10,
     };
     const phase = str(data, "progress_phase");
-    if (phase)
+    if (awaitingFinalize) {
+        snap.phase = phase && phase !== "complete" ? `${phase}+awaiting_finalize` : "awaiting_finalize";
+    }
+    else if (phase) {
         snap.phase = phase;
+    }
     const epoch = num(data, "epoch");
     const total = num(data, "total_epochs");
     if (epoch != null)
@@ -58,7 +69,7 @@ export function snapshotFromJob(data, elapsedSec, note) {
     const panelTe = num(data, "panel_topographic_error");
     if (panelTe != null)
         snap.panel_te = Math.round(panelTe * 10_000) / 10_000;
-    if (data.kernel_complete === true)
+    if (kernelComplete)
         snap.kernel_complete = true;
     const failureStage = str(data, "failure_stage");
     if (failureStage)
@@ -69,8 +80,12 @@ export function snapshotFromJob(data, elapsedSec, note) {
     const tail = tailOrderingErrors(data);
     if (tail && tail.length > 0)
         snap.ordering_errors_tail = tail;
-    if (note)
+    if (note) {
         snap.note = note;
+    }
+    else if (awaitingFinalize) {
+        snap.note = "kernel complete — awaiting finalize (not fully done)";
+    }
     return snap;
 }
 /** True when a new snapshot is worth recording (phase/epoch/progress/status change). */
@@ -96,7 +111,10 @@ export function shouldRecordSnapshot(prev, next) {
     return false;
 }
 export function formatSnapshotLine(s) {
-    const parts = [`[+${s.elapsed_sec}s] ${s.status} ${s.progress_pct.toFixed(1)}%`];
+    const progressLabel = s.kernel_complete && s.status !== "completed" && s.status !== "failed" && s.status !== "cancelled"
+        ? `kernel ${s.progress_pct.toFixed(1)}% (awaiting finalize)`
+        : `${s.progress_pct.toFixed(1)}%`;
+    const parts = [`[+${s.elapsed_sec}s] ${s.status} ${progressLabel}`];
     if (s.phase)
         parts.push(`phase ${s.phase}`);
     if (s.epoch != null && s.total_epochs != null)
@@ -107,8 +125,9 @@ export function formatSnapshotLine(s) {
         parts.push(`Epoch TE ${s.te.toFixed(4)}`);
     if (s.panel_te != null)
         parts.push(`Panel TE ${s.panel_te.toFixed(4)}`);
-    if (s.kernel_complete)
+    if (s.kernel_complete && (s.status === "completed" || s.status === "failed" || s.status === "cancelled")) {
         parts.push("kernel complete");
+    }
     if (s.failure_stage)
         parts.push(`failure_stage ${s.failure_stage}`);
     if (s.eta_sec != null)

package/dist/job_status_format.js

@@ -42,7 +42,12 @@ export async function formatJobStatusText(job_id, data) {
     const runConfig = formatRunConfigTable(data);
     if (runConfig)
         parts.push(runConfig);
-    parts.push(`${jobDesc}: ${status} (${progress.toFixed(1)}%)`);
+    const kernelComplete = data.kernel_complete === true;
+    const awaitingFinalize = kernelComplete && status !== "completed" && status !== "failed" && status !== "cancelled";
+    const progressBit = awaitingFinalize
+        ? `kernel ${Math.min(progress, 99).toFixed(1)}% — awaiting finalize`
+        : `${progress.toFixed(1)}%`;
+    parts.push(`${jobDesc}: ${status} (${progressBit})`);
     const attempt = data.attempt != null ? Number(data.attempt) : null;
     if (attempt != null && attempt > 1) {
         parts.push(`attempt ${attempt} (job was requeued after worker timeout — not stuck from scratch)`);

package/dist/shared.js

@@ -35,7 +35,7 @@ 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.8.3";
+export const CLIENT_VERSION = "0.8.7";
 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;
@@ -45,6 +45,94 @@ 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
+/** Normalize upload JSON after staging completes — never leave staging:true with train_ready. */
+function finalizeStagedUploadResponse(data, ready) {
+    const merged = ready
+        ? { ...data, ...ready }
+        : { ...data };
+    const trainReady = merged.train_ready === true || String(merged.status ?? "") === "ready";
+    if (trainReady) {
+        merged.status = ready?.status ?? merged.status ?? "ready";
+        merged.train_ready = true;
+        merged.staging = false;
+        if (ready?.stage_job_id == null)
+            delete merged.stage_job_id;
+    }
+    return merged;
+}
+/**
+ * After a small POST /v1/datasets upload, poll stage_job_id until the dataset is
+ * train-ready (mirrors the large-upload finalize path).
+ */
+export async function awaitDatasetStageIfNeeded(data) {
+    const stageJobId = data.stage_job_id != null ? String(data.stage_job_id) : "";
+    if (!stageJobId) {
+        if (data.train_ready === true || data.status === "ready") {
+            return finalizeStagedUploadResponse(data);
+        }
+        return data;
+    }
+    if (data.train_ready === true || data.status === "ready") {
+        return finalizeStagedUploadResponse(data);
+    }
+    const poll = await pollUntilComplete(stageJobId, POLL_STAGE_MAX_MS);
+    if (poll.status === "failed") {
+        throw new Error(`Dataset staging failed (stage_job_id=${stageJobId}): ${poll.error ?? "unknown error"}`);
+    }
+    if (poll.status === "timeout") {
+        throw new Error(`Dataset staging timed out after ${POLL_STAGE_MAX_MS / 60000} min (stage_job_id=${stageJobId}). Poll barmesh_jobs(action=status, job_id="${stageJobId}").`);
+    }
+    const datasetId = String(data.id ?? data.dataset_id ?? "");
+    if (datasetId) {
+        try {
+            const ready = (await apiCall("GET", `/v1/datasets/${datasetId}`));
+            return finalizeStagedUploadResponse(data, ready);
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    return finalizeStagedUploadResponse({ ...data, status: "ready", train_ready: true });
+}
+/**
+ * Before mesh_convergence submit: ensure the dataset has finished staging.
+ */
+export async function ensureDatasetTrainReady(datasetId) {
+    const ds = (await apiCall("GET", `/v1/datasets/${datasetId}`));
+    if (ds.train_ready === true)
+        return;
+    if (String(ds.status) === "failed") {
+        const err = ds.ingest_error != null ? String(ds.ingest_error) : "staging failed";
+        throw new Error(`Dataset ${datasetId} staging failed: ${err}`);
+    }
+    const stageJobId = ds.stage_job_id != null ? String(ds.stage_job_id) : "";
+    if (stageJobId) {
+        const poll = await pollUntilComplete(stageJobId, POLL_STAGE_MAX_MS);
+        if (poll.status === "failed") {
+            throw new Error(`Dataset staging failed (stage_job_id=${stageJobId}): ${poll.error ?? "unknown error"}`);
+        }
+        if (poll.status === "timeout") {
+            throw new Error(`Dataset staging timed out (stage_job_id=${stageJobId}). Poll barmesh_jobs(action=status, job_id="${stageJobId}").`);
+        }
+        return;
+    }
+    const deadline = Date.now() + 60_000;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 1000));
+        const again = (await apiCall("GET", `/v1/datasets/${datasetId}`));
+        if (again.train_ready === true)
+            return;
+        if (String(again.status) === "failed") {
+            const err = again.ingest_error != null ? String(again.ingest_error) : "staging failed";
+            throw new Error(`Dataset ${datasetId} staging failed: ${err}`);
+        }
+        if (again.stage_job_id != null) {
+            await ensureDatasetTrainReady(datasetId);
+            return;
+        }
+    }
+    throw new Error(`Dataset ${datasetId} is not train_ready (status=${ds.status ?? "?"}). Wait for staging or poll barmesh_datasets(action=get).`);
+}
 /** Map a local upload path to the API Content-Type (csv vs tsv; ignores .gz suffix). */
 export function resolveUploadContentType(filePath) {
     const lower = filePath.toLowerCase();
@@ -261,9 +349,48 @@ function enforceWorkspaceSandboxUpload() {
         return false;
     return true;
 }
+/** Extra realpath roots allowed for uploads (comma- or colon-separated absolute paths). */
+export function getWorkspaceExtraRoots() {
+    const raw = process.env.BARIVIA_WORKSPACE_EXTRA_ROOTS ?? "";
+    if (!raw.trim())
+        return [];
+    return raw
+        .split(/[,:]/)
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((s) => path.resolve(s));
+}
+async function realpathIfExists(p) {
+    try {
+        return await fs.realpath(p);
+    }
+    catch {
+        return null;
+    }
+}
+export async function isPathUnderSandboxRoots(realPath, workspaceRoot) {
+    const candidates = [workspaceRoot, ...getWorkspaceExtraRoots()];
+    for (const root of candidates) {
+        const realRoot = await realpathIfExists(root);
+        if (!realRoot)
+            continue;
+        if (realPath === realRoot || realPath.startsWith(realRoot + path.sep))
+            return true;
+    }
+    return false;
+}
+function sandboxEscapeError(realPath, workspaceRoot) {
+    const extras = getWorkspaceExtraRoots();
+    const extraHint = extras.length > 0
+        ? ` Also checked BARIVIA_WORKSPACE_EXTRA_ROOTS (${extras.join(", ")}).`
+        : " Set BARIVIA_WORKSPACE_EXTRA_ROOTS to allow shared fixture dirs, or copy the file into the workspace.";
+    return new Error(`Resolved path escapes workspace — symlink resolves outside BARIVIA_WORKSPACE_ROOT` +
+        ` (${workspaceRoot}). Target: ${realPath}.${extraHint}`);
+}
 /**
  * Resolve file_path for dataset upload. Rejects "..", enforces workspace sandbox
  * by default (set BARIVIA_ENFORCE_WORKSPACE_SANDBOX=0 to allow absolute paths).
+ * Symlink targets under BARIVIA_WORKSPACE_EXTRA_ROOTS are allowed when sandbox is on.
  */
 export async function resolveFilePathForUpload(filePath, mcpServer) {
     const trimmed = filePath.trim();
@@ -272,9 +399,8 @@ export async function resolveFilePathForUpload(filePath, mcpServer) {
     const checkUnder = async (p) => {
         const root = await getWorkspaceRootAsync(mcpServer);
         const real = await fs.realpath(p);
-        const realRoot = await fs.realpath(root);
-        if (real !== realRoot && !real.startsWith(realRoot + path.sep)) {
-            throw new Error(`Path outside the workspace is disabled (BARIVIA_ENFORCE_WORKSPACE_SANDBOX). Workspace root: ${realRoot}`);
+        if (!(await isPathUnderSandboxRoots(real, root))) {
+            throw sandboxEscapeError(real, root);
         }
         const stat = await fs.stat(real);
         if (!stat.isFile())
@@ -294,6 +420,9 @@ export async function resolveFilePathForUpload(filePath, mcpServer) {
     }
     const root = await getWorkspaceRootAsync(mcpServer);
     const resolved = path.resolve(root, trimmed);
+    if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+        throw new Error("Path must be within the workspace directory.");
+    }
     return checkUnder(resolved);
 }
 function looksLikeHtml(bodyText) {
@@ -357,7 +486,15 @@ export function classifyApiError(status, bodyText, requestId) {
     }
     else if (status === 409) {
         cause = "client";
-        hint = "The job may not be in the expected state.";
+        if (apiCode === "staging_not_ready") {
+            const stageId = parsed?.stage_job_id != null ? String(parsed.stage_job_id) : "";
+            hint = stageId
+                ? `Wait for stage_dataset to finish: barmesh_jobs(action=monitor, job_id="${stageId}"), then retry. Prefer barmesh_datasets(action=get) train_ready=true.`
+                : "Wait for dataset staging (status=ready with staged_prefix / train_ready=true), then retry.";
+        }
+        else {
+            hint = "The job may not be in the expected state.";
+        }
         retryable = false;
     }
     else if (status === 429) {
@@ -685,20 +822,65 @@ export function textResult(data) {
 }
 export async function pollUntilComplete(jobId, maxWaitMs = 30_000, intervalMs = 2000) {
     const start = Date.now();
+    /** Brief 404s happen when finalize_job_id is visible before the child row is readable. */
+    let notFoundStreak = 0;
+    const maxNotFoundRetries = 5;
     while (Date.now() - start < maxWaitMs) {
-        const data = (await apiCall("GET", `/v1/jobs/${jobId}`));
-        const status = data.status;
-        if (status === "completed" || status === "failed" || status === "cancelled") {
-            return {
-                status,
-                result_ref: data.result_ref,
-                error: data.error,
-            };
+        try {
+            const data = (await apiCall("GET", `/v1/jobs/${jobId}`));
+            notFoundStreak = 0;
+            const status = data.status;
+            if (status === "completed" || status === "failed" || status === "cancelled") {
+                return {
+                    status,
+                    result_ref: data.result_ref,
+                    error: data.error,
+                };
+            }
+        }
+        catch (err) {
+            const status = err?.httpStatus;
+            if (status === 404 && notFoundStreak < maxNotFoundRetries) {
+                notFoundStreak += 1;
+                await new Promise((r) => setTimeout(r, intervalMs));
+                continue;
+            }
+            throw err;
         }
         await new Promise((r) => setTimeout(r, intervalMs));
     }
     return { status: "timeout" };
 }
+const RESULTS_FIGURE_ENUMS = new Set(["default", "all", "none"]);
+/**
+ * Coerce host-stringified figures args (e.g. `'["all"]'`) and singleton enum arrays
+ * (`["all"]` → `"all"`) before Zod validation.
+ */
+export function coerceFiguresArg(v) {
+    if (v === undefined || v === null)
+        return v;
+    let val = v;
+    if (typeof val === "string") {
+        const trimmed = val.trim();
+        if ((trimmed.startsWith("[") && trimmed.endsWith("]")) ||
+            (trimmed.startsWith('"') && trimmed.endsWith('"'))) {
+            try {
+                val = JSON.parse(trimmed);
+            }
+            catch {
+                return v;
+            }
+        }
+    }
+    if (Array.isArray(val)) {
+        const asStrings = val.map((x) => String(x));
+        if (asStrings.length === 1 && RESULTS_FIGURE_ENUMS.has(asStrings[0])) {
+            return asStrings[0];
+        }
+        return asStrings;
+    }
+    return val;
+}
 // ---------------------------------------------------------------------------
 // Image helpers
 // ---------------------------------------------------------------------------

package/dist/tools/cfd.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
-import { apiCall, textResult, suggestAfterCfdSubmit } from "../shared.js";
+import { apiCall, ensureDatasetTrainReady, textResult, suggestAfterCfdSubmit } from "../shared.js";
 import { pollCfdPrepareIfPresent } from "../cfd_prepare.js";
 export function registerCfdTools(server) {
     registerAuditedTool(server, "barmesh_mesh_convergence", `Run SOM-based mesh-convergence analysis on an uploaded combined per-cell CSV.
@@ -53,6 +53,7 @@ COMMON MISTAKES: omitting feature_columns (required); choosing a reference_mesh
             body.description = description;
         if (tags !== undefined)
             body.tags = tags;
+        await ensureDatasetTrainReady(String(dataset_id));
         const data = (await apiCall("POST", "/v1/cfd/mesh-convergence", body));
         await pollCfdPrepareIfPresent(data, "barmesh_mesh_convergence");
         const id = data.id;

package/dist/tools/datasets.js

@@ -4,7 +4,7 @@ import { z } from "zod";
 import fs from "node:fs/promises";
 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 { apiCall, getWorkspaceRootAsync, resolveFilePathForUpload, textResult, pollUntilComplete, UPLOAD_DATASET_TIMEOUT_MS, LARGE_UPLOAD_BYTES, PRESIGNED_PUT_TIMEOUT_MS, POLL_STAGE_MAX_MS, awaitDatasetStageIfNeeded, streamFileSha256, putPresignedStream, resolveUploadContentType, suggestMeshDatasetPreview, } from "../shared.js";
 import { GZIP_UPLOAD_HINT } from "../upload_hints.js";
 import { formatDatasetInventoryLine, formatTags } from "../inventory_format.js";
 /**
@@ -178,7 +178,7 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
                         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 data = await awaitDatasetStageIfNeeded((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));
@@ -208,7 +208,7 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
                 uploadBody = gzipSync(Buffer.from(body, "utf-8"));
                 uploadHeaders["Content-Encoding"] = "gzip";
             }
-            const data = (await apiCall("POST", "/v1/datasets", uploadBody, uploadHeaders, UPLOAD_DATASET_TIMEOUT_MS));
+            const data = await awaitDatasetStageIfNeeded((await apiCall("POST", "/v1/datasets", uploadBody, uploadHeaders, UPLOAD_DATASET_TIMEOUT_MS)));
             const id = data.id ?? data.dataset_id;
             if (id != null) {
                 data.suggested_next_step = suggestMeshDatasetPreview(String(id));
@@ -259,16 +259,20 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
                 throw new Error("barmesh_datasets(get) requires dataset_id.");
             const ds = (await apiCall("GET", `/v1/datasets/${dataset_id}`));
             const tagStr = formatTags(ds.tags);
+            const trainReady = ds.train_ready === true;
             const lines = [
                 `Dataset: ${ds.name ?? "?"} (${ds.id ?? dataset_id})`,
-                `Status: ${ds.status ?? "ready"}`,
+                `Status: ${ds.status ?? "unknown"}`,
+                `Train ready: ${trainReady ? "yes" : "no"}`,
                 `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))` : "",
+                !trainReady && ds.stage_job_id != null
+                    ? `Stage job: ${String(ds.stage_job_id)} (poll barmesh_jobs(action=status) until train_ready)`
+                    : "",
                 cleanNullable(ds.ingest_error) ? `Ingest error: ${cleanNullable(ds.ingest_error)}` : "",
                 ds.created_at != null ? `Created: ${String(ds.created_at)}` : "",
             ].filter(Boolean);

package/dist/tools/results.js

@@ -2,7 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 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 { apiCall, apiRawCall, getWorkspaceRootAsync, sandboxPath, textResult, tryAttachImage, resetInlineAttachBudget, pollUntilComplete, POLL_STAGE_MAX_MS, suggestAfterRender, coerceFiguresArg, } 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"];
@@ -21,6 +21,18 @@ function formatMeshResultsSummary(jobId, data, summary) {
     const curveNote = (ord?.length ?? 0) > 0 || (conv?.length ?? 0) > 0
         ? `Training curves: ${ord?.length ?? 0} ordering + ${conv?.length ?? 0} convergence batch samples (≤1000 each in API/MCP responses).`
         : "";
+    const topDivs = summary.top_divergences;
+    const klComp = summary.feature_kl_complexity;
+    const topDivLine = topDivs && topDivs.length > 0
+        ? `Top feature-plane symmetric KL pairs (component association — not mesh SKL/EMD): ${topDivs
+            .map((t) => `${t.f1}&${t.f2}=${typeof t.symmetric_kl === "number" ? Number(t.symmetric_kl).toFixed(3) : t.symmetric_kl}`)
+            .join(", ")}`
+        : "";
+    const klComplexityLine = klComp && klComp.length > 0
+        ? `Feature KL complexity (mean outgoing): ${klComp
+            .map((t) => `${t.feature}=${typeof t.mean_outgoing_kl === "number" ? Number(t.mean_outgoing_kl).toFixed(3) : t.mean_outgoing_kl}`)
+            .join(", ")}`
+        : "";
     return [
         header,
         `Preset: ${String(summary.preset ?? "generic")} | Grid: ${grid.length >= 2 ? `${grid[0]}×${grid[1]}` : "N/A"} | Reference: ${String(summary.reference_mesh ?? "N/A")}`,
@@ -28,8 +40,13 @@ function formatMeshResultsSummary(jobId, data, summary) {
         meshes.length > 0 ? `\nDistances vs reference:\n${meshLines.join("\n")}` : "",
         stepLines.length > 0 ? `\nStepwise:\n${stepLines.join("\n")}` : "",
         readingLine ? `\nConvergence: ${readingLine}` : "",
+        topDivLine,
+        klComplexityLine,
         curveNote,
         "\nAdvisory: SOM distances complement, not replace, numerical uncertainty analysis (use barmesh_richardson for classical GCI).",
+        topDivLine || klComplexityLine
+            ? "Feature-plane KL (divergence_kl / feature_divergences.json) measures association between SOM component planes; mesh SKL/EMD measure fingerprint distance between meshes. Refresh or add W1 via barmesh_results(action=feature_divergences, metrics=[\"wasserstein\"])."
+            : "",
         "For every figure: barmesh_results_explorer(job_id) or barmesh_results(action=download). Use figures=\"none\" to skip inline images.",
     ].filter(Boolean).join("\n");
 }
@@ -40,6 +57,8 @@ const TEXT_ARTIFACTS = [
     "distances_to_ref.txt",
     "emd_stepwise.txt",
     "cfd_metrics.json",
+    "feature_divergences.json",
+    "weights.json",
     "richardson_gci.csv",
 ];
 export function registerResultsTool(server) {
@@ -47,29 +66,85 @@ export function registerResultsTool(server) {
 
 | Action | Use when |
 |--------|----------|
-| 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). |
+| get | Read the summary. mesh_convergence: distances + inline figures + feature-plane KL tops when present. richardson: triplet p/GCI table + topology_warning; see richardson_gci.csv. |
+| image | Download one figure by filename (e.g. KL_ref.png, combined.pdf, divergence_kl.png). |
 | 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). |
+| feature_divergences | Refresh feature-plane KL matrices / optional Wasserstein on SOM component planes (async; not mesh fingerprint KL). |
 
 BEST FOR: After barmesh_jobs(action=status) shows completed (and finalize finished if defer_figures was used).
-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).
+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 or divergence_kl. Prefer string figures="all" / "none" (not an array); arrays are for specific base names or filenames. Hosts that stringify arrays are coerced. action=get inlines the headline set; pass figures="all" for every artifact listed in summary.files, figures="none" for metrics only (recommended for agents).
+FEATURE-PLANE KL: mesh SKL/EMD (KL_ref, EMD_*) compare meshes; divergence_kl / feature_divergences.json compare SOM component planes (barsom-parallel). Finalize already writes symmetric KL; use action=feature_divergences for W1 or a refresh.
 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"),
+        action: z
+            .enum(["get", "image", "render", "download", "feature_divergences"])
+            .describe("get: summary + figures; image: one file; render: lazy PDF/SVG; download: save to disk; feature_divergences: feature-plane KL/W1 (async)."),
         job_id: z.string().describe("Job ID"),
         filename: z.string().optional().describe("For action=image: the figure filename (e.g. KL_ref.png or, after render, KL_ref.pdf)"),
         format: z.enum(["pdf", "png", "svg"]).optional().describe("For action=render: output format to generate (default pdf). PNG previews already exist by default."),
-        figures: z
+        figures: z.preprocess(coerceFiguresArg, z
             .union([z.enum(["default", "all", "none"]), z.array(z.string())])
             .optional()
-            .describe("For action=get/download: which figures (default headline panels; 'all'; 'none'; or a list of base names)"),
+            .describe("Prefer string 'all'/'none'. get/download: omit=headline panels; 'all'; 'none'; or array of base names/filenames. Stringified JSON arrays from hosts are accepted.")),
         folder: z.string().optional().describe("For action=download: directory to save into (relative to workspace). Files land in a per-job subfolder."),
         include_json: z.boolean().optional().describe("For action=download: also save summary.json and text/CSV artifacts"),
+        metrics: z
+            .array(z.enum(["symmetric_kl", "directed_kl", "wasserstein"]))
+            .optional()
+            .describe("action=feature_divergences: which matrices (default symmetric_kl+directed_kl). Add wasserstein for W1."),
+        wasserstein_method: z
+            .enum(["sinkhorn", "exact"])
+            .optional()
+            .describe("action=feature_divergences: OT solver when metrics includes wasserstein (default sinkhorn)."),
+        output_format: z.enum(["png", "pdf", "svg"]).optional().describe("action=feature_divergences: heatmap format (default png)."),
+        output_dpi: z.number().int().min(1).max(4).optional().describe("action=feature_divergences: PNG scale factor (default 2)."),
     }, async (args) => {
-        const { action, job_id, filename, format, figures, folder, include_json } = args;
+        const { action, job_id, filename, format, figures, folder, include_json, metrics: divergenceMetrics, wasserstein_method: wassersteinMethod, output_format, output_dpi, } = args;
+        if (action === "feature_divergences") {
+            const body = {
+                metrics: divergenceMetrics ?? ["symmetric_kl", "directed_kl"],
+                output_format: output_format ?? "png",
+                output_dpi: output_dpi ?? 2,
+            };
+            if (wassersteinMethod != null)
+                body.wasserstein_method = wassersteinMethod;
+            const data = (await apiCall("POST", `/v1/results/${job_id}/feature_divergences`, body));
+            const newJobId = data.id;
+            const poll = await pollUntilComplete(newJobId, POLL_STAGE_MAX_MS);
+            if (poll.status !== "completed") {
+                return textResult(`Feature divergences job ${newJobId} submitted (parent mesh job ${job_id}). Poll with barmesh_jobs(action=status, job_id="${newJobId}"), then barmesh_results(action=get, job_id="${job_id}").`);
+            }
+            const res = (await apiCall("GET", `/v1/results/${newJobId}`));
+            const sum = (res.summary ?? {});
+            const topDivs = sum.top_divergences ?? [];
+            const klComp = sum.feature_kl_complexity ?? [];
+            const topW1 = sum.top_wasserstein ?? null;
+            const lines = [
+                `Feature-plane divergences complete — job_id: ${newJobId} (parent mesh job: ${job_id})`,
+                `Method: ${sum.divergence_method ?? "symmetric_kl_min_shift_sum_norm_denormalized_component_planes"}`,
+                `Weight space: ${sum.weight_space ?? "denormalized"} (physical component planes)`,
+                `Metrics: ${JSON.stringify(sum.metrics ?? body.metrics)}`,
+                topDivs.length
+                    ? `Top symmetric KL pairs: ${topDivs.map((t) => `${t.f1}&${t.f2}=${typeof t.symmetric_kl === "number" ? Number(t.symmetric_kl).toFixed(3) : t.symmetric_kl}`).join(", ")}`
+                    : "",
+                klComp.length
+                    ? `KL complexity ranking: ${klComp.map((t) => `${t.feature}=${typeof t.mean_outgoing_kl === "number" ? Number(t.mean_outgoing_kl).toFixed(3) : t.mean_outgoing_kl}`).join(", ")}`
+                    : "",
+                topW1 && topW1.length
+                    ? `Top Wasserstein pairs: ${topW1.map((t) => `${t.f1}&${t.f2}=${typeof t.wasserstein === "number" ? Number(t.wasserstein).toFixed(3) : t.wasserstein}`).join(", ")}`
+                    : "",
+                `Artifacts refreshed on parent result (divergence_kl / feature_divergences.json). This is feature-plane association — distinct from mesh fingerprint SKL/EMD (KL_ref, EMD_*).`,
+            ].filter(Boolean);
+            const content = [{ type: "text", text: lines.join("\n") }];
+            const files = sum.files ?? [];
+            for (const f of files.filter((x) => /\.(png|svg)$/i.test(x))) {
+                await tryAttachImage(content, job_id, f);
+            }
+            return { content };
+        }
         if (action === "render") {
             const fmt = format ?? "pdf";
             const submit = (await apiCall("POST", "/v1/cfd/render", { job_id, format: fmt }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barivia/barmesh-mcp",
-  "version": "0.8.3",
+  "version": "0.8.7",
   "description": "barmesh MCP proxy — SOM-based CFD mesh-convergence and Richardson/GCI analysis on the Barivia cloud API",
   "keywords": [
     "mcp",