@barivia/barsom-mcp 0.22.1 → 0.22.4

package/README.md

@@ -163,12 +163,11 @@ All actions use a frozen trained map — no retraining. Derived columns use **`d
 | Action | Use when |
 |--------|----------|
 | `status` | Before large jobs — plan tier, GPU availability, queue depth, credit balance, training time estimates |
-| `request_compute` | Upgrading to cloud burst. Leave tier blank to list options. |
-| `compute_status` | Checking active lease time remaining |
-| `release_compute` | Manually stopping a lease to stop billing |
 | `history` | Viewing recent compute usage and spend |
 | `add_funds` | Getting instructions to add credits |
 
+Capacity is shared LOCAL/GKE worker pools (no per-key cloud burst lease).
+
 ### MCP App tools (optional UIs)
 
 | Tool | Role |
@@ -191,6 +190,10 @@ The right viewer depends on **(MCP App support)** **and** **(can the human reach
 
 ### Migration notes
 
+- **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.
+  - **`train`** submit responses may include a **`results_hint`** string pointing agents to the next post-train step.
 - **Fixed-panel live TE (0.20.4):** mid-training TE curves use a fixed evaluation panel (`te_panel_size` on `train`). Monitors show **Panel TE** and **Map TE** separately; curve tail no longer snaps to map TE.
 - **Features (0.20.0, non-breaking):**
   - **FLooP-SIOM maps are now projectable.** `inference(action=project_columns)`, `inference(action=predict)`, and `datasets(action=add_expression, project_onto_job=<floop_job>)` work on FLooP-SIOM (free/chain) maps — values render onto the FLooP Voronoi layout instead of failing. Grid-only ops (`inference(action=transition_flow | impute_column | render_variant)`) return a clear `unsupported_topology_for_inference` message; use a fixed-grid SOM/SIOM for those. No client change required.

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{resolvePrepareTrainingPromptText 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, burst/compute actions, 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})=>({messages:[{role:"user",content:{type:"text",text:await M(e)}}]}));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/job_status_format.js

@@ -70,6 +70,17 @@ export function formatJobStatusText(job_id, data) {
         if (epoch != null && totalEpochs != null && totalEpochs > 0) {
             parts.push(`epoch ${epoch}/${totalEpochs}`);
         }
+        const panelTe = data.panel_te != null && !Number.isNaN(Number(data.panel_te))
+            ? Number(data.panel_te)
+            : data.panel_topographic_error != null && !Number.isNaN(Number(data.panel_topographic_error))
+                ? Number(data.panel_topographic_error)
+                : null;
+        if (panelTe != null) {
+            parts.push(`panel_te: ${panelTe.toFixed(4)}`);
+        }
+        if (data.kernel_complete === true) {
+            parts.push("kernel_complete");
+        }
     }
     const datasetRows = data.dataset_rows != null ? Number(data.dataset_rows) : null;
     const datasetName = data.dataset_name != null ? String(data.dataset_name) : null;
@@ -120,6 +131,18 @@ export function formatJobStatusText(job_id, data) {
     else if (status === "cancelled") {
         parts.push(`Cancelled. Poll again to confirm; dataset and partial worker state are unchanged.`);
     }
+    const suggested = data.suggested_next_step != null && String(data.suggested_next_step) !== ""
+        ? String(data.suggested_next_step)
+        : status === "completed"
+            ? `results(action=get, job_id="${job_id}") then results_explorer(job_id="${job_id}")`
+            : status === "failed"
+                ? `Inspect failure_stage/error; fix data or params; resubmit train or jobs.`
+                : status === "running" || status === "pending"
+                    ? `jobs(action=status, job_id="${job_id}") again in 10–15s (or training_monitor).`
+                    : null;
+    if (suggested) {
+        parts.push(`suggested_next_step: ${suggested}`);
+    }
     return parts.join(" | ");
 }
 export function formatJobCancelText(job_id, data) {

package/dist/prepare_training_prompt.js

@@ -1,6 +1,8 @@
 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',
@@ -9,16 +11,24 @@ const FALLBACK_LINES = [
     '- train(action=floop_siom, dataset_id="{id}", ...) for FLooP-SIOM (default topology=free / CHL; optional topology=chain)',
 ];
 /** Used by the `prepare_training` MCP prompt; prefers tier-scoped text from the API when online. */
-export async function resolvePrepareTrainingPromptText(datasetId) {
-    let promptText = FALLBACK_LINES.join("\n").replaceAll("{id}", datasetId);
+export async function resolvePrepareTrainingPrompt(datasetId) {
+    const fallbackText = FALLBACK_LINES.join("\n").replaceAll("{id}", datasetId);
     try {
         const data = (await apiCall("GET", `/v1/docs/prepare_training?dataset_id=${datasetId}`));
         if (typeof data.prompt === "string" && data.prompt.trim()) {
-            promptText = data.prompt.trim();
+            return { text: data.prompt.trim(), used_fallback: false, fallback_version: null };
         }
     }
     catch {
-        // fallback
+        // fall through
     }
-    return promptText;
+    return {
+        text: fallbackText,
+        used_fallback: true,
+        fallback_version: PREPARE_TRAINING_FALLBACK_VERSION,
+    };
+}
+/** @deprecated Prefer resolvePrepareTrainingPrompt for structured fallback metadata. */
+export async function resolvePrepareTrainingPromptText(datasetId) {
+    return (await resolvePrepareTrainingPrompt(datasetId)).text;
 }

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.1";
+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,29 +1,25 @@
 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, request cloud burst compute, view billing history.
+    registerAuditedTool(server, "account", `Manage your Barivia account — check plan/license info, view usage history, add funds.
 
 | Action | Use when |
 |--------|----------|
 | status | Before large jobs — see plan tier, GPU availability, queue depth, training time estimates, credit balance |
-| request_compute | Upgrading to cloud burst (required for large grids or GPU). Leave tier blank to list options. |
-| compute_status | Checking if a burst lease is active and how much time remains |
-| release_compute | Manually terminating an active lease to stop billing |
-| history | Viewing recent compute leases and credit spend |
+| history | Viewing recent compute usage and credit spend |
 | add_funds | Getting instructions to add credits |
 
 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.
-action=request_compute: Provisions an ephemeral cloud burst EC2 instance. Data is in shared R2 — no re-upload needed. Wait ~3 min after requesting before submitting jobs.
-NOT FOR: Training itself — use train(action=map). This tool only manages the account and compute lease.`, {
+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.`, {
         action: z
-            .enum(["status", "request_compute", "compute_status", "release_compute", "history", "add_funds"])
-            .describe("status: plan/license/queue info; request_compute: provision burst; compute_status: check active lease; release_compute: stop lease; history: recent compute usage; add_funds: instructions"),
-        tier: z.string().optional().describe("action=request_compute: tier ID — CPU: cpu-mini, cpu-2, cpu-8..cpu-48 (C7i); GPU: gpu-t4-small, gpu-t4..gpu-t4xxx, gpu-t4-12x (G4dn), gpu-p4d (P4d), gpu-l4, gpu-a10. Omit to list options."),
-        duration_minutes: z.number().optional().describe("action=request_compute: lease duration in minutes (default: 60)"),
+            .enum(["status", "history", "add_funds"])
+            .describe("status: plan/license/queue info; history: recent compute usage; add_funds: instructions"),
         limit: z.number().optional().describe("action=history: number of records to return (default: 10)"),
-    }, async ({ action, tier, duration_minutes, limit }) => {
+    }, async ({ action, limit }) => {
         if (action === "status") {
             const data = (await apiCall("GET", "/v1/system/info"));
             const plan = data.plan ?? {};
@@ -35,7 +31,6 @@ NOT FOR: Training itself — use train(action=map). This tool only manages the a
             const computeDesc = gpuEnabled ? (backend.gpu_model ? `GPU (${backend.gpu_model}${backend.gpu_vram_gb ? `, ${backend.gpu_vram_gb}GB` : ""})` : "GPU") : "CPU only";
             const fmtLimit = (v) => v === -1 || v === "-1" ? "unlimited" : String(v ?? "?");
             const historyData = await apiCall("GET", "/v1/compute/history?limit=5").catch(() => null);
-            const leaseData = await apiCall("GET", "/v1/compute/lease").catch(() => null);
             const algoNames = {
                 train_som: "SOM",
                 train_impute: "Imputation",
@@ -62,7 +57,6 @@ NOT FOR: Training itself — use train(action=map). This tool only manages the a
                     lines.push(`  Credits: $${(historyData.credit_balance_cents / 100).toFixed(2)} remaining`);
                 }
                 else {
-                    // Unknown billing mode: avoid misleading $0.00 for postpaid accounts
                     const cents = historyData.credit_balance_cents ?? 0;
                     if (cents === 0) {
                         lines.push(`  Credits: N/A (postpaid or zero balance — check plan)`);
@@ -74,9 +68,6 @@ NOT FOR: Training itself — use train(action=map). This tool only manages the a
             }
             if (backend.memory_gb)
                 lines.push(`  Backend Memory: ${backend.memory_gb} GB`);
-            if (leaseData && leaseData.lease_id) {
-                lines.push(``, `Active Burst Lease: ${leaseData.tier} | ${Math.round(leaseData.time_remaining_ms / 60000)} min left`);
-            }
             const running = Number(status.running_jobs ?? data.running_jobs ?? 0);
             const pending = Number(status.pending_jobs ?? data.pending_jobs ?? 0);
             const compute_eta = Number(estimates?.total || 0);
@@ -90,64 +81,12 @@ NOT FOR: Training itself — use train(action=map). This tool only manages the a
                         lines.push(`  ${k}: ~${v}s`);
                 }
             }
-            return { content: [{ type: "text", text: lines.join("\n") }] };
-        }
-        if (action === "request_compute") {
-            if (!tier) {
-                try {
-                    const tiersData = await apiCall("GET", "/v1/compute/tiers");
-                    const lines = ["Available Compute Tiers:"];
-                    for (const [tId, tData] of Object.entries(tiersData.tiers)) {
-                        lines.push(`  ${tId}: ${tData.desc}`);
-                    }
-                    return { content: [{ type: "text", text: lines.join("\n") }] };
-                }
-                catch (err) {
-                    const msg = err?.message ?? "Failed to fetch compute tiers. Ensure you have burst access enabled.";
-                    return { content: [{ type: "text", text: msg }] };
-                }
-            }
-            const data = await apiCall("POST", "/v1/compute/lease", { tier, duration_minutes });
-            const billingLine = data.billing_mode === "postpaid"
-                ? `Billing: Postpaid (usage logged, billed retrospectively)\nAccrued Balance: $${(data.credit_balance_cents / 100).toFixed(2)}`
-                : `Credits Remaining After Reserve: $${(data.credit_balance_cents / 100).toFixed(2)}`;
-            return {
-                content: [{ type: "text", text: `Compute Lease Requested:
-Lease ID: ${data.lease_id}
-Status: ${data.status}
-Estimated Wait: ${data.estimated_wait_minutes} minutes
-Estimated Cost: $${(data.estimated_cost_cents / 100).toFixed(2)}
-${billingLine}
-
-IMPORTANT: Cloud burst active. Data is pulled from shared Cloudflare R2, so you do NOT need to re-upload datasets. Just wait ~3 minutes and check status.` }]
-            };
-        }
-        if (action === "compute_status") {
-            const data = await apiCall("GET", "/v1/compute/lease");
-            if (data.status === "none" || !data.lease_id) {
-                return { content: [{ type: "text", text: "No active lease -- running on default Primary Server." }] };
+            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: `Active Compute Lease:
-Lease ID: ${data.lease_id}
-Status: ${data.status}
-Tier: ${data.tier} (${data.instance_type})
-Time Remaining: ${Math.round(data.time_remaining_ms / 60000)} minutes` }]
-            };
-        }
-        if (action === "release_compute") {
-            const data = await apiCall("DELETE", "/v1/compute/lease");
-            const costLine = data.billing_mode === "postpaid"
-                ? `Cost Logged: $${(data.cost_cents / 100).toFixed(2)} (postpaid — billed retrospectively)`
-                : `Credits Deducted: $${((data.credits_deducted || data.cost_cents) / 100).toFixed(2)}`;
-            return {
-                content: [{ type: "text", text: `Compute Released:
-Duration Billed: ${data.duration_minutes} minutes
-${costLine}
-Balance: $${(data.final_balance_cents / 100).toFixed(2)}
-
-Routing reverted to default Primary Server.` }]
-            };
+            return { content: [{ type: "text", text: lines.join("\n") }] };
         }
         if (action === "history") {
             const data = await apiCall("GET", `/v1/compute/history?limit=${limit || 10}`);
@@ -159,11 +98,11 @@ Routing reverted to default Primary Server.` }]
         if (action === "add_funds") {
             return {
                 content: [{ type: "text", text: `To add funds to your account, please visit the Barivia Billing Portal (integration pending) or ask your administrator to use the CLI tool:
-bash scripts/manage-credits.sh add <org_id> <amount_usd>` }]
+bash scripts/billing/manage-credits.sh add <org_id> <amount_usd>` }]
             };
         }
         return {
-            content: [{ type: "text", text: `Unknown action: ${action}. Valid: status, request_compute, compute_status, release_compute, history, add_funds.` }]
+            content: [{ type: "text", text: `Unknown action: ${action}. Valid: status, history, add_funds.` }]
         };
     });
 }

package/dist/tools/datasets.js

@@ -4,7 +4,7 @@ import { gzipSync } from "node:zlib";
 import { createHash } from "node:crypto";
 import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
-import { apiCall, getWorkspaceRootAsync, resolveFilePathForUpload, textResult, pollUntilComplete, POLL_DERIVE_MAX_MS, POLL_ANALYZE_MAX_MS, UPLOAD_DATASET_TIMEOUT_MS, LARGE_UPLOAD_BYTES, PRESIGNED_PUT_TIMEOUT_MS, POLL_STAGE_MAX_MS, streamFileSha256, putPresignedStream, resolveUploadContentType, suggestDatasetPreview, } from "../shared.js";
+import { apiCall, getWorkspaceRootAsync, resolveFilePathForUpload, textResult, structuredTextResult, pollUntilComplete, POLL_DERIVE_MAX_MS, POLL_ANALYZE_MAX_MS, UPLOAD_DATASET_TIMEOUT_MS, LARGE_UPLOAD_BYTES, PRESIGNED_PUT_TIMEOUT_MS, POLL_STAGE_MAX_MS, streamFileSha256, putPresignedStream, resolveUploadContentType, suggestDatasetPreview, } from "../shared.js";
 import { GZIP_UPLOAD_HINT } from "../job_status_format.js";
 /**
  * Normalize a nullable string field from the API. Returns "" for absent values,
@@ -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()
@@ -481,10 +483,20 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
                     throw new Error("analyze did not return a job id");
                 const poll = await pollUntilComplete(jobId, POLL_ANALYZE_MAX_MS);
                 if (poll.status === "failed") {
-                    return { content: [{ type: "text", text: `datasets(analyze) job ${jobId} failed: ${poll.error ?? "unknown error"}` }] };
+                    const rid = poll.request_id;
+                    const errText = `datasets(analyze) job ${jobId} failed: ${poll.error ?? "unknown error"}`;
+                    return structuredTextResult({
+                        error: true,
+                        action: "analyze",
+                        job_id: jobId,
+                        request_id: rid ?? null,
+                        message: errText,
+                        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") {
-                    return { content: [{ type: "text", text: `datasets(analyze) job ${jobId} is still running. Poll with jobs(action=status, job_id="${jobId}") then results(action=get, job_id="${jobId}").` }] };
+                    const text = `datasets(analyze) job ${jobId} is still running. Poll with jobs(action=status, job_id="${jobId}") then results(action=get, job_id="${jobId}").`;
+                    return structuredTextResult({ error: false, action: "analyze", job_id: jobId, status: poll.status, message: text }, text);
                 }
                 const results = (await apiCall("GET", `/v1/results/${jobId}`));
                 data = (results.summary ?? results);
@@ -495,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;