@barivia/barsom-mcp 0.22.2 → 0.22.4

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 i}from"./viz-server.js";import{API_KEY as a,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 g}from"./tools/train.js";import{registerJobsTool as h,JOBS_DESCRIPTION_BASE as _}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 j}from"./tools/account.js";import{registerInferenceTool as v}from"./tools/inference.js";import{registerGuideBarsomTool as x}from"./tools/guide_barsom.js";import{registerTrainingGuidanceTool as P}from"./tools/training_guidance.js";import{registerFeedbackTool as k}from"./tools/feedback.js";import{registerTrainingMonitorTool as I,TRAINING_MONITOR_URI as A}from"./tools/training_monitor.js";import{resolvePrepareTrainingPrompt as M}from"./prepare_training_prompt.js";a||(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: project high-dimensional data to a 2D grid for clusters, gradients, and anomalies.\n\n## Workflow (short)\n\nUpload (`datasets(upload)`) → `datasets(preview)` and `datasets(analyze)` before train → submit one of `train(action=map)`, `train(action=siom_map)`, or `train(action=floop_siom)` (only if plan allows FLooP) → poll `jobs(status)` every 10–15s until `completed` → `results(get)` for metrics and figures (there is no separate analyze tool), then `results_explorer(job_id)` to browse the figures interactively. Then `jobs(compare)`, `results(download/recolor)`, or `inference` (predict / compare / project_columns / impute_column / transition_flow) as needed.\n\n**Full detail:** Call `guide_barsom_workflow` for plan-scoped tool map, training modes, async rules, optional MCP App UIs, and step-by-step SOP (from the Barivia API when online).\n\n## Tool taxonomy (one tool per stage — do not mix)\n\n| Stage | Tool(s) | Contract |\n|-------|---------|----------|\n| Data | `datasets` | upload, preview, analyze, list, **get** (status/staging), subset, add_expression, reduce_spectral, delete — ingest + feature engineering, no map |\n| Train submit | `train` | map, siom_map, impute (sparse → map + dense imputed.csv), floop_siom (entitled). Async, returns job_id. Submit only |\n| Lifecycle | `jobs` | status, list, compare (**training runs**), cancel, delete. No training/scoring here |\n| Artifacts | `results` | get (default=combined only; figures="none" for metrics-only sweeps; figures="all" or results_explorer/download for every plot), export, download, recolor (async). Read/render completed jobs |\n| Frozen-map ops | `inference` | predict (regime-aware; "compact"|"annotated"), batch_predict, impute_column (neighbor-pool fill for a non-training column), compare (cohort density-diff), project_columns, transition_flow (time-ordered rows only), report. No weight updates |\n| Account | `account` | status, history, add_funds |\n| Bootstrap | `guide_barsom_workflow`, `train`, `training_guidance`, `prepare_training` prompt | orientation, submit map/siom/impute/floop, parameter hints, narrative checklist (API/tier-scoped) |\n| Explore (UI) | `results_explorer`, `training_monitor` | richer UX over the same API; `jobs(status)`+`results(get)` still suffice headless |\n| Other | `send_feedback` | only after user agrees |\n\n### Avoid these mis-routes\n- `jobs(compare)` = metrics table across **training runs** (pick best in a sweep). `inference(compare)` = density-diff of one map vs a **second dataset** (drift/cohort). Different tools.\n- Post-training map analysis (predict, compare, project_columns, impute_column, **transition_flow**) is all **inference** — not `results`. `results` is presentation/artifacts only (`recolor` stays here: it re-renders, it doesn\'t touch data).\n- Project a quantity onto the map: existing columns → `inference(project_columns)`; a formula → `datasets(add_expression, project_onto_job=<job>)`.\n\n## Async pattern\n\n- **Manual poll:** Training submits return `job_id` immediately — poll `jobs(status)` every 10–15s. **Running is not failed**; large grids or FLooP-SIOM can take many minutes. `max_nodes` (FLooP) is a total node budget, not grid side length.\n- **Often auto-polled:** `inference` actions (incl. `transition_flow`) and `results(recolor)` may wait in-proxy; if you get a `job_id`, poll `jobs(status)` the same way.\n\nCredits: jobs consume compute credits; check `account(status)` before big runs. Per-request HTTP timeout defaults to 60s (`datasets(analyze)` is async + auto-polled, so it is not bound by it); on slow networks raise `BARIVIA_FETCH_TIMEOUT_MS`. Timeouts are NOT auto-retried (avoids duplicating slow/expensive work).\n\n## Constraints\n\n- Prep ladder: `prepare_training` prompt = narrative checklist; `training_guidance` = structured hints (presets, resolved normalization/transforms, grid/epochs). Review these, then submit with `train`. Do not guess tiers or FLooP entitlement.\n- `inference(predict)`: prefer `dataset_id` for batch and for SIOM/irregular maps; single-row `rows` uses a fast path that can fail on some topologies — retry with `dataset_id`. FLooP-SIOM: if predict jobs fail while grid SIOM works, capture errors + `job_id`.\n- Column names are case-sensitive — match `datasets(preview)`.\n- Default training path is numeric/cyclic/temporal; use explicit `categorical_features` for baseline categoricals. `predict` must match the model contract.\n- After `results(recolor)`, `inference(transition_flow)`, or `inference(project_columns)`, use the **new** `job_id` returned for follow-up `results` if applicable.\n- **Large results / MCP timeouts:** For sweeps, `jobs(compare)`, or metrics-only reads use `results(action=get, figures="none")`. Default `get` inlines combined only. For every plot use `results_explorer` or `results(action=download)`, not `figures="all"` in chat unless the user wants all images inline.'});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),I(T),f(T),g(T),h(T,_),b(T),j(T),v(T),P(T),k(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/floop_siom; 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 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 M(e);return{messages:[{role:"user",content:{type:"text",text:(t.used_fallback?`[offline fallback ${t.fallback_version}]\n\n`:"")+t.text}}]}});const S=new t;(async function(){try{const e=await i(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(S)})().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 p,loadViewHtml as c,setVizPort as u,setClientSupportsMcpApps as d,CLIENT_VERSION as m}from"./shared.js";import{registerDatasetsTool as f}from"./tools/datasets.js";import{registerTrainTool as g}from"./tools/train.js";import{registerJobsTool as h,JOBS_DESCRIPTION_BASE as _}from"./tools/jobs.js";import{registerResultsTool as b}from"./tools/results.js";import{registerExploreMapTool as y,RESULTS_EXPLORER_URI as w}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 P}from"./tools/feedback.js";import{registerTrainingMonitorTool as A,TRAINING_MONITOR_URI as I}from"./tools/training_monitor.js";import{resolvePrepareTrainingPrompt as C}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 M=new e({name:"analytics-engine",version:m,instructions:'# Barivia Mapping Analytics Engine\n\nSelf-organizing map (SOM) analytics: project high-dimensional data to a 2D grid for clusters, gradients, and anomalies.\n\n## Workflow (short)\n\nUpload (`datasets(upload)`) → `datasets(preview)` and `datasets(analyze)` before train → submit one of `train(action=map)`, `train(action=siom_map)`, or `train(action=floop_siom)` (only if plan allows FLooP) → poll `jobs(status)` every 10–15s until `completed` → `results(get)` for metrics and figures (there is no separate analyze tool), then `results_explorer(job_id)` to browse the figures interactively. Then `jobs(compare)`, `results(download/recolor)`, or `inference` (predict / compare / project_columns / impute_column / transition_flow) as needed.\n\n**Full detail:** Call `guide_barsom_workflow` for plan-scoped tool map, training modes, async rules, optional MCP App UIs, and step-by-step SOP (from the Barivia API when online).\n\n## Tool taxonomy (one tool per stage — do not mix)\n\n| Stage | Tool(s) | Contract |\n|-------|---------|----------|\n| Data | `datasets` | upload, preview, analyze, list, **get** (status/staging), subset, add_expression, reduce_spectral, delete — ingest + feature engineering, no map |\n| Train submit | `train` | map, siom_map, impute (sparse → map + dense imputed.csv), floop_siom (entitled). Async, returns job_id. Submit only |\n| Lifecycle | `jobs` | status, list, compare (**training runs**), cancel, delete. No training/scoring here |\n| Artifacts | `results` | get (default=combined only; figures="none" for metrics-only sweeps; figures="all" or results_explorer/download for every plot), export, download, recolor (async). Read/render completed jobs |\n| Frozen-map ops | `inference` | predict (regime-aware; "compact"|"annotated"), batch_predict, impute_column (neighbor-pool fill for a non-training column), compare (cohort density-diff), project_columns, transition_flow (time-ordered rows only), report. No weight updates |\n| Account | `account` | status, history, add_funds |\n| Bootstrap | `guide_barsom_workflow`, `train`, `training_guidance`, `prepare_training` prompt | orientation, submit map/siom/impute/floop, parameter hints, narrative checklist (API/tier-scoped) |\n| Explore (UI) | `results_explorer`, `training_monitor` | richer UX over the same API; `jobs(status)`+`results(get)` still suffice headless |\n| Other | `send_feedback` | only after user agrees |\n\n### Avoid these mis-routes\n- `jobs(compare)` = metrics table across **training runs** (pick best in a sweep). `inference(compare)` = density-diff of one map vs a **second dataset** (drift/cohort). Different tools.\n- Post-training map analysis (predict, compare, project_columns, impute_column, **transition_flow**) is all **inference** — not `results`. `results` is presentation/artifacts only (`recolor` stays here: it re-renders, it doesn\'t touch data).\n- Project a quantity onto the map: existing columns → `inference(project_columns)`; a formula → `datasets(add_expression, project_onto_job=<job>)`.\n\n## Async pattern\n\n- **Manual poll:** Training submits return `job_id` immediately — poll `jobs(status)` every 10–15s. **Running is not failed**; large grids or FLooP-SIOM can take many minutes. `max_nodes` (FLooP) is a total node budget, not grid side length.\n- **Often auto-polled:** `inference` actions (incl. `transition_flow`) and `results(recolor)` may wait in-proxy; if you get a `job_id`, poll `jobs(status)` the same way.\n\nCredits: jobs consume compute credits; check `account(status)` before big runs. Per-request HTTP timeout defaults to 60s (`datasets(analyze)` is async + auto-polled, so it is not bound by it); on slow networks raise `BARIVIA_FETCH_TIMEOUT_MS`. Timeouts are NOT auto-retried (avoids duplicating slow/expensive work).\n\n## Constraints\n\n- **Do not auto-subset:** Never call `datasets(subset)` or `sample_n` unless the user explicitly asks for a filter, slice, or random sample. Train and analyze on the uploaded `dataset_id` at full row count — GPU staging/prepare handles hundreds of thousands of rows quickly; silent downsampling hides real prepare/train behavior and wastes scale demos. Use small named fixtures (e.g. sample.csv, periodic_load) only when the user or runbook names them.\n- Prep ladder: `prepare_training` prompt = narrative checklist; `training_guidance` = structured hints (presets, resolved normalization/transforms, grid/epochs). Review these, then submit with `train`. Do not guess tiers or FLooP entitlement.\n- `inference(predict)`: prefer `dataset_id` for batch and for SIOM/irregular maps; single-row `rows` uses a fast path that can fail on some topologies — retry with `dataset_id`. FLooP-SIOM: if predict jobs fail while grid SIOM works, capture errors + `job_id`.\n- Column names are case-sensitive — match `datasets(preview)`.\n- Default training path is numeric/cyclic/temporal; use explicit `categorical_features` for baseline categoricals. `predict` must match the model contract.\n- After `results(recolor)`, `inference(transition_flow)`, or `inference(project_columns)`, use the **new** `job_id` returned for follow-up `results` if applicable.\n- **Large results / MCP timeouts:** For sweeps, `jobs(compare)`, or metrics-only reads use `results(action=get, figures="none")`. Default `get` inlines combined only. For every plot use `results_explorer` or `results(action=download)`, not `figures="all"` in chat unless the user wants all images inline.\n\n## UI delivery (heterogeneous MCP clients)\n\nHosts differ (Cursor, Claude Desktop, CLI agents): some embed MCP App panels; others list `ui://` but never mount them (expected on some Cursor builds); others are text-only. Tool results **always lead with a standalone localhost URL** — that is the intended fallback, not a broken App.\n\n| Tier | When | Agent should |\n|------|------|--------------|\n| **embedded** | Client advertises MCP Apps | Let the panel render **and** surface the standalone localhost URL from tool output / `ui_delivery.urls` (hosts often list Apps but do not mount). |\n| **localhost** | No MCP Apps; viz server running | Post the markdown link from tool output to the user (never broken workspace paths). Re-post after job completes if needed. |\n| **inline_image** | No Apps / override `inline` | Summarize metrics; inline raster (combined.png, learning curve) is attached automatically — show it in the reply. |\n| **text_only** | Viz server down | Use `jobs(status)` + `results(get)`; no panel or localhost link. |\n\nEvery `training_monitor` / `results_explorer` response includes a structured `ui_delivery` block (`delivery`, `urls`, `hint_for_agent`). Follow `hint_for_agent` without user prompting. Standalone viz pages cross-link monitor ↔ results for the same `job_id`.\n\n**Env overrides:** `BARIVIA_UI_DELIVERY=auto|apps|localhost|inline` (default `auto`). `BARIVIA_VIZ_PORT` pins the localhost viz port across proxy restarts. **Diagnostics:** `account(action=status)` reports detected MCP Apps support, viz port, and active tier.'});s(M,w,w,{mimeType:n},async()=>{const e=await c("results-explorer");return{contents:[{uri:w,mimeType:n,text:e??"<html><body>Results Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),s(M,I,I,{mimeType:n},async()=>{const e=await c("training-monitor");return{contents:[{uri:I,mimeType:n,text:e??"<html><body>Training Monitor view not built yet.</body></html>"}]}}),x(M),y(M),A(M),f(M),g(M),h(M,_),b(M),v(M),j(M),k(M),P(M),M.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/floop_siom; 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")}}]})),M.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 C(e);return{messages:[{role:"user",content:{type:"text",text:(t.used_fallback?`[offline fallback ${t.fallback_version}]\n\n`:"")+t.text}}]}});const T=new t;(async function(){try{const e=await a(l,p,c);u(e)}catch(e){process.env.BARIVIA_VIZ_PORT&&console.error("Barivia viz server failed to start:",e)}const e=M.server;e.oninitialized=()=>{const t=e.getClientCapabilities(),o=r(t);d(!!o?.mimeTypes?.includes(n))},await M.connect(T)})().catch(console.error);

package/dist/prepare_training_prompt.js

@@ -2,6 +2,7 @@ import { apiCall } from "./shared.js";
 export const PREPARE_TRAINING_FALLBACK_VERSION = "2026.07-offline";
 const FALLBACK_LINES = [
     "Before upload: for train(action=map) ensure training columns have no NaNs; for train(action=impute) missing cells in training columns are OK (plain numeric only).",
+    "Do not auto-subset: never call datasets(subset) or sample_n unless the user explicitly asks — train on the full uploaded dataset_id.",
     'Please run datasets(action=preview, dataset_id="{id}") to inspect columns, then datasets(action=analyze, dataset_id="{id}") to see which columns and temporal periods are most informative.',
     "Choose the training path:",
     '- train(action=map, dataset_id="{id}", ...) for complete-case data',

package/dist/shared.js

@@ -35,7 +35,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.22.2";
+export const CLIENT_VERSION = "0.22.4";
 /** 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). */
@@ -73,6 +73,51 @@ 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 (large files take minutes). */
 export const POLL_STAGE_MAX_MS = 30 * 60_000; // 30 min
+export const BARSOM_VIZ_VIEWS = {
+    trainingMonitor: "training-monitor",
+    resultsExplorer: "results-explorer",
+};
+export function buildStandaloneVizPageUrl(port, viewPath, jobId) {
+    if (!port)
+        return undefined;
+    return `http://localhost:${port}/viz/${viewPath}?mode=standalone&job_id=${encodeURIComponent(jobId)}`;
+}
+export function buildVizRelatedUrls(port, jobId, views) {
+    if (!port)
+        return undefined;
+    return {
+        trainingMonitor: buildStandaloneVizPageUrl(port, views.trainingMonitor, jobId),
+        resultsExplorer: buildStandaloneVizPageUrl(port, views.resultsExplorer, jobId),
+    };
+}
+/** Prominent standalone URL blocks for tool results — always emitted when a viz port exists. */
+export function buildVizUrlContentBlocks(options) {
+    const { label, toolName, standaloneUrl, port, jobId, clientSupportsMcpApps } = options;
+    if (!standaloneUrl)
+        return [];
+    const embedNote = clientSupportsMcpApps
+        ? "Embedded panel if your host supports MCP Apps — otherwise open the standalone URL below (expected on some Cursor builds)."
+        : "Open the standalone URL below when no inline panel appears.";
+    const health = port > 0
+        ? ` Health check: http://localhost:${port}/api/health?job_id=${encodeURIComponent(jobId)}`
+        : "";
+    const blocks = [
+        {
+            type: "text",
+            text: `${embedNote}\n` +
+                `Standalone ${label} URL (copy if Open is blocked):\n${standaloneUrl}\n` +
+                `AGENT: surface this URL prominently in your reply — use a markdown link "[Open ${label}](${standaloneUrl})" or tell the user to copy/paste into a browser. Do not bury it after metrics.\n` +
+                `This localhost port is per MCP session and goes stale if the proxy restarts — re-run ${toolName} for a fresh URL, or set BARIVIA_VIZ_PORT for a persistent port.${health}`,
+        },
+    ];
+    if (!clientSupportsMcpApps) {
+        blocks.push({
+            type: "text",
+            text: `[Open ${label}](${standaloneUrl})`,
+        });
+    }
+    return blocks;
+}
 // ---------------------------------------------------------------------------
 // Shared state (mutable)
 // ---------------------------------------------------------------------------
@@ -860,12 +905,17 @@ export function getResultsImagesToFetch(jobType, summary, figures, includeIndivi
     }
     // train_som / train_siom
     const features = summary.features ?? [];
-    const combinedName = `combined.${ext}`;
-    const umatrixName = `umatrix.${ext}`;
-    const hitHistName = `hit_histogram.${ext}`;
-    const correlationName = `correlation.${ext}`;
+    const summaryFiles = summary.files ?? [];
+    const imageFilesFromSummary = summaryFiles.filter((f) => /\.(png|pdf|svg)$/i.test(f));
+    const combinedName = imageFilesFromSummary.find((f) => f.startsWith("combined.")) ?? `combined.${ext}`;
+    const umatrixName = imageFilesFromSummary.find((f) => f.startsWith("umatrix.")) ?? `umatrix.${ext}`;
+    const hitHistName = imageFilesFromSummary.find((f) => f.startsWith("hit_histogram.")) ?? `hit_histogram.${ext}`;
+    const correlationName = imageFilesFromSummary.find((f) => f.startsWith("correlation.")) ?? `correlation.${ext}`;
     const componentNames = features.map((f, i) => `component_${i + 1}_${f.replace(/[^a-zA-Z0-9_]/g, "_")}.${ext}`);
-    const allList = [combinedName, umatrixName, hitHistName, correlationName, ...componentNames];
+    const publishedComponents = imageFilesFromSummary.filter((f) => /^component_\d+_/.test(f));
+    const allList = imageFilesFromSummary.length > 0
+        ? imageFilesFromSummary
+        : [combinedName, umatrixName, hitHistName, correlationName, ...componentNames];
     if (figures === undefined || figures === "default") {
         return includeIndividual ? allList : [combinedName];
     }
@@ -880,8 +930,13 @@ export function getResultsImagesToFetch(jobType, summary, figures, includeIndivi
             hit_histogram: hitHistName,
             correlation: correlationName,
         };
+        for (const file of imageFilesFromSummary) {
+            const key = file.replace(/\.(png|pdf|svg)$/i, "");
+            nameToFile[key] = file;
+        }
         features.forEach((_, i) => {
-            nameToFile[`component_${i + 1}`] = componentNames[i];
+            const published = publishedComponents.find((f) => f.startsWith(`component_${i + 1}_`));
+            nameToFile[`component_${i + 1}`] = published ?? componentNames[i];
         });
         return figures
             .map((key) => {

package/dist/tools/account.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
-import { apiCall } from "../shared.js";
+import { apiCall, CLIENT_VERSION } from "../shared.js";
+import { getMcpClientDiagnostics } from "../ui-delivery.js";
 export function registerAccountTool(server) {
     registerAuditedTool(server, "account", `Manage your Barivia account — check plan/license info, view usage history, add funds.
 
@@ -80,6 +81,11 @@ NOT FOR: Training itself — use train(action=map). This tool only manages the a
                         lines.push(`  ${k}: ~${v}s`);
                 }
             }
+            const mcpDiag = getMcpClientDiagnostics();
+            lines.push(``, `MCP client (local proxy @ ${CLIENT_VERSION}):`, `  MCP Apps detected: ${mcpDiag.mcp_apps_supported ? "yes" : "no"}`, `  Viz port: ${mcpDiag.viz_port ?? "none"}${mcpDiag.viz_port_pinned ? " (BARIVIA_VIZ_PORT pinned)" : " (ephemeral — set BARIVIA_VIZ_PORT for stable URLs)"}`, `  UI delivery override: ${mcpDiag.ui_delivery_override}`, `  Active delivery tier: ${mcpDiag.active_delivery_tier}`);
+            if (mcpDiag.health_url) {
+                lines.push(`  Viz health: ${mcpDiag.health_url}`);
+            }
             return { content: [{ type: "text", text: lines.join("\n") }] };
         }
         if (action === "history") {

package/dist/tools/datasets.js

@@ -139,7 +139,7 @@ Formats: plain CSV/TSV or gzip (.csv.gz / .tsv.gz). For files above ~100 MB, pre
 | analyze | Pre-training column analysis: correlation matrix, periodicity ranking, column recommendations (train / drop / project later). Run after preview, before train_map. |
 | list | Finding dataset IDs for train_map, preview, or subset — see all available datasets |
 | get | Fetch one dataset by id — status, staging fields, ingest_error (use after upload or when staging is slow) |
-| subset | Creating a filtered/sliced view without re-uploading the full CSV |
+| subset | ONLY when the user asks for row_range, filters, or sample_n — never auto-shrink before train/analyze |
 | add_expression | Add a computed column from an expression (dataset_id + name + expression). With project_onto_job=<training_job_id>, instead projects the computed expression onto that map as a component plane in one step (no column added). |
 | reduce_spectral | Collapse a long ordered numeric block (e.g. 1000-point spectrum, time series, sensor fingerprint) into a small per-row feature set so the SOM can train on signal-dense features. Methods: pca, log_sample, uniform_sample, stats. |
 | delete | Cleaning up after experiments or freeing the dataset slot |
@@ -153,13 +153,15 @@ action=preview: Show columns, stats, sample rows, cyclic/datetime detections. AL
 action=analyze: Pre-training analysis on numeric columns — Pearson correlation, autocorrelation periodicity scores, and column recommendations (train, consider_dropping, project_later, low_variance). Use to choose which columns to include in training and which to project onto the map after training.
 action=list: List all datasets belonging to the organisation with id, name, rows, cols, created_at (use created_at or id to distinguish datasets with the same name).
 action=get: Fetch one dataset by dataset_id — returns status, staged_prefix, staged_version, ingest_error, and stage_job_id when staging is pending.
+DO NOT AUTO-SUBSET: Call action=subset only when the user explicitly requests a filter, slice, or random sample. Default path is upload → preview/analyze → train on the full dataset_id (GPU handles scale). Never downsample to "save time" or "be helpful".
+
 action=subset: Create a new dataset from a subset of an existing one. Requires name and at least one of row_range, filters, or sample_n.
   - row_range: [start, end] 1-based inclusive (e.g. [1, 2000] for first 2000 rows)
   - filters: array of conditions, ALL must match (AND logic). Each: { column, op, value }.
     Operators: eq, ne, in, gt, lt, gte, lte, between
     Examples: { column: "region", op: "eq", value: "Europe" } | { column: "age", op: "between", value: [18, 65] }
-  - sample_n: keep a random N-row sample (seeded via sample_seed, default 42; row order preserved). Shrink a huge table server-side instead of pre-sampling locally. Applied after row_range/filters; can also be used alone.
-  - Combine row_range + filters + sample_n to slice rows, values, then downsample.
+  - sample_n: keep a random N-row sample (seeded via sample_seed, default 42; row order preserved). User/ops tool only — not an agent default. Applied after row_range/filters; can also be used alone.
+  - Combine row_range + filters + sample_n to slice rows, values, then downsample when the user asked for it.
   - Single filter object is also accepted (auto-wrapped).
 action=reduce_spectral: Run a pre-training reducer over an ordered block of numeric columns. All four methods produce one feature vector per row (rows in = rows out; only the column dimension is collapsed) and append derived columns to the dataset. Choose by data shape:
   - pca:            top-k principal components — general first try when many columns are correlated (spectroscopy, gene panels, sensor arrays). Returns explained_variance_ratio.
@@ -258,7 +260,7 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
             .int()
             .min(1)
             .optional()
-            .describe("action=subset: keep a random N-row sample (seeded, row order preserved). Use to shrink a huge table server-side instead of pre-sampling locally. Combine with row_range/filters, or use alone."),
+            .describe("action=subset: keep a random N-row sample (seeded, row order preserved). Only when the user explicitly requests downsampling — not an agent default. Combine with row_range/filters, or use alone."),
         sample_seed: z
             .number()
             .int()
@@ -489,7 +491,7 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
                         job_id: jobId,
                         request_id: rid ?? null,
                         message: errText,
-                        suggested_next_step: "If the dataset is very large, try datasets(action=subset, sample_n=10000) then analyze again.",
+                        suggested_next_step: "Do not auto-subset. Report the error to the user; full-dataset analyze is supported at scale. Use datasets(subset) only if the user explicitly asks for downsampling.",
                     }, errText + (rid ? ` (request_id=${rid})` : ""));
                 }
                 if (poll.status !== "completed") {
@@ -505,7 +507,7 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
                 }
                 else {
                     const msg = err instanceof Error ? err.message : String(err);
-                    throw new Error(`datasets(analyze) failed: ${msg}. If the dataset is very large, try datasets(action=subset, sample_n=10000) first.`);
+                    throw new Error(`datasets(analyze) failed: ${msg}. Do not auto-subset — use datasets(subset) only if the user explicitly asked.`);
                 }
             }
             return { content: [{ type: "text", text: formatAnalyzeResult(data, dataset_id) }] };

package/dist/tools/explore_map.js

@@ -1,7 +1,9 @@
 import { z } from "zod";
 import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
 import { registerAuditedTool, runMcpToolAudit } from "../audit.js";
-import { apiCall, apiRawCall, getClientSupportsMcpApps, getVizPort, getCaptionForImage, getResultsImagesToFetch, mimeForFilename, structuredTextResult, tryAttachImage, } from "../shared.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";
 export const RESULTS_EXPLORER_URI = "ui://barsom/results-explorer";
 function labelForFigure(filename) {
     const base = filename.replace(/\.(png|pdf|svg)$/i, "");
@@ -111,6 +113,10 @@ export function buildPayload(jobId, data) {
         summary.selected_columns ? `Variables: ${summary.selected_columns.join(", ")}` : "",
     ].filter(Boolean);
     const port = getVizPort();
+    const standaloneUrl = buildStandaloneVizPageUrl(port, BARSOM_VIZ_VIEWS.resultsExplorer, jobId) ??
+        buildVizStandaloneUrl("results-explorer", jobId);
+    const trainingMonitorUrl = buildStandaloneVizPageUrl(port, BARSOM_VIZ_VIEWS.trainingMonitor, jobId) ??
+        buildVizStandaloneUrl("training-monitor", jobId);
     return {
         type: "results-explorer",
         jobId,
@@ -123,42 +129,55 @@ export function buildPayload(jobId, data) {
         availableFigures: figures,
         defaultFigureKey: figures.find((figure) => figure.key === "combined")?.key
             ?? figures[0]?.key,
-        standaloneUrl: port ? `http://localhost:${port}/viz/results-explorer?mode=standalone&job_id=${jobId}` : undefined,
+        standaloneUrl,
+        trainingMonitorUrl,
+        relatedUrls: buildVizRelatedUrls(port, jobId, BARSOM_VIZ_VIEWS),
     };
 }
 async function handleResultsExplorer(job_id) {
+    beginInlineFallback();
     const data = (await apiCall("GET", `/v1/results/${job_id}`));
     const payload = buildPayload(job_id, data);
     const summary = (data.summary ?? {});
-    const content = [
-        {
-            type: "text",
-            text: [
-                `Results Explorer ready for job ${job_id}.`,
-                payload.gridLabel ? `Grid: ${payload.gridLabel}` : "",
-                payload.subtitle ? `Label: ${payload.subtitle}` : "",
-                payload.highlights[0] ?? "",
-            ].filter(Boolean).join("\n"),
-        },
-    ];
+    const summaryText = [
+        `Results Explorer ready for job ${job_id}.`,
+        payload.gridLabel ? `Grid: ${payload.gridLabel}` : "",
+        payload.subtitle ? `Label: ${payload.subtitle}` : "",
+        payload.highlights[0] ?? "",
+    ].filter(Boolean).join("\n");
+    const content = [{ type: "text", text: summaryText }];
     const defaultFigure = payload.availableFigures.find((figure) => figure.key === payload.defaultFigureKey);
+    let inlineImageAttached = false;
     if (defaultFigure) {
+        const before = content.length;
         await tryAttachImage(content, job_id, defaultFigure.filename);
+        inlineImageAttached = content.length > before && content.some((c) => c.type === "image");
     }
     else {
         const ext = summary.output_format ?? "png";
+        const before = content.length;
         await tryAttachImage(content, job_id, `combined.${ext}`);
+        inlineImageAttached = content.length > before && content.some((c) => c.type === "image");
     }
-    if (!getClientSupportsMcpApps() && payload.standaloneUrl) {
+    const uiDelivery = resolveUiDelivery({
+        tool: "results_explorer",
+        jobId: job_id,
+        jobStatus: "completed",
+        inlineImageAttached,
+    });
+    appendUiDeliveryContent(content, uiDelivery, {
+        linkLabel: "Open results explorer",
+        primaryUrl: payload.standaloneUrl ?? buildStandaloneVizUrl("results_explorer", job_id),
+    });
+    const monitorUrl = payload.trainingMonitorUrl ?? buildStandaloneVizUrl("training_monitor", job_id);
+    if (monitorUrl) {
         content.push({
             type: "text",
-            text: `Interactive results explorer: [Open results explorer](${payload.standaloneUrl})\n` +
-                `AGENT: surface this to the user as a clickable markdown link (e.g. "[Open results explorer](${payload.standaloneUrl})") in your reply — do not leave it buried in tool output. ` +
-                `This localhost port is assigned per MCP session and changes if the proxy restarts — if the page won't load, re-run results_explorer for a fresh URL, or set BARIVIA_VIZ_PORT in your MCP env for a persistent port.`,
+            text: `Review training curves: [Open training monitor](${monitorUrl})`,
         });
     }
     return {
-        ...structuredTextResult(payload, undefined, content),
+        ...structuredTextResult({ ...payload, ui_delivery: uiDelivery }, undefined, content),
         _meta: { ui: { resourceUri: RESULTS_EXPLORER_URI } },
     };
 }

package/dist/tools/results.js

@@ -19,7 +19,7 @@ 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.
-  - figures: omit = combined only. "all" = all plots. "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, component_1..N).
+  - figures: omit = combined only. "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, component_1..N). 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.
   - After showing results, guide the user: QE interpretation, whether to retrain, which features to explore.
@@ -574,14 +574,20 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
                 throw new Error("results(download) requires folder");
             const data = (await apiCall("GET", `/v1/results/${job_id}`));
             const summary = (data.summary ?? {});
+            const downloadUrls = (data.download_urls ?? {});
             const jobLabel = data.label != null && data.label !== "" ? String(data.label) : null;
             const files = summary.files ?? [];
             const jobType = summary.job_type ?? "train_som";
             const needsAllFiles = ["enrich_dataset", "predict", "impute_column", "compare_datasets"].includes(jobType);
             const isImage = (f) => f.endsWith(".png") || f.endsWith(".svg") || f.endsWith(".pdf");
+            const hasUrlIndex = Object.keys(downloadUrls).length > 0;
+            const isPublished = (f) => !hasUrlIndex || f in downloadUrls;
             let toDownload;
             if (figures === "all" || figures === "images" || figures === undefined) {
                 toDownload = needsAllFiles || include_json ? files : files.filter(isImage);
+                if (hasUrlIndex) {
+                    toDownload = toDownload.filter((f) => !isImage(f) || isPublished(f));
+                }
             }
             else if (Array.isArray(figures)) {
                 toDownload = figures;

package/dist/tools/train.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
-import { apiCall, textResult } from "../shared.js";
+import { apiCall } from "../shared.js";
 import { buildTrainSubmitExtras } from "../train_submit_message.js";
+import { TRAINING_MONITOR_URI, buildTrainingMonitorResult, } from "./training_monitor.js";
 import { TRAINING_INPUT_SCHEMA, buildTrainMapParams, buildFloopParams, fetchTrainingPresets, assertValidNormalizationArgs, } from "./training_core.js";
 export const TRAIN_DESCRIPTION = `Submit a self-organizing map training job. Returns a job_id; poll with jobs(action=status) and then results(action=get). All actions are async.
 
@@ -89,7 +90,12 @@ async function submitTrainJob(opts) {
     }
     data.message = msg;
     data.suggested_next_step = extras.suggested_next_step;
-    return textResult(data);
+    const monitor = await buildTrainingMonitorResult(newJobId, { preamble: msg });
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }, ...monitor.content],
+        structuredContent: monitor.structuredContent,
+        _meta: { ui: { resourceUri: TRAINING_MONITOR_URI } },
+    };
 }
 /**
  * Core training dispatcher. Shared by the `train` tool and the deprecated
@@ -98,7 +104,7 @@ async function submitTrainJob(opts) {
 export async function runTrain(action, args) {
     const dataset_id = args.dataset_id;
     if (action === "map" || action === "siom_map" || action === "impute") {
-        const { preset, grid_x, grid_y, epochs, model, periodic, columns, cyclic_features, cyclic_pairs, temporal_features, feature_weights, transforms, auto_log_transforms, time_delay_embeddings, categorical_features, normalize, normalization_methods, sigma_f, learning_rate, batch_size, quality_metrics, backend, output_format, output_dpi, colormap, row_range, gamma, gamma_f, siom_decay, siom_penalty, penalty_alpha, reset_per_epoch, siom_feature_geometry, siom_qe_backend, siom_qe_batch_size, label, cv_folds, viz_mode, viz_top_components, emit_cell_uncertainty, } = args;
+        const { preset, grid_x, grid_y, epochs, model, periodic, columns, cyclic_features, cyclic_pairs, temporal_features, feature_weights, transforms, auto_log_transforms, time_delay_embeddings, categorical_features, normalize, normalization_methods, sigma_f, learning_rate, batch_size, quality_metrics, backend, output_format, output_dpi, colormap, row_range, gamma, gamma_f, siom_decay, siom_penalty, penalty_alpha, reset_per_epoch, siom_feature_geometry, siom_qe_backend, siom_qe_batch_size, label, cv_folds, viz_mode, viz_top_components, viz_upload_cyclic_components, emit_cell_uncertainty, } = args;
         let PRESETS = {};
         try {
             PRESETS = await fetchTrainingPresets();
@@ -123,7 +129,8 @@ export async function runTrain(action, args) {
             temporal_features, feature_weights, transforms, auto_log_transforms,
             time_delay_embeddings, categorical_features,
             normalize, normalization_methods, sigma_f, learning_rate, batch_size, quality_metrics, backend,
-            output_format, output_dpi, colormap, row_range,
+            output_format, output_dpi, colormap, row_range, siom_feature_geometry, siom_qe_backend, siom_qe_batch_size,
+            viz_upload_cyclic_components,
         }, PRESETS);
         if (action === "impute") {
             params._job_type = "train_impute";

package/dist/tools/training_core.js

@@ -113,6 +113,8 @@ export const TRAINING_INPUT_SCHEMA = {
         .describe("Visualization density; auto-capped when feature count > 40"),
     viz_top_components: z.number().int().min(0).max(64).optional()
         .describe("With viz_mode=summary_plus_top: upload top-N component maps by variance (default 8)"),
+    viz_upload_cyclic_components: z.boolean().optional()
+        .describe("When true with individual component PNGs, also publish cos/sin cyclic expansion planes (default false; recovered hour/month panels stay in combined.png)"),
     emit_cell_uncertainty: z.boolean().optional()
         .describe("impute: write imputation_uncertainty.csv (pool_std = prototype-neighbourhood dispersion, not calibrated SD; pool_n = contributing nodes)"),
     gamma: z.preprocess((v) => (v !== undefined && v !== null && typeof v === "string") ? parseFloat(v) : v, z.number().optional())
@@ -245,7 +247,7 @@ export function buildFloopParams(args) {
     return { params, paramSummary };
 }
 export function buildTrainMapParams(args, presets) {
-    const { preset, grid_x, grid_y, epochs, model, periodic, columns, cyclic_features, cyclic_pairs, temporal_features, feature_weights, transforms, auto_log_transforms, time_delay_embeddings, categorical_features, normalize, normalization_methods, sigma_f, learning_rate, batch_size, quality_metrics, backend, output_format, output_dpi, colormap, row_range, siom_feature_geometry, siom_qe_backend, siom_qe_batch_size, } = args;
+    const { preset, grid_x, grid_y, epochs, model, periodic, columns, cyclic_features, cyclic_pairs, temporal_features, feature_weights, transforms, auto_log_transforms, time_delay_embeddings, categorical_features, normalize, normalization_methods, sigma_f, learning_rate, batch_size, quality_metrics, backend, output_format, output_dpi, colormap, row_range, siom_feature_geometry, siom_qe_backend, siom_qe_batch_size, viz_upload_cyclic_components, } = args;
     const p = preset ? presets[preset] : undefined;
     const params = {
         model: model ?? "SOM",
@@ -308,6 +310,9 @@ export function buildTrainMapParams(args, presets) {
         params.siom_qe_backend = siom_qe_backend;
     if (siom_qe_batch_size !== undefined)
         params.siom_qe_batch_size = siom_qe_batch_size;
+    if (viz_upload_cyclic_components !== undefined) {
+        params.viz_upload_cyclic_components = viz_upload_cyclic_components;
+    }
     const effectiveGrid = params.grid;
     const effectiveEpochs = params.epochs;
     const effectiveBatch = params.batch_size;

package/dist/tools/training_monitor.js

@@ -1,8 +1,10 @@
 import { z } from "zod";
 import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
 import { runMcpToolAudit } from "../audit.js";
-import { apiCall, getClientSupportsMcpApps, getVizPort, structuredTextResult, } from "../shared.js";
+import { apiCall, BARSOM_VIZ_VIEWS, buildStandaloneVizPageUrl, buildVizRelatedUrls, getVizPort, structuredTextResult, } from "../shared.js";
+import { appendUiDeliveryContent, beginInlineFallback, resolveUiDelivery, tryAttachLearningCurve, } from "../ui-delivery.js";
 import { lastEpochTeFromCurves } from "../training_monitor_curve.js";
+import { buildVizStandaloneUrl, resultsExplorerStandaloneLinkText, } from "../viz_links.js";
 export const TRAINING_MONITOR_URI = "ui://barsom/training-monitor";
 export const TRAINING_MONITOR_REFRESH_MS = 5000;
 function hasCurveArrays(data) {
@@ -14,8 +16,12 @@ function hasCurveArrays(data) {
     ];
     return keys.some((k) => Array.isArray(data[k]) && data[k].length > 0);
 }
-function buildStructuredContent(job_id, data) {
+function buildStructuredContent(job_id, data, port = getVizPort()) {
     const id = String(data.id ?? job_id);
+    const standaloneUrl = buildStandaloneVizPageUrl(port, BARSOM_VIZ_VIEWS.trainingMonitor, id) ??
+        buildVizStandaloneUrl("training-monitor", id);
+    const resultsExplorerUrl = buildStandaloneVizPageUrl(port, BARSOM_VIZ_VIEWS.resultsExplorer, id) ??
+        buildVizStandaloneUrl("results-explorer", id);
     return {
         ...data,
         type: "training-monitor",
@@ -23,6 +29,9 @@ function buildStructuredContent(job_id, data) {
         id,
         job_id: id,
         refresh_interval_ms: TRAINING_MONITOR_REFRESH_MS,
+        standaloneUrl,
+        resultsExplorerUrl,
+        relatedUrls: buildVizRelatedUrls(port, id, BARSOM_VIZ_VIEWS),
     };
 }
 function hasTeCurveArrays(data) {
@@ -81,6 +90,71 @@ async function enrichWithTrainingLog(job_id, data) {
         return data;
     }
 }
+export async function buildTrainingMonitorResult(job_id, opts) {
+    const { fetch_training_log, preamble } = opts ?? {};
+    let data = (await apiCall("GET", `/v1/jobs/${job_id}`));
+    const jobStatus = String(data.status ?? "");
+    if (fetch_training_log || needsTrainingLogEnrichment(data)) {
+        data = await enrichWithTrainingLog(job_id, data);
+    }
+    const port = getVizPort();
+    const structuredContent = buildStructuredContent(job_id, data, port);
+    const status = jobStatus;
+    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 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.`;
+    const content = [{ type: "text", text }];
+    const terminal = status === "completed" || status === "failed" || status === "cancelled";
+    let inlineImageAttached = false;
+    if (terminal) {
+        inlineImageAttached = await tryAttachLearningCurve(content, job_id);
+    }
+    const uiDelivery = resolveUiDelivery({
+        tool: "training_monitor",
+        jobId: job_id,
+        jobStatus: status,
+        inlineImageAttached,
+    });
+    appendUiDeliveryContent(content, uiDelivery, {
+        linkLabel: "Open training monitor",
+        primaryUrl: structuredContent.standaloneUrl,
+    });
+    if (status === "completed" && uiDelivery.urls?.length) {
+        const resultsUrl = uiDelivery.urls.find((u) => u.includes("results-explorer"));
+        if (resultsUrl) {
+            content.push({
+                type: "text",
+                text: `Job completed — browse map figures: [Open results explorer](${resultsUrl})`,
+            });
+        }
+    }
+    structuredContent.ui_delivery = uiDelivery;
+    return { structuredContent, content, text };
+}
+/** After terminal + finalize, append results explorer open hint (monitor completion path). */
+export function appendResultsExplorerCompletionHint(content, job_id) {
+    const link = resultsExplorerStandaloneLinkText(job_id);
+    if (link) {
+        content.push({
+            type: "text",
+            text: `${link}\n` +
+                `AGENT: when the job is fully complete (finalize done if any), call results_explorer(job_id="${job_id}") in the same turn and surface this link — do not wait for the user to ask.`,
+        });
+    }
+}
 export function registerTrainingMonitorTool(server) {
     registerAppTool(server, "training_monitor", {
         title: "Training Monitor",
@@ -94,42 +168,11 @@ export function registerTrainingMonitorTool(server) {
         },
         _meta: { ui: { resourceUri: TRAINING_MONITOR_URI } },
     }, async (args) => runMcpToolAudit("training_monitor", "default", args, async () => {
+        beginInlineFallback();
         const { job_id, fetch_training_log } = args;
-        let data = (await apiCall("GET", `/v1/jobs/${job_id}`));
-        const jobStatus = String(data.status ?? "");
-        if (fetch_training_log || needsTrainingLogEnrichment(data)) {
-            data = await enrichWithTrainingLog(job_id, data);
-        }
-        const structuredContent = buildStructuredContent(job_id, data);
-        const status = jobStatus;
-        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 text = `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.`;
-        const content = [{ type: "text", text }];
-        const port = getVizPort();
-        const standaloneUrl = port
-            ? `http://localhost:${port}/viz/training-monitor?mode=standalone&job_id=${encodeURIComponent(job_id)}`
-            : undefined;
-        if (!getClientSupportsMcpApps() && standaloneUrl) {
-            content.push({
-                type: "text",
-                text: `Live training monitor: [Open training monitor](${standaloneUrl})\n` +
-                    `AGENT: surface this to the user as a clickable markdown link (e.g. "[Open training monitor](${standaloneUrl})") in your reply — do not leave it buried in tool output. Re-post the link after the job completes so the user can return to the curves.\n` +
-                    `This localhost port is assigned per MCP session and changes if the proxy restarts — if the page stays at "running 0%" or stops updating, the link is stale: re-run training_monitor for a fresh URL, or set BARIVIA_VIZ_PORT in your MCP env for a persistent port. Health check: http://localhost:${port}/api/health?job_id=${encodeURIComponent(job_id)}`,
-            });
-        }
+        const { structuredContent, content, text } = await buildTrainingMonitorResult(job_id, {
+            fetch_training_log,
+        });
         return {
             ...structuredTextResult(structuredContent, text, content),
             _meta: { ui: { resourceUri: TRAINING_MONITOR_URI } },

package/dist/train_submit_message.js

@@ -1,17 +1,15 @@
-import { getVizPort } from "./shared.js";
+import { buildVizStandaloneUrl } from "./viz_links.js";
 export function buildTrainSubmitExtras(opts) {
     const { newJobId, totalRows, hasTransforms, prepareJobId, variantPrefix, paramSummary, impute, resultsHint } = opts;
-    const monitorUrl = getVizPort() > 0
-        ? `http://localhost:${getVizPort()}/viz/training-monitor?mode=standalone&job_id=${encodeURIComponent(newJobId)}`
-        : null;
+    const monitorUrl = buildVizStandaloneUrl("training-monitor", newJobId);
     let msg = `Job submitted (${variantPrefix}, ${paramSummary}). `;
     if (prepareJobId) {
         msg += `Preprocessing job prepare_training_matrix (${prepareJobId}) runs on worker-io first; train job ${newJobId} starts after it completes. Poll jobs(action=status, job_id="${prepareJobId}") until completed, then poll the train job. `;
     }
-    msg += `Recommended: training_monitor(job_id="${newJobId}")`;
+    msg += `Training monitor opened for job ${newJobId}`;
     if (monitorUrl)
-        msg += ` or open ${monitorUrl}`;
-    msg += ` while polling jobs(action=status, job_id="${newJobId}") every 60–120s for large jobs. `;
+        msg += ` — standalone: ${monitorUrl}`;
+    msg += `. Poll jobs(action=status, job_id="${newJobId}") every 60–120s for large jobs if needed. `;
     msg += `When status is completed, check jobs(action=status) for finalize_job_id — if present, poll that finalize_training job before results(action=get). `;
     msg += `Then use results(action=get, job_id="${newJobId}")`;
     if (resultsHint) {