@barivia/barsom-mcp 0.23.10 → 0.23.12

package/README.md

@@ -1,8 +1,8 @@
 # @barivia/barsom-mcp
 
-MCP proxy for the Barivia Analytics Engine — connects any stdio MCP client (Cursor, Claude Desktop, etc.) to the barSOM cloud API. The npm package is **`@barivia/barsom-mcp`**; many configs label the server **`analytics-engine`** (the MCP server name in the client JSON). **`guide_barsom_workflow`** is the canonical bootstrap: it loads plan-scoped workflow text from the Barivia API when online (tool map, async rules, training modes, SOP). If the API is unreachable, it returns a short offline stub. Core tools are `datasets`, `train` (`map`, `siom_map`, `impute`, `floop_siom` where entitled), `jobs` (status/list/compare/cancel/delete — lifecycle only), `results` (get/export/download/recolor), and `inference` (predict/batch_predict/impute_column/compare/project_columns/transition_flow/report). **Optional MCP App tools** (`training_monitor`, `results_explorer`) add embedded or localhost viz; they are **not required** to complete upload → train → poll → results, though `results_explorer` is the preferred way to browse figures.
+MCP proxy for the Barivia Analytics Engine — connects any stdio MCP client (Cursor, Claude Desktop, etc.) to the barSOM cloud API. The npm package is **`@barivia/barsom-mcp`**; many configs label the server **`analytics-engine`** (the MCP server name in the client JSON). **`guide_barsom_workflow`** is the canonical bootstrap: it loads plan-scoped workflow text from the Barivia API when online (tool map, async rules, training modes, SOP). If the API is unreachable, it returns a short **connectivity-only** offline stub. Core tools are `datasets`, `train` (`map`, `siom_map`, `impute`, `floop_siom` where entitled), `jobs` (status/list/compare/cancel/delete — lifecycle only), `results` (get/export/download/recolor), and `inference` (predict/batch_predict/impute_column/compare/project_columns/transition_flow/report). **Optional MCP App tools** (`training_monitor`, `results_explorer`) add embedded or localhost viz; they are **not required** to complete upload → train → poll → results, though `results_explorer` is the preferred way to browse figures.
 
-**Pre-training help (pick one):** **`prepare_training`** prompt = narrative checklist (tier-scoped from the API when online); **`training_guidance`** tool = structured presets and parameter hints (including the resolved per-column normalization). Review either, then submit with **`train`**.
+**Pre-training help (pick one):** **`prepare_training`** prompt = narrative checklist (tier-scoped from the API when online); **`training_guidance`** tool = structured presets, quality/timing heuristics, and parameter hints (including resolved per-column normalization). Review either, then submit with **`train`**. Parameter encyclopedias and quality targets are **API-gated** (valid key + plan); the published proxy catalog keeps short routing text only.
 
 ## Installation
 
@@ -56,7 +56,8 @@ MCP clients typically run it with **`npx`** (downloads on first use):
 | `BARIVIA_WORKSPACE_EXTRA_ROOTS` | No | (empty) | Comma- or colon-separated absolute directories whose **realpath** targets are also allowed for uploads when the sandbox is on. Use for shared fixture trees reached via symlinks under the case workspace (e.g. `…/barivia-testing/data`). Does not weaken the default sandbox for paths outside these roots. |
 | `BARIVIA_FETCH_TIMEOUT_MS` | No | `60000` | Per-request HTTP timeout (ms) to the API. Increase (e.g. `120000`) on slow networks or when the API does long-running work. Large dataset uploads use a separate longer timeout internally, and `datasets(analyze)` runs asynchronously (auto-polled) so it is not bound by this. A timeout is not auto-retried (re-firing slow work would only multiply load / risk duplicates). |
 | `BARIVIA_VIZ_PORT` | No | OS-assigned | Local viz server on `127.0.0.1`. Port is **per MCP session** unless pinned — standalone `…/viz/…` URLs go stale after proxy restart. Set a fixed port for stable bookmark URLs. Diagnostic: `GET http://127.0.0.1:<port>/api/health?job_id=<id>`. |
-| `BARIVIA_UI_DELIVERY` | No | `auto` | Client-capability override for App tools: `auto` \| `apps` \| `localhost` \| `inline`. Tool responses always lead with a standalone localhost URL (hosts may list `ui://` without mounting widgets) and include a structured `ui_delivery` block. `account(status)` reports detected Apps support, viz port, and active tier. |
+| `BARIVIA_UI_DELIVERY` | No | `auto` | Client-capability override for App tools: `auto` \| `apps` \| `localhost` \| `inline` \| `text_only`. Tool responses always lead with a standalone localhost URL (hosts may list `ui://` without mounting widgets) and include a structured `ui_delivery` block. `account(status)` reports detected Apps support, viz port, and active tier. |
+| `BARIVIA_UI_PREFER_LOCALHOST` | No | (off) | Set `1` to force `localhost` under `auto` even when the host advertises MCP Apps (Cursor list-without-mount workaround). Default `auto` behavior unchanged. |
 | `BARIVIA_ENFORCE_WORKSPACE_SANDBOX` | No | `1` (enabled) | File uploads are constrained to the MCP workspace root (and optional `BARIVIA_WORKSPACE_EXTRA_ROOTS`) by default. Set to `0` or `false` to allow absolute paths anywhere on the machine (high trust). If uploads fail with "symlink resolves outside workspace", either point `BARIVIA_WORKSPACE_ROOT` / `BARIVIA_WORKSPACE_EXTRA_ROOTS` at the real data dir, copy the file into the workspace, or opt out with `BARIVIA_ENFORCE_WORKSPACE_SANDBOX=0`. |
 
 Legacy `BARSOM_API_KEY` / `BARSOM_API_URL` / `BARSOM_WORKSPACE_ROOT` are also accepted as fallbacks.
@@ -193,7 +194,7 @@ The right viewer depends on **(MCP App support)** **and** **(can the human reach
 ### Migration notes
 
 - **Results explorer figure dropdown (0.23.2):** `results_explorer` puts a grouped `<select>` above the plot (no scrolling the sidebar to switch figures), matching barmesh explorer UX. Sidebar keeps Metrics + Highlights only.
-- **UI delivery + train auto-open (0.22.4+):** `train()` returns `training_monitor` App structured content so supporting hosts open the monitor in the same turn. App tools emit structured `ui_delivery` (`delivery`, `urls`, `hint_for_agent`) and always put the standalone viz URL first. Env: `BARIVIA_UI_DELIVERY`, `BARIVIA_VIZ_PORT`. Cyclic cos/sin component PNGs are omitted from default `summary.files` / `figures=all` (encoding for training; panels still appear in `combined` / recolor); opt in with train param `viz_upload_cyclic_components=true`.
+- **UI delivery + train auto-open (0.22.4+ / 0.23.11+):** `train()` returns `training_monitor` App structured content so supporting hosts open the monitor in the same turn. App tools emit structured `ui_delivery` (`delivery`, `urls`, `hint_for_agent`) and always put the standalone viz URL first. Env: `BARIVIA_UI_DELIVERY` (`auto` \| `apps` \| `localhost` \| `inline` \| `text_only`), `BARIVIA_UI_PREFER_LOCALHOST=1` (opt-in localhost under `auto`), `BARIVIA_VIZ_PORT`. Cyclic cos/sin component PNGs are omitted from default `summary.files` / `figures=all` (encoding for training; panels still appear in `combined` / recolor); opt in with train param `viz_upload_cyclic_components=true`.
 - **Account surface (0.22.0, breaking):** `account(request_compute|compute_status|release_compute)` removed — AWS cloud burst leases are gone. Use `account(status|history|add_funds)`. Capacity is shared LOCAL/GKE pools.
 - **Structured results + train hints (0.21.x, non-breaking):**
   - **`results(action=get)`** returns **`structuredContent`** (job id/type, label, summary metrics, file list) alongside the text summary — same pattern as `training_monitor` / `results_explorer`. Agent hosts can read fields without parsing prose.

package/dist/audit.js

@@ -161,14 +161,20 @@ export async function runMcpToolAudit(tool, action, args, handler) {
 /**
  * Register an MCP tool with structured audit logging on each invocation.
  */
-export function registerAuditedTool(server, name, description, schema, handler) {
-    server.tool(name, description, schema, (async (args) => {
+export function registerAuditedTool(server, name, description, schema, handler, annotations) {
+    const cb = (async (args) => {
         const rec = args;
         const action = typeof rec.action === "string" && rec.action.length > 0 ? rec.action : "default";
         // One trace per tool invocation: every apiCall inside this handler shares one
         // trace_id, so the API + job chain reconstruct the whole logical action.
         return runWithTrace(() => runMcpToolAudit(name, action, rec, () => handler(args)));
-    }));
+    });
+    if (annotations) {
+        server.tool(name, description, schema, annotations, cb);
+    }
+    else {
+        server.tool(name, description, schema, cb);
+    }
 }
 /** Attach audit flags to a tool result (stripped before returning to MCP client). */
 export function withAuditFlags(result, flags) {

package/dist/figure_sections.js

@@ -0,0 +1,63 @@
+/**
+ * Canonical figure taxonomy for barsom results_explorer dropdown sections.
+ * Labels match the prior GROUP_LABELS (Summary → Diagnostics → Components → Other).
+ */
+export const FIGURE_SECTION_ORDER = [
+    "summary",
+    "diagnostic",
+    "component",
+    "artifact",
+];
+export const FIGURE_SECTION_LABELS = {
+    summary: "Summary",
+    diagnostic: "Diagnostics",
+    component: "Components",
+    artifact: "Other",
+};
+/** Map a figure base key into one of four explorer sections. */
+export function figureSection(key) {
+    if (key === "combined" || key === "coverage_overview")
+        return "summary";
+    if (key.startsWith("component_"))
+        return "component";
+    if (key === "umatrix" ||
+        key === "hit_histogram" ||
+        key === "learning_curve" ||
+        key === "correlation" ||
+        key === "divergence_kl" ||
+        key === "divergence_w1" ||
+        key.startsWith("cluster")) {
+        return "diagnostic";
+    }
+    if (key.startsWith("component"))
+        return "component";
+    return "artifact";
+}
+export const FIGURE_SORT_RANK = {
+    combined: 0,
+    coverage_overview: 1,
+    umatrix: 10,
+    hit_histogram: 11,
+    learning_curve: 12,
+    correlation: 13,
+    divergence_kl: 14,
+    divergence_w1: 15,
+};
+export function sortRank(key) {
+    if (key in FIGURE_SORT_RANK)
+        return FIGURE_SORT_RANK[key];
+    if (key.startsWith("component_")) {
+        const n = Number(key.replace(/^component_/, "").split("_")[0]);
+        return 20 + (Number.isFinite(n) ? n : 0);
+    }
+    if (key.startsWith("cluster"))
+        return 16;
+    return 50;
+}
+/** Sort by section order, then canonical rank, then label. */
+export function sortFiguresBySection(figures) {
+    return [...figures].sort((a, b) => FIGURE_SECTION_ORDER.indexOf(a.kind ?? figureSection(a.key)) -
+        FIGURE_SECTION_ORDER.indexOf(b.kind ?? figureSection(b.key)) ||
+        sortRank(a.key) - sortRank(b.key) ||
+        a.label.localeCompare(b.label));
+}

package/dist/index.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import{McpServer as e}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport as t}from"@modelcontextprotocol/sdk/server/stdio.js";import{z as o}from"zod";import{getUiCapability as r,registerAppResource as s,RESOURCE_MIME_TYPE as n}from"@modelcontextprotocol/ext-apps/server";import{startVizServer as a}from"./viz-server.js";import{API_KEY as i,apiCall as l,apiRawCall as c,loadViewHtml as p,setVizPort as m,setClientSupportsMcpApps as u,CLIENT_VERSION as d}from"./shared.js";import{registerDatasetsTool as f}from"./tools/datasets.js";import{registerTrainTool as _}from"./tools/train.js";import{registerJobsTool as g,JOBS_DESCRIPTION_BASE as h}from"./tools/jobs.js";import{registerResultsTool as b}from"./tools/results.js";import{registerExploreMapTool as w,RESULTS_EXPLORER_URI as y}from"./tools/explore_map.js";import{registerAccountTool as v}from"./tools/account.js";import{registerInferenceTool as j}from"./tools/inference.js";import{registerGuideBarsomTool as x}from"./tools/guide_barsom.js";import{registerTrainingGuidanceTool as k}from"./tools/training_guidance.js";import{registerFeedbackTool as I}from"./tools/feedback.js";import{registerTrainingMonitorTool as P,TRAINING_MONITOR_URI as A}from"./tools/training_monitor.js";import{resolvePrepareTrainingPrompt as S}from"./prepare_training_prompt.js";i||(console.error("Error: BARIVIA_API_KEY not set. Set it in your MCP client config."),process.exit(1));const T=new e({name:"analytics-engine",version:d,instructions:'# Barivia Mapping Analytics Engine\n\nSelf-organizing map (SOM) analytics via the Barivia API.\n\n## Bootstrap (do this first)\n\nCall `guide_barsom_workflow` for the plan-scoped tool map, training modes, async rules, and SOP (API when online). Call `training_guidance` / `prepare_training` for parameter and quality hints before guessing knobs.\n\n## Workflow (short)\n\n`datasets(upload)` → preview/analyze → `train(action=...)` (only modes your plan allows) → poll `jobs(status)` every 10–15s → `results(get)` then optional `results_explorer`. Scoring and frozen-map ops live in `inference`.\n\n## Tool taxonomy (one tool per stage)\n\n| Stage | Tool(s) |\n|-------|---------|\n| Data | `datasets` |\n| Train submit | `train` (map / siom_map / impute / floop_siom where entitled) |\n| Lifecycle | `jobs` (status/list/compare/cancel/delete — no train/score) |\n| Artifacts | `results` (get/export/download/recolor) |\n| Frozen-map ops | `inference` (predict/batch_predict/impute_column/compare/project_columns/transition_flow/report) |\n| Account | `account` (status/inventory/health) |\n| Bootstrap | `guide_barsom_workflow`, `training_guidance`, `prepare_training` |\n| Explore (UI) | `results_explorer`, `training_monitor` |\n| Feedback | `send_feedback` (after user agrees) |\n\n### Avoid these mis-routes\n- `jobs(compare)` = metrics across **training runs**. `inference(compare)` = density-diff vs a **second dataset**.\n- Post-training analysis is `inference`, not `results` (presentation/artifacts only).\n- Project columns → `inference(project_columns)`; formula → `datasets(add_expression, project_onto_job=...)`.\n\n## Async & constraints\n\n- Training returns `job_id` immediately — poll `jobs(status)` every 10–15s; running is not failed.\n- **Do not auto-subset** unless the user asks. Prefer `results(get, figures="none")` for sweeps.\n- Column names are case-sensitive. After recolor/transition_flow/project_columns, use the **new** job_id when returned.\n- On `api_unreachable`: one calm sentence, honor `retry_after_sec`; use `account(health)`. Timeouts are not auto-retried.\n\n## UI delivery\n\nTool results lead with a localhost viz URL and a structured `ui_delivery` block — follow `hint_for_agent`. Env: `BARIVIA_UI_DELIVERY`, `BARIVIA_VIZ_PORT`. Details: `account(status)`.'});s(T,y,y,{mimeType:n},async()=>{const e=await p("results-explorer");return{contents:[{uri:y,mimeType:n,text:e??"<html><body>Results Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),s(T,A,A,{mimeType:n},async()=>{const e=await p("training-monitor");return{contents:[{uri:A,mimeType:n,text:e??"<html><body>Training Monitor view not built yet.</body></html>"}]}}),x(T),w(T),P(T),f(T),_(T),g(T,h),b(T),v(T),j(T),k(T),I(T),T.prompt("info","Short orientation for the Barivia Mapping MCP. For full plan-scoped workflow, tool map, and SOP, the model should call guide_barsom_workflow. Use when the user asks what this MCP can do or how to get started.",{},()=>({messages:[{role:"user",content:{type:"text",text:["Give a concise, scannable answer (headers + bullets):","","**What it is:** MCP client to the Barivia mapping engine (2D SOM / SIOM / FLooP-SIOM when entitled) over HTTPS.","","**First step:** Call `guide_barsom_workflow` for plan-scoped bootstrap (full tool list, async rules, training modes, optional MCP Apps, SOP).","","**Core path:** `datasets(upload)` → `datasets(preview)` + `datasets(analyze)` → choose training action → poll `jobs(status)` every 10–15s until completed → `results(get)` (all main figures/metrics; no separate analyze tool) → `results_explorer(job_id)` to browse figures.","",'**Key tools:** `datasets` (data; reduce_spectral for spectra/long blocks), `train` (map; siom_map/impute with SIOM entitlement; floop_siom when entitled; pass `label` for readable compare rows; preset=quick for a fast first map), `jobs` (status/list/compare/cancel/delete — lifecycle only), `results` (get/download/export/recolor; figures="none" for metrics-only), `inference` (predict; batch_predict; impute_column for topology-neighbor pool fill; compare; project_columns; transition_flow; report), `account` (status/credits/queue).',"","**Prep help:** `prepare_training` prompt (checklist) · `training_guidance` (presets/JSON hints + resolved normalization/params) — review, then submit with `train`.","","**Browse results:** `results_explorer(job_id)` is the preferred way to explore figures after a first `results(get)` glance; `training_monitor` shows live progress. Both optional — `results` + `jobs(status)` suffice headless.","","**After training:** `jobs(compare)` across runs, `results(recolor)`, `inference(project_columns)` for variables not in training, `inference(transition_flow)` only if rows are time-ordered.","","**Rules:** Running ≠ failed. Column names must match `datasets(preview)` exactly. Do not auto-subset — never call `datasets(subset)` / `sample_n` unless the user explicitly asks; train on the full uploaded `dataset_id`. Do not call `_fetch_figure` from chat (host/UI only); use `results(get)` or `results_explorer`.","","Offer `send_feedback` only after asking the user."].join("\n")}}]})),T.prompt("prepare_training","Narrative pre-training checklist (prompt). Use after upload and before train. Content is tier-scoped from the API when online. Prep ladder: this prompt = story checklist; training_guidance tool = JSON presets/parameter hints. Review, then submit with train.",{dataset_id:o.string().describe("Dataset ID to prepare for training")},async({dataset_id:e})=>{const t=await S(e);return{messages:[{role:"user",content:{type:"text",text:(t.used_fallback?`[offline fallback ${t.fallback_version}]\n\n`:"")+t.text}}]}});const C=new t;(async function(){try{const e=await a(l,c,p);m(e)}catch(e){process.env.BARIVIA_VIZ_PORT&&console.error("Barivia viz server failed to start:",e)}const e=T.server;e.oninitialized=()=>{const t=e.getClientCapabilities(),o=r(t);u(!!o?.mimeTypes?.includes(n))},await T.connect(C)})().catch(console.error);
+import{McpServer as e}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport as t}from"@modelcontextprotocol/sdk/server/stdio.js";import{z as o}from"zod";import{getUiCapability as r,registerAppResource as s,RESOURCE_MIME_TYPE as n}from"@modelcontextprotocol/ext-apps/server";import{startVizServer as a}from"./viz-server.js";import{API_KEY as i,apiCall as l,apiRawCall as c,loadViewHtml as p,setVizPort as m,setClientSupportsMcpApps as u,CLIENT_VERSION as d}from"./shared.js";import{registerDatasetsTool as f}from"./tools/datasets.js";import{registerTrainTool as _}from"./tools/train.js";import{registerJobsTool as g,JOBS_DESCRIPTION_BASE as h}from"./tools/jobs.js";import{registerResultsTool as b}from"./tools/results.js";import{registerExploreMapTool as w,RESULTS_EXPLORER_URI as y}from"./tools/explore_map.js";import{registerAccountTool as v}from"./tools/account.js";import{registerInferenceTool as j}from"./tools/inference.js";import{registerGuideBarsomTool as x}from"./tools/guide_barsom.js";import{registerTrainingGuidanceTool as k}from"./tools/training_guidance.js";import{registerFeedbackTool as I}from"./tools/feedback.js";import{registerTrainingMonitorTool as A,TRAINING_MONITOR_URI as P}from"./tools/training_monitor.js";import{resolvePrepareTrainingPrompt as S}from"./prepare_training_prompt.js";i||(console.error("Error: BARIVIA_API_KEY not set. Set it in your MCP client config."),process.exit(1));const T=new e({name:"analytics-engine",version:d,instructions:'# Barivia Mapping Analytics Engine\n\nSelf-organizing map (SOM) analytics via the Barivia API.\n\n## Bootstrap (do this first)\n\nCall `guide_barsom_workflow` for the plan-scoped tool map, training modes, async rules, and SOP (API when online). Call `training_guidance` / `prepare_training` for parameter and quality hints before guessing knobs.\n\n## Workflow (short)\n\n`datasets(upload)` → preview/analyze → `train(action=...)` (only modes your plan allows) → poll `jobs(status)` every 10–15s → `results(get)` then optional `results_explorer`. Scoring and frozen-map ops live in `inference`.\n\n## Tool taxonomy (one tool per stage)\n\n| Stage | Tool(s) |\n|-------|---------|\n| Data | `datasets` |\n| Train submit | `train` (map / siom_map / impute / floop_siom where entitled) |\n| Lifecycle | `jobs` (status/list/compare/cancel/delete — no train/score) |\n| Artifacts | `results` (get/export/download/recolor) |\n| Frozen-map ops | `inference` (predict/batch_predict/impute_column/compare/project_columns/transition_flow/report) |\n| Account | `account` (status/inventory/health) |\n| Bootstrap | `guide_barsom_workflow`, `training_guidance`, `prepare_training` |\n| Explore (UI) | `results_explorer`, `training_monitor` |\n| Feedback | `send_feedback` (after user agrees) |\n\n### Avoid these mis-routes\n- `jobs(compare)` = metrics across **training runs**. `inference(compare)` = density-diff vs a **second dataset**.\n- Post-training analysis is `inference`, not `results` (presentation/artifacts only).\n- Project columns → `inference(project_columns)`; formula → `datasets(add_expression, project_onto_job=...)`.\n\n## Async & constraints\n\n- Training returns `job_id` immediately — poll `jobs(status)` every 10–15s; running is not failed.\n- **Do not auto-subset** unless the user asks. Prefer `results(get, figures="none")` for sweeps.\n- Column names are case-sensitive. After recolor/transition_flow/project_columns, use the **new** job_id when returned.\n- On `api_unreachable`: one calm sentence, honor `retry_after_sec`; use `account(health)`. Timeouts are not auto-retried.\n\n## UI delivery\n\nTool results lead with a localhost viz URL and a structured `ui_delivery` block — follow `hint_for_agent`. Env: `BARIVIA_UI_DELIVERY` (auto|apps|localhost|inline|text_only), `BARIVIA_UI_PREFER_LOCALHOST=1` (opt-in localhost even when Apps advertised), `BARIVIA_VIZ_PORT`. Details: `account(status)`.'});s(T,y,y,{mimeType:n},async()=>{const e=await p("results-explorer");return{contents:[{uri:y,mimeType:n,text:e??"<html><body>Results Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),s(T,P,P,{mimeType:n},async()=>{const e=await p("training-monitor");return{contents:[{uri:P,mimeType:n,text:e??"<html><body>Training Monitor view not built yet.</body></html>"}]}}),x(T),w(T),A(T),f(T),_(T),g(T,h),b(T),v(T),j(T),k(T),I(T),T.prompt("info","Short orientation for the Barivia Mapping MCP. For full plan-scoped workflow, tool map, and SOP, the model should call guide_barsom_workflow. Use when the user asks what this MCP can do or how to get started.",{},()=>({messages:[{role:"user",content:{type:"text",text:["Give a concise, scannable answer (headers + bullets):","","**What it is:** MCP client to the Barivia mapping engine (2D SOM / SIOM / FLooP-SIOM when entitled) over HTTPS.","","**First step:** Call `guide_barsom_workflow` for plan-scoped bootstrap (full tool list, async rules, training modes, optional MCP Apps, SOP).","","**Core path:** `datasets(upload)` → `datasets(preview)` + `datasets(analyze)` → choose training action → poll `jobs(status)` every 10–15s until completed → `results(get)` (all main figures/metrics; no separate analyze tool) → `results_explorer(job_id)` to browse figures.","",'**Key tools:** `datasets` (data; reduce_spectral for spectra/long blocks), `train` (map; siom_map/impute with SIOM entitlement; floop_siom when entitled; pass `label` for readable compare rows; preset=quick for a fast first map), `jobs` (status/list/compare/cancel/delete — lifecycle only), `results` (get/download/export/recolor; figures="none" for metrics-only), `inference` (predict; batch_predict; impute_column for topology-neighbor pool fill; compare; project_columns; transition_flow; report), `account` (status/credits/queue).',"","**Prep help:** `prepare_training` prompt (checklist) · `training_guidance` (presets/JSON hints + resolved normalization/params) — review, then submit with `train`.","","**Browse results:** `results_explorer(job_id)` is the preferred way to explore figures after a first `results(get)` glance; `training_monitor` shows live progress. Both optional — `results` + `jobs(status)` suffice headless.","","**After training:** `jobs(compare)` across runs, `results(recolor)`, `inference(project_columns)` for variables not in training, `inference(transition_flow)` only if rows are time-ordered.","","**Rules:** Running ≠ failed. Column names must match `datasets(preview)` exactly. Do not auto-subset — never call `datasets(subset)` / `sample_n` unless the user explicitly asks; train on the full uploaded `dataset_id`. Do not call `_fetch_figure` from chat (host/UI only); use `results(get)` or `results_explorer`.","","Offer `send_feedback` only after asking the user."].join("\n")}}]})),T.prompt("prepare_training","Narrative pre-training checklist (prompt). Use after upload and before train. Content is tier-scoped from the API when online. Prep ladder: this prompt = story checklist; training_guidance tool = JSON presets/parameter hints. Review, then submit with train.",{dataset_id:o.string().describe("Dataset ID to prepare for training")},async({dataset_id:e})=>{const t=await S(e);return{messages:[{role:"user",content:{type:"text",text:(t.used_fallback?`[offline fallback ${t.fallback_version}]\n\n`:"")+t.text}}]}});const O=new t;(async function(){try{const e=await a(l,c,p);m(e)}catch(e){process.env.BARIVIA_VIZ_PORT&&console.error("Barivia viz server failed to start:",e)}const e=T.server;e.oninitialized=()=>{const t=e.getClientCapabilities(),o=r(t);u(!!o?.mimeTypes?.includes(n))},await T.connect(O)})().catch(console.error);

package/dist/job_monitor.js

@@ -10,6 +10,9 @@ export const DEFAULT_BLOCK_UNTIL_SEC = 900;
 export const DEFAULT_POLL_INTERVAL_SEC = 5;
 export const MIN_POLL_INTERVAL_SEC = 5;
 export const HEARTBEAT_POLLS = 1;
+/** After this many unchanged polls, gently raise interval (never below MIN_POLL). */
+export const IDLE_BACKOFF_AFTER_POLLS = 8;
+export const MAX_POLL_INTERVAL_SEC = 15;
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
@@ -218,12 +221,22 @@ export async function monitorJob(job_id, options = {}) {
     let lastSnap = null;
     let data = {};
     let heartbeat = 0;
+    let idleStreak = 0;
     while (Date.now() - start < blockMs) {
         data = (await apiCall("GET", `/v1/jobs/${job_id}`));
         const elapsedSec = Math.round((Date.now() - start) / 1000);
         const snap = snapshotFromJob(data, elapsedSec);
         heartbeat += 1;
         const heartbeatDue = heartbeat >= HEARTBEAT_POLLS;
+        const unchanged = lastSnap != null &&
+            lastSnap.status === snap.status &&
+            lastSnap.progress_pct === snap.progress_pct &&
+            lastSnap.phase === snap.phase &&
+            lastSnap.epoch === snap.epoch;
+        if (unchanged)
+            idleStreak += 1;
+        else
+            idleStreak = 0;
         if (shouldRecordSnapshot(lastSnap, snap) || heartbeatDue) {
             snapshots.push(snap);
             lastSnap = snap;
@@ -233,7 +246,13 @@ export async function monitorJob(job_id, options = {}) {
         if (status === "completed" || status === "failed" || status === "cancelled") {
             break;
         }
-        await sleep(pollMs);
+        // Gentle backoff on idle polls — raise interval, never below the 5s floor.
+        let waitMs = pollMs;
+        if (idleStreak >= IDLE_BACKOFF_AFTER_POLLS) {
+            const steps = Math.floor((idleStreak - IDLE_BACKOFF_AFTER_POLLS) / 2);
+            waitMs = Math.min(pollMs + steps * 5000, MAX_POLL_INTERVAL_SEC * 1000);
+        }
+        await sleep(Math.max(MIN_POLL_INTERVAL_SEC * 1000, waitMs));
     }
     const status = String(data.status ?? "");
     const terminal = status === "completed" || status === "failed" || status === "cancelled";

package/dist/shared.js

@@ -27,10 +27,37 @@ export const RETRY_BASE_MS = parseInt(process.env.BARIVIA_RETRY_BASE_MS ?? "2000
 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) {
+/**
+ * Delay between burst retries. Keeps the flat RETRY_BASE_MS default (short gateway
+ * blips); when the server sends Retry-After / retry_after_sec, sleep at least that long.
+ */
+export function retryDelayMs(_attempt, retryAfterMs) {
+    if (retryAfterMs != null && Number.isFinite(retryAfterMs) && retryAfterMs > 0) {
+        return Math.max(RETRY_BASE_MS, Math.floor(retryAfterMs));
+    }
     return RETRY_BASE_MS;
 }
+/** Parse Retry-After header (delta-seconds) and/or JSON body retry_after_sec → ms. */
+export function parseRetryAfterMs(resp, bodyText) {
+    const header = resp.headers.get("Retry-After");
+    if (header) {
+        const sec = parseInt(header.trim(), 10);
+        if (!Number.isNaN(sec) && sec >= 0)
+            return sec * 1000;
+    }
+    if (bodyText) {
+        try {
+            const j = JSON.parse(bodyText);
+            const sec = Number(j.retry_after_sec);
+            if (Number.isFinite(sec) && sec >= 0)
+                return sec * 1000;
+        }
+        catch {
+            /* not JSON */
+        }
+    }
+    return undefined;
+}
 function newRequestId() {
     return randomUUID();
 }
@@ -39,7 +66,7 @@ function newRequestId() {
  * X-Barsom-Client-Version so the server can annotate tool guidance with the
  * wrapper version each action requires. Keep in sync with package.json on bump.
  */
-export const CLIENT_VERSION = "0.23.10";
+export const CLIENT_VERSION = "0.23.12";
 /** User-facing links; keep aligned with barivia.se / api.barivia.se. */
 export const PUBLIC_SITE_ORIGIN = "https://barivia.se";
 /** Self-serve account dashboard (manage plan, billing, and API keys). */
@@ -244,7 +271,11 @@ export function isTransientError(err, status) {
         return true; // network-level fetch failure
     return false;
 }
-/** Streaming SHA-256 of a file (for idempotency keys) without reading it into memory. */
+/**
+ * Streaming SHA-256 of a file without reading it into memory.
+ * Used by tools/datasets.ts upload as Idempotency-Key = sha256(name+body) — do not
+ * invent a second key path here.
+ */
 export async function streamFileSha256(srcPath) {
     return new Promise((resolve, reject) => {
         const h = createHash("sha256");
@@ -814,7 +845,7 @@ export async function apiCall(method, path, body, extraHeaders, requestTimeoutMs
             const text = await resp.text();
             if (!resp.ok) {
                 if (attempt < MAX_RETRIES && isTransientError(null, resp.status)) {
-                    const delayMs = retryDelayMs(attempt);
+                    const delayMs = retryDelayMs(attempt, parseRetryAfterMs(resp, text));
                     logWarn("API retry", {
                         rid: requestId,
                         method,
@@ -845,7 +876,10 @@ export async function apiCall(method, path, body, extraHeaders, requestTimeoutMs
         catch (err) {
             lastError = err;
             if (attempt < MAX_RETRIES && isTransientError(err)) {
-                const delayMs = retryDelayMs(attempt);
+                const errRetryMs = typeof err.retryAfterSec === "number"
+                    ? err.retryAfterSec * 1000
+                    : undefined;
+                const delayMs = retryDelayMs(attempt, errRetryMs);
                 logWarn("API retry", {
                     rid: requestId,
                     method,
@@ -889,8 +923,9 @@ export async function apiRawCall(path, requestTimeoutMs) {
                 },
             }, effectiveTimeout);
             if (!resp.ok) {
+                const text = await resp.text();
                 if (attempt < MAX_RETRIES && isTransientError(null, resp.status)) {
-                    const delayMs = retryDelayMs(attempt);
+                    const delayMs = retryDelayMs(attempt, parseRetryAfterMs(resp, text));
                     logWarn("API retry", {
                         rid: requestId,
                         path,
@@ -902,7 +937,6 @@ export async function apiRawCall(path, requestTimeoutMs) {
                     await new Promise((r) => setTimeout(r, delayMs));
                     continue;
                 }
-                const text = await resp.text();
                 throwApiError(resp.status, text, requestId);
             }
             const arrayBuf = await resp.arrayBuffer();
@@ -914,7 +948,10 @@ export async function apiRawCall(path, requestTimeoutMs) {
         catch (err) {
             lastError = err;
             if (attempt < MAX_RETRIES && isTransientError(err)) {
-                const delayMs = retryDelayMs(attempt);
+                const errRetryMs = typeof err.retryAfterSec === "number"
+                    ? err.retryAfterSec * 1000
+                    : undefined;
+                const delayMs = retryDelayMs(attempt, errRetryMs);
                 logWarn("API retry", {
                     rid: requestId,
                     path,
@@ -1059,6 +1096,11 @@ export async function fetchTrainingGuidanceFromApi() {
     catch (e) {
         if (e?.httpStatus === 401 || e?.httpStatus === 403)
             throw e;
+        // Prefer last successful payload over a hard failure (TTL may have expired).
+        if (_trainingGuidanceCache?.text) {
+            return (_trainingGuidanceCache.text +
+                "\n\n(Note: API unreachable — showing last cached guidance; may be stale.)");
+        }
         return "Could not fetch parameter guidance. Check API key and connectivity.";
     }
 }

package/dist/tools/account.js

@@ -46,7 +46,7 @@ export function registerAccountTool(server) {
 action=status: Returns plan tier, compute class (CPU/GPU), usage limits, live queue state, training time estimates, and credit balance.
   Use BEFORE large jobs to check GPU availability and estimate wait time.
   When the API/gateway is down, returns structured \`{ok:false, retry_after_sec, …}\` — treat as a pause, not a crash.
-action=inventory: Lists datasets (name/id/rows/cols/description/tags) and slim recent jobs (label/id/status/job_type/dataset_id/created_at/result). Prefer this over hand-assembling datasets(list)+jobs(list). Page jobs with jobs(action=list, cursor=…).
+action=inventory: One-shot markdown overview — all datasets (slim) plus the latest N jobs (limit default 50). Not paginated for datasets; for more jobs use jobs(action=list, cursor=next_cursor, limit=…). Prefer this over hand-assembling datasets(list)+jobs(list).
 action=health: Lightweight liveness/readiness (no R2). Use when tools return api_unreachable or before retrying deferred send_feedback.
 Capacity is shared LOCAL/GKE worker pools — there is no per-key cloud burst lease.
 NOT FOR: Training itself — use train(action=map). This tool only manages the account.`, {

package/dist/tools/explore_map.js

@@ -4,7 +4,9 @@ import { registerAuditedTool, runMcpToolAudit } from "../audit.js";
 import { apiCall, apiRawCall, BARSOM_VIZ_VIEWS, buildStandaloneVizPageUrl, buildVizRelatedUrls, getVizPort, getCaptionForImage, getResultsImagesToFetch, mimeForFilename, structuredTextResult, tryAttachImage, } from "../shared.js";
 import { buildVizStandaloneUrl } from "../viz_links.js";
 import { appendUiDeliveryContent, beginInlineFallback, buildStandaloneVizUrl, resolveUiDelivery, } from "../ui-delivery.js";
+import { figureSection, sortFiguresBySection } from "../figure_sections.js";
 export const RESULTS_EXPLORER_URI = "ui://barsom/results-explorer";
+export { FIGURE_SECTION_LABELS, FIGURE_SECTION_ORDER, figureSection } from "../figure_sections.js";
 function labelForFigure(filename) {
     const base = filename.replace(/\.(png|pdf|svg)$/i, "");
     if (base === "combined")
@@ -34,7 +36,7 @@ function buildAvailableFigures(jobId, summary) {
     // `_fetch_figure` server-tool bridge (the default figure also arrives as a
     // base64 image via the tool result). The standalone browser page builds its
     // own relative-URL payload separately (see views/results-explorer/app.ts).
-    return figureFiles.map((filename) => {
+    return sortFiguresBySection(figureFiles.map((filename) => {
         const base = filename.replace(/\.(png|pdf|svg)$/i, "");
         const featureName = base.startsWith("component_")
             ? base.replace(/^component_\d+_/, "").replace(/_/g, " ")
@@ -44,11 +46,11 @@ function buildAvailableFigures(jobId, summary) {
             key: base,
             label: labelForFigure(filename),
             filename,
-            kind: base.startsWith("component_") ? "component" : base === "combined" ? "summary" : "diagnostic",
+            kind: figureSection(base),
             featureName,
             caption: getCaptionForImage(filename) || (!isRaster ? "This figure is available for download, but it is not inline-displayable in this first iteration." : undefined),
         };
-    });
+    }));
 }
 function buildMetrics(summary) {
     const jobType = String(summary.job_type ?? "train_som");
@@ -164,6 +166,7 @@ async function handleResultsExplorer(job_id) {
         jobId: job_id,
         jobStatus: "completed",
         inlineImageAttached,
+        uiResourceUri: RESULTS_EXPLORER_URI,
     });
     appendUiDeliveryContent(content, uiDelivery, {
         linkLabel: "Open results explorer",
@@ -178,7 +181,7 @@ async function handleResultsExplorer(job_id) {
     }
     return {
         ...structuredTextResult({ ...payload, ui_delivery: uiDelivery }, undefined, content),
-        _meta: { ui: { resourceUri: RESULTS_EXPLORER_URI } },
+        _meta: { ui: { resourceUri: RESULTS_EXPLORER_URI, visibility: ["app"] } },
     };
 }
 export function registerExploreMapTool(server) {
@@ -188,7 +191,7 @@ export function registerExploreMapTool(server) {
         inputSchema: {
             job_id: z.string().describe("Job ID of a completed map training job"),
         },
-        _meta: { ui: { resourceUri: RESULTS_EXPLORER_URI } },
+        _meta: { ui: { resourceUri: RESULTS_EXPLORER_URI, visibility: ["app"] } },
     };
     registerAppTool(server, "results_explorer", toolConfig, async (args) => runMcpToolAudit("results_explorer", "default", args, () => handleResultsExplorer(String(args.job_id))));
     // NOTE: this MUST stay a registered tool — the Results Explorer MCP App view

package/dist/tools/feedback.js

@@ -23,7 +23,7 @@ export function registerFeedbackTool(server) {
 
 For a substantial issue, prefer feedback_items: submit several focused instances (each max 1400 chars) covering, e.g., symptoms, exact reproduction steps, environment, and concrete asks — they are stored together as one batch so developers see the full picture. Use the single feedback field for a short one-off note.
 
-If the API or object storage is unavailable, this tool queues feedback locally (~/.barivia/deferred-feedback) and returns deferred=true with request_id / api_health — call again later to flush. Probe API liveness with account(action=health) (GET /health; does not touch R2).`, {
+If the API or object storage is unavailable, this tool queues feedback locally (~/.barivia/deferred-feedback) and returns deferred=true with request_id / api_health — call again later to flush (idempotent enqueue of the same draft). Probe API liveness with account(action=health) (GET /health; does not touch R2).`, {
         feedback: z.string().max(1400).optional().describe("Single feedback note (max 1400 characters). Use feedback_items instead for a multi-part report."),
         feedback_items: z.array(z.string().max(1400)).max(10).optional().describe("Several feedback instances (each max 1400 characters, up to 10), stored together as one batch. Prefer this for a detailed issue: split it into focused parts (symptoms, reproduction, environment, asks)."),
     }, async ({ feedback, feedback_items }) => {
@@ -104,5 +104,10 @@ If the API or object storage is unavailable, this tool queues feedback locally (
             }
             throw err;
         }
+    }, {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
     });
 }

package/dist/tools/jobs.js

@@ -24,13 +24,13 @@ ASYNC POLLING PROTOCOL (action=monitor):
 - Optional UI: training_monitor(job_id) for embedded charts; jobs(action=monitor) is the headless equivalent.
 
 ASYNC POLLING PROTOCOL (action=status):
-- One-shot check only. If not using monitor, poll every 10-15 seconds manually.
+- One-shot check only. If not using monitor, poll every 10-15 seconds manually — do not give up after one or two polls; large jobs need patience.
 - Progress increases through phases (ordering then convergence for map training); other job types differ.
 - For large grids (40×40+), do not assume failure before 3 minutes on CPU.
 - Map training typical times: 10×10 ~30s | 20×20 ~3–5 min | 40×40 ~15–30 min.
 - completed → results(action=get); failed → read error + optional failure_stage (preprocessing/training/metrics/visualization/upload): memory error → smaller grid/batch and retrain; column missing → datasets(action=preview); NaN on a standard map → train(action=impute) for sparse columns or clean the CSV.
 
-action=list: Slim rows by default (label,id,status,job_type,dataset_id,created_at,result_ref,description,tags — no fat params). Use status/job_type/has_results/limit/cursor to page. has_results=true is the results catalog. Pass fields="full" only when you need params/error.
+action=list: Slim rows by default (label,id,status,job_type,dataset_id,created_at,result_ref,description,tags — no fat params). Use status/job_type/has_results/limit/cursor to page; when the response includes next_cursor, call again with cursor=that value. has_results=true is the results catalog. Pass fields="full" only when you need params/error.
 action=update: PATCH label/description/tags (pass at train submit when possible).
 action=compare: metrics table (QE, TE, explained variance, silhouette) for 2+ COMPLETED TRAINING jobs — pick the best run in a sweep. NOT inference(action=compare) (single trained job + second dataset → density-diff heatmap). Only hyperparameter columns that differ across runs are shown (including SIOM knobs gamma/gamma_f/siom_decay/siom_penalty/reset_per_epoch when they vary); pass label="…" at train time for readable rows.
 action=cancel: Not instant — worker checks between phases. Expect up to 30s delay.

package/dist/tools/results.js

@@ -19,7 +19,8 @@ Temporal state-transition arrows moved to **inference(action=transition_flow)**
 ONLY call this after jobs(action=status) returns "completed".
 ESCALATION: If job not found, verify job_id. If "job not complete", poll with jobs(action=status).
 
-action=get: Returns text summary with quality metrics and inline images.
+Job states (for async parents): pending → running → completed | failed | cancelled (finalize_training may run after compute completes — wait until status=completed before get).
+action=get: Returns text summary with quality metrics and inline images; structuredContent includes a slim verification block (status, file_count, has_summary).
   - figures: omit = combined only. Prefer string "all" / "none" (not an array). "all" = all published plots (excludes unpublished cyclic cos/sin expansions unless train used viz_upload_cyclic_components=true). "none" = metrics text only, no images (recommended for sweeps and LLM clients to keep tool payloads small). Array = specific logical names (combined, umatrix, hit_histogram, learning_curve, correlation, divergence_kl, component_1..N) or download filenames. Hosts that stringify arrays are coerced. Request unpublished cyclic planes via results(recolor, figures=[component_N, ...]).
   - include_individual: if true (and figures omitted), inlines every component plane.
   - After recolor or project, use the job_id returned by that operation to get the new artifacts, not the original training job_id.
@@ -478,6 +479,13 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
                 summary,
                 files,
                 figures_inlined: [...inlinedImages],
+                verification: {
+                    status: "completed",
+                    has_summary: Object.keys(summary).length > 0,
+                    file_count: files.length,
+                    figures_inlined_count: inlinedImages.size,
+                    job_type: jobType2,
+                },
             };
             const summaryText = content.filter((c) => c.type === "text").map((c) => c.text).join("\n\n");
             return structuredTextResult(structuredPayload, summaryText, content);

package/dist/tools/train.js

@@ -15,7 +15,7 @@ export const TRAIN_DESCRIPTION = `Submit a self-organizing map training job. Ret
 
 Call **guide_barsom_workflow**, **training_guidance**, and/or the **prepare_training** prompt for plan-scoped parameter details, timing heuristics, quality.csv semantics, SIOM/FLooP knobs, and impute constraints — do not guess. Backend: "cpu" | "gpu" | "gpu_graphs" (on CPU-only hosts pass backend=cpu).
 
-ASYNC: every action returns a job_id immediately. Poll jobs(action=status) every 10–15s (not faster). When completed, call results(action=get). Timing and quality heuristics: **training_guidance**.
+ASYNC: every action returns a job_id immediately. Prefer jobs(action=monitor) to block with snapshots, or poll jobs(action=status) every 10–15s (not faster) — do not abandon after one poll. When completed, call results(action=get). Timing and quality heuristics: **training_guidance**.
 NOT FOR: lifecycle → jobs; scoring → inference.
 Rank transform (map/siom/floop only) is train-only — see training_guidance.`;
 function assertImputeTrainingArgs(args) {

package/dist/tools/training_monitor.js

@@ -1,7 +1,16 @@
 import { z } from "zod";
 import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
 import { runMcpToolAudit } from "../audit.js";
+import { logWarn } from "../logger.js";
 import { apiCall, BARSOM_VIZ_VIEWS, buildStandaloneVizPageUrl, buildVizRelatedUrls, getVizPort, structuredTextResult, } from "../shared.js";
+/** Loose shape check — warn + pass through on failure (never drop a successful monitor payload). */
+const TrainingMonitorStructuredSchema = z
+    .object({
+    type: z.literal("training-monitor"),
+    jobId: z.string(),
+    refresh_interval_ms: z.number(),
+})
+    .passthrough();
 import { appendUiDeliveryContent, beginInlineFallback, resolveUiDelivery, tryAttachLearningCurve, } from "../ui-delivery.js";
 import { lastEpochTeFromCurves } from "../training_monitor_curve.js";
 import { buildVizStandaloneUrl, resultsExplorerStandaloneLinkText, } from "../viz_links.js";
@@ -91,10 +100,11 @@ async function enrichWithTrainingLog(job_id, data) {
     }
 }
 export async function buildTrainingMonitorResult(job_id, opts) {
-    const { fetch_training_log, preamble } = opts ?? {};
+    const { preamble } = opts ?? {};
     let data = (await apiCall("GET", `/v1/jobs/${job_id}`));
     const jobStatus = String(data.status ?? "");
-    if (fetch_training_log || needsTrainingLogEnrichment(data)) {
+    // Enrich terminal jobs for curve arrays (App refresh uses job_id only — no public flag).
+    if (needsTrainingLogEnrichment(data) || ["completed", "failed", "cancelled"].includes(jobStatus)) {
         data = await enrichWithTrainingLog(job_id, data);
     }
     const port = getVizPort();
@@ -114,8 +124,8 @@ export async function buildTrainingMonitorResult(job_id, opts) {
         timingParts.push(`epoch ${epoch}/${totalEpochs}`);
     const timingNote = timingParts.length > 0 ? ` ${timingParts.join(", ")}.` : "";
     const text = (preamble ? `${preamble}\n\n` : "") +
-        `Training monitor (live when embedded, refreshes every ${TRAINING_MONITOR_REFRESH_MS / 1000}s): job ${job_id} — ${status} (${progress.toFixed(1)}%).${timingNote} ` +
-        `Optional UI; jobs(action=status) is enough to finish the workflow headless.`;
+        `Training monitor (standalone URL + optional App panel; refreshes every ${TRAINING_MONITOR_REFRESH_MS / 1000}s when mounted): job ${job_id} — ${status} (${progress.toFixed(1)}%).${timingNote} ` +
+        `For headless progress use jobs(action=status); this tool is optional.`;
     const content = [{ type: "text", text }];
     const terminal = status === "completed" || status === "failed" || status === "cancelled";
     let inlineImageAttached = false;
@@ -127,6 +137,7 @@ export async function buildTrainingMonitorResult(job_id, opts) {
         jobId: job_id,
         jobStatus: status,
         inlineImageAttached,
+        uiResourceUri: TRAINING_MONITOR_URI,
     });
     appendUiDeliveryContent(content, uiDelivery, {
         linkLabel: "Open training monitor",
@@ -142,6 +153,13 @@ export async function buildTrainingMonitorResult(job_id, opts) {
         }
     }
     structuredContent.ui_delivery = uiDelivery;
+    const parsed = TrainingMonitorStructuredSchema.safeParse(structuredContent);
+    if (!parsed.success) {
+        logWarn("training_monitor structuredContent validation failed — passing through", {
+            job_id,
+            issues: parsed.error.issues.slice(0, 5).map((i) => i.message),
+        });
+    }
     return { structuredContent, content, text };
 }
 /** After terminal + finalize, append results explorer open hint (monitor completion path). */
@@ -158,24 +176,18 @@ export function appendResultsExplorerCompletionHint(content, job_id) {
 export function registerTrainingMonitorTool(server) {
     registerAppTool(server, "training_monitor", {
         title: "Training Monitor",
-        description: "Optional embedded or standalone view of training progress for a job_id. When embedded in a client that supports MCP Apps, the panel auto-refreshes every 5s until the job completes: live QE/TE learning curves (uniformly subsampled to ≤1000 batch samples per phase, not one point per epoch) plus a per-epoch hit-distribution heatmap (sampled BMU counts across the map, showing where observations are landing as training proceeds). A standalone browser URL is also available — its localhost port is per MCP session and goes stale if the proxy restarts (set BARIVIA_VIZ_PORT for a persistent port; re-run this tool for a fresh link). The same scalar fields are available via jobs(action=status)—not required to complete training or read results.",
+        description: "Optional view of training progress for a job_id. Prefer the standalone localhost URL in the tool result (always surfaced when the viz server is up) — some hosts list MCP Apps without mounting panels. When a host mounts the App, the panel auto-refreshes every 5s: QE/TE curves (≤1000 batch samples per phase) plus a hit-distribution heatmap. Set BARIVIA_VIZ_PORT for a stable port; re-run for a fresh link after proxy restart. Headless: jobs(action=status) has the same scalars — not required to finish training or read results.",
         inputSchema: {
             job_id: z.string().describe("Training job ID to monitor"),
-            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 } },
+        _meta: { ui: { resourceUri: TRAINING_MONITOR_URI, visibility: ["model", "app"] } },
     }, async (args) => runMcpToolAudit("training_monitor", "default", args, async () => {
         beginInlineFallback();
-        const { job_id, fetch_training_log } = args;
-        const { structuredContent, content, text } = await buildTrainingMonitorResult(job_id, {
-            fetch_training_log,
-        });
+        const { job_id } = args;
+        const { structuredContent, content, text } = await buildTrainingMonitorResult(job_id);
         return {
             ...structuredTextResult(structuredContent, text, content),
-            _meta: { ui: { resourceUri: TRAINING_MONITOR_URI } },
+            _meta: { ui: { resourceUri: TRAINING_MONITOR_URI, visibility: ["model", "app"] } },
         };
     }));
 }