@barivia/barsom-mcp 0.22.2 → 0.23.0

package/dist/tools/datasets.js

@@ -6,6 +6,7 @@ import { z } from "zod";
 import { registerAuditedTool } from "../audit.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";
+import { formatDatasetInventoryLine, formatTags } from "../inventory_format.js";
 /**
  * Normalize a nullable string field from the API. Returns "" for absent values,
  * empty strings, and the literal SQL/serialization sentinels "missing"/"null"
@@ -137,9 +138,10 @@ Formats: plain CSV/TSV or gzip (.csv.gz / .tsv.gz). For files above ~100 MB, pre
 | upload | You have a CSV or .csv.gz file to add — do this first |
 | preview | Before train(action=map) — always preview an unfamiliar dataset to spot cyclics, nulls, column types |
 | 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 |
+| list | Finding dataset IDs for train_map, preview, or subset — see all available datasets (includes description/tags) |
+| get | Fetch one dataset by id — status, staging fields, ingest_error, description/tags (use after upload or when staging is slow) |
+| update | Edit name / description / tags on an existing dataset (helps navigate duplicates) |
+| 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 |
@@ -151,15 +153,20 @@ Step 1 (after upload): always datasets(action=preview) to verify column types an
 
 action=preview: Show columns, stats, sample rows, cyclic/datetime detections. ALWAYS preview before train(action=map) on an unfamiliar dataset.
 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.
+action=list: List all datasets belonging to the organisation with id, name, rows, cols, created_at, description, tags (use tags/description 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, description/tags, and stage_job_id when staging is pending.
+action=update: PATCH name/description/tags on an existing dataset.
+action=upload: Optional description and tags help later inventory (also settable via update).
+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".
+Org overview: account(action=inventory) for a markdown datasets+jobs catalog.
+
 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.
@@ -173,9 +180,11 @@ BEST FOR: Tabular numeric data. CSV with header required.
 NOT FOR: Real-time data streams or binary files — upload a snapshot CSV instead.
 ESCALATION: If upload fails with column errors, open the file locally and verify the header row. If preview shows nulls in training columns: use train(action=impute) for sparse data, or clean/subset for train(action=map).`, {
         action: z
-            .enum(["upload", "preview", "analyze", "list", "get", "subset", "delete", "add_expression", "reduce_spectral"])
-            .describe("upload: add CSV or .csv.gz; preview: inspect columns/stats; analyze: pre-training correlation and periodicity; list: see all datasets; get: fetch one dataset metadata (status/staging); subset: create filtered subset; delete: remove dataset; add_expression: add derived column from expression (or, with project_onto_job, project the expression onto a trained map as a component plane); reduce_spectral: collapse a long ordered numeric block (e.g. spectrum, time series) into a small per-row feature set via PCA / log_sample / uniform_sample / stats"),
-        name: z.string().optional().describe("Dataset name (required for action=upload and subset)"),
+            .enum(["upload", "preview", "analyze", "list", "get", "update", "subset", "delete", "add_expression", "reduce_spectral"])
+            .describe("upload: add CSV or .csv.gz; preview: inspect columns/stats; analyze: pre-training correlation and periodicity; list: see all datasets; get: fetch one dataset metadata (status/staging); update: edit name/description/tags; subset: create filtered subset; delete: remove dataset; add_expression: add derived column from expression (or, with project_onto_job, project the expression onto a trained map as a component plane); reduce_spectral: collapse a long ordered numeric block (e.g. spectrum, time series) into a small per-row feature set via PCA / log_sample / uniform_sample / stats"),
+        name: z.string().optional().describe("Dataset name (required for action=upload and subset; optional for update)"),
+        description: z.string().optional().describe("Optional free-text description (upload/update). Pass \"\" on update to clear."),
+        tags: z.array(z.string()).optional().describe("Optional tags for inventory/navigation (upload/update). Pass [] on update to clear."),
         file_path: z.string().optional().describe("Path to local CSV or .csv.gz (PREFERRED): absolute path, file:// URI, or path relative to the workspace root. Token-efficient; server reads file. NOTE: relative paths resolve against the MCP workspace root — in Cursor/IDE clients that root is often the MCP install dir, not your project, so set BARIVIA_WORKSPACE_ROOT in the MCP config env (or just pass an absolute path) if a relative path is 'not accessible'. Use .csv.gz for large scientific tables."),
         csv_data: z.string().optional().describe("Inline CSV string for small pastes only (<10KB). Avoid for large files — use file_path instead to avoid token explosion."),
         dataset_id: z.string().optional().describe("Dataset ID (required for preview, get, subset, and delete)"),
@@ -258,13 +267,13 @@ 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()
             .optional()
             .describe("action=subset: RNG seed for sample_n (default 42; same seed + dataset reproduces the same sample)."),
-    }, async ({ action, name, file_path, csv_data, dataset_id, n_rows, row_range, filters, filter, expression, options, project_onto_job, aggregation, output_format, method, columns_block, columns_range, columns_except, k, sample_n, sample_seed }) => {
+    }, async ({ action, name, description, tags, file_path, csv_data, dataset_id, n_rows, row_range, filters, filter, expression, options, project_onto_job, aggregation, output_format, method, columns_block, columns_range, columns_except, k, sample_n, sample_seed }) => {
         if (action === "upload") {
             if (!name)
                 throw new Error("datasets(upload) requires name");
@@ -304,7 +313,12 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
                     const idem = await streamFileSha256(resolved);
                     let init;
                     try {
-                        init = (await apiCall("POST", "/v1/datasets/upload-url", { name, size_bytes: stat.size }, { "Idempotency-Key": idem }));
+                        const uploadUrlBody = { name, size_bytes: stat.size };
+                        if (description !== undefined)
+                            uploadUrlBody.description = description;
+                        if (tags !== undefined)
+                            uploadUrlBody.tags = tags;
+                        init = (await apiCall("POST", "/v1/datasets/upload-url", uploadUrlBody, { "Idempotency-Key": idem }));
                     }
                     catch (e) {
                         const msg = e instanceof Error ? e.message : String(e);
@@ -342,12 +356,17 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
                 // Content-Encoding: gzip), never decoding them as UTF-8 text.
                 if (isGzipInput) {
                     const gzBytes = await fs.readFile(resolved);
-                    const data = (await apiCall("POST", "/v1/datasets", gzBytes, {
+                    const gzHeaders = {
                         "X-Dataset-Name": name,
                         "Content-Type": uploadContentType,
                         "Content-Encoding": "gzip",
                         "Idempotency-Key": createHash("sha256").update(`${name}\n`).update(gzBytes).digest("hex"),
-                    }, UPLOAD_DATASET_TIMEOUT_MS));
+                    };
+                    if (description !== undefined)
+                        gzHeaders["X-Dataset-Description"] = description;
+                    if (tags !== undefined)
+                        gzHeaders["X-Dataset-Tags"] = JSON.stringify(tags);
+                    const data = (await apiCall("POST", "/v1/datasets", gzBytes, gzHeaders, UPLOAD_DATASET_TIMEOUT_MS));
                     const gid = data.id ?? data.dataset_id;
                     if (gid != null)
                         data.suggested_next_step = `${suggestDatasetPreview(String(gid))} to inspect columns before training.`;
@@ -371,6 +390,10 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
                 // the original dataset server-side instead of creating a duplicate.
                 "Idempotency-Key": createHash("sha256").update(`${name}\n`).update(body).digest("hex"),
             };
+            if (description !== undefined)
+                uploadHeaders["X-Dataset-Description"] = description;
+            if (tags !== undefined)
+                uploadHeaders["X-Dataset-Tags"] = JSON.stringify(tags);
             let uploadBody = body;
             if (Buffer.byteLength(body, "utf-8") > GZIP_THRESHOLD) {
                 uploadBody = gzipSync(Buffer.from(body, "utf-8"));
@@ -489,7 +512,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 +528,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) }] };
@@ -679,15 +702,9 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
             const data = (await apiCall("GET", "/v1/datasets"));
             if (Array.isArray(data)) {
                 const lines = data.map((ds) => {
-                    const id = String(ds.id ?? "");
-                    const name = String(ds.name ?? "");
-                    const rows = ds.rows != null ? Number(ds.rows) : "?";
-                    const cols = ds.cols != null ? Number(ds.cols) : "?";
-                    const st = ds.status != null ? String(ds.status) : "ready";
-                    const statusBit = st !== "ready" ? ` | status=${st}` : "";
+                    const base = formatDatasetInventoryLine(ds);
                     const ingestErr = cleanNullable(ds.ingest_error);
-                    const err = ingestErr ? ` | ingest_error=${ingestErr}` : "";
-                    return `${name} (${id}) — ${rows}×${cols}${statusBit}${err}`;
+                    return ingestErr ? `${base} | ingest_error=${ingestErr}` : base;
                 });
                 return { content: [{ type: "text", text: lines.length > 0 ? lines.join("\n") : "No datasets." }] };
             }
@@ -697,11 +714,14 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
             if (!dataset_id)
                 throw new Error("datasets(get) requires dataset_id");
             const ds = (await apiCall("GET", `/v1/datasets/${dataset_id}`));
+            const tagStr = formatTags(ds.tags);
             const lines = [
                 `Dataset: ${ds.name ?? "?"} (${ds.id ?? dataset_id})`,
                 `Status: ${ds.status ?? "ready"}`,
                 `Rows × cols: ${ds.rows ?? "?"} × ${ds.cols ?? "?"}`,
                 ds.size_bytes != null ? `Size: ${Number(ds.size_bytes).toLocaleString()} bytes` : "",
+                ds.description != null && String(ds.description).trim() !== "" ? `Description: ${String(ds.description)}` : "",
+                tagStr ? `Tags: ${tagStr}` : "",
                 ds.staged_prefix != null ? `Staged prefix: ${String(ds.staged_prefix)}` : "",
                 ds.staged_version != null ? `Staged version: ${String(ds.staged_version)}` : "",
                 ds.stage_job_id != null ? `Stage job: ${String(ds.stage_job_id)} (poll jobs(action=status))` : "",
@@ -710,6 +730,22 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
             ].filter(Boolean);
             return { content: [{ type: "text", text: lines.join("\n") }] };
         }
+        if (action === "update") {
+            if (!dataset_id)
+                throw new Error("datasets(update) requires dataset_id");
+            const body = {};
+            if (name !== undefined)
+                body.name = name;
+            if (description !== undefined)
+                body.description = description;
+            if (tags !== undefined)
+                body.tags = tags;
+            if (Object.keys(body).length === 0) {
+                throw new Error("datasets(update) requires at least one of name, description, tags");
+            }
+            const data = await apiCall("PATCH", `/v1/datasets/${dataset_id}`, body);
+            return textResult(data);
+        }
         if (action === "delete") {
             if (!dataset_id)
                 throw new Error("datasets(delete) requires 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/feedback.js

@@ -1,10 +1,29 @@
 import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
-import { apiCall, API_URL, fetchWithTimeout, textResult } from "../shared.js";
+import { apiCall, API_URL, fetchWithTimeout, probeApiHealth, structuredTextResult, } from "../shared.js";
+import { enqueueDeferredFeedback, flushDeferredFeedback, listDeferredFeedback, } from "../deferred_feedback.js";
+function isDeferworthy(err) {
+    const e = err;
+    if (e?.retryable)
+        return true;
+    if (e?.cause === "api_unreachable" || e?.cause === "storage" || e?.cause === "network")
+        return true;
+    const status = e?.httpStatus;
+    if (status === 502 || status === 503 || status === 504)
+        return true;
+    if (err instanceof TypeError)
+        return true;
+    if (err instanceof Error && /fetch failed|ECONNREFUSED|ENOTFOUND|ECONNRESET|network|timed out/i.test(err.message)) {
+        return true;
+    }
+    return false;
+}
 export function registerFeedbackTool(server) {
     registerAuditedTool(server, "send_feedback", `Send feedback or feature requests to Barivia developers. Use when the user has suggestions, ran into issues, or wants something improved. Do NOT call without asking the user first — but after any group of actions or downloading of results, you SHOULD prepare feedback based on the user's workflow or errors encountered, show it to them, and ask for permission to send it. Once they accept, call this tool.
 
-For a substantial issue, prefer feedback_items: submit several focused instances (each max 1400 chars) covering, e.g., symptoms, exact reproduction steps, environment, and concrete asks — they are stored together as one batch so developers see the full picture. Use the single feedback field for a short one-off note.`, {
+For a substantial issue, prefer feedback_items: submit several focused instances (each max 1400 chars) covering, e.g., symptoms, exact reproduction steps, environment, and concrete asks — they are stored together as one batch so developers see the full picture. Use the single feedback field for a short one-off note.
+
+If the API or object storage is unavailable, this tool queues feedback locally (~/.barivia/deferred-feedback) and returns deferred=true with request_id / api_health — call again later to flush. Probe API liveness with account(action=health) (GET /health; does not touch R2).`, {
         feedback: z.string().max(1400).optional().describe("Single feedback note (max 1400 characters). Use feedback_items instead for a multi-part report."),
         feedback_items: z.array(z.string().max(1400)).max(10).optional().describe("Several feedback instances (each max 1400 characters, up to 10), stored together as one batch. Prefer this for a detailed issue: split it into focused parts (symptoms, reproduction, environment, asks)."),
     }, async ({ feedback, feedback_items }) => {
@@ -15,9 +34,20 @@ For a substantial issue, prefer feedback_items: submit several focused instances
             throw new Error("send_feedback requires feedback or feedback_items (at least one non-empty entry).");
         }
         const body = items.length === 1 ? { feedback: items[0] } : { feedback_items: items };
+        const submit = async (b) => apiCall("POST", "/v1/feedback", b);
+        // Best-effort flush of earlier offline drafts before sending the new one.
+        const flushed = await flushDeferredFeedback("barsom", submit).catch(() => null);
         try {
-            const data = await apiCall("POST", "/v1/feedback", body);
-            return textResult(data);
+            const data = (await submit(body));
+            return structuredTextResult({
+                ...data,
+                deferred: false,
+                ...(flushed && flushed.flushed > 0
+                    ? { flushed_deferred: flushed.flushed, deferred_remaining: flushed.remaining }
+                    : {}),
+            }, typeof data.message === "string"
+                ? data.message
+                : "Feedback received. Thank you.");
         }
         catch (err) {
             if (err?.httpStatus === 401) {
@@ -31,10 +61,46 @@ For a substantial issue, prefer feedback_items: submit several focused instances
                     const text = await resp.text();
                     if (resp.ok) {
                         const parsed = JSON.parse(text);
-                        return textResult({ ...parsed, note: "Feedback sent anonymously (API key invalid or expired)." });
+                        return structuredTextResult({ ...parsed, deferred: false, note: "Feedback sent anonymously (API key invalid or expired)." }, "Feedback sent anonymously (API key invalid or expired).");
                     }
                 }
-                catch { /* fall through to original error */ }
+                catch { /* fall through */ }
+            }
+            if (isDeferworthy(err)) {
+                const e = err;
+                const queued = await enqueueDeferredFeedback("barsom", body, {
+                    status: e.httpStatus,
+                    error_code: e.errorCode,
+                    request_id: e.requestId,
+                    message: e.message,
+                });
+                const api_health = await probeApiHealth().catch(() => ({
+                    liveness: "down",
+                    readiness: "unknown",
+                    storage: "not_probed",
+                }));
+                const pending = await listDeferredFeedback("barsom");
+                return structuredTextResult({
+                    ok: true,
+                    deferred: true,
+                    deferred_id: queued.id,
+                    deferred_path: queued.path,
+                    deferred_pending: pending.length,
+                    error_code: e.errorCode ?? "api_unreachable",
+                    cause: e.cause ?? "api_unreachable",
+                    request_id: e.requestId ?? null,
+                    api_health,
+                    message: "API/storage unavailable — feedback saved locally and will be sent on the next successful send_feedback call.",
+                }, [
+                    "Feedback deferred (API/storage unavailable).",
+                    `Saved to ${queued.path}`,
+                    e.requestId ? `request_id=${e.requestId}` : null,
+                    e.errorCode ? `error_code=${e.errorCode}` : null,
+                    `api_health.liveness=${api_health.liveness} (storage not_probed)`,
+                    "Retry send_feedback later to flush the local queue.",
+                ]
+                    .filter(Boolean)
+                    .join(" | "));
             }
             throw err;
         }

package/dist/tools/guide_barsom.js

@@ -1,15 +1,20 @@
 import { registerAuditedTool } from "../audit.js";
-import { fetchWorkflowGuideFromApi } from "../shared.js";
+import { fetchWorkflowGuideFromApi, UNAVAILABLE_RETRY_AFTER_SEC } from "../shared.js";
 /** Minimal orientation when the API is unreachable; full SOP lives on GET /v1/docs/workflow. */
 const OFFLINE_STUB = `## Offline / API unavailable
 
-Configure \`BARIVIA_API_KEY\` and optional \`BARIVIA_API_URL\`, then call **guide_barsom_workflow** again. Full tool map, async rules, training modes, and step-by-step SOP are loaded from the Barivia API (authenticated) and scoped to your plan.
+Configure \`BARIVIA_API_KEY\` and optional \`BARIVIA_API_URL\`, then call **guide_barsom_workflow** again when online. Full tool map, async rules, training modes, and step-by-step SOP are loaded from the Barivia API (authenticated) and scoped to your plan.
 
-**Core tools:** \`datasets\`, \`train\` (map, siom_map, impute, floop_siom where entitled), \`jobs\` (status/list/compare — lifecycle only), \`results\`, \`inference\`, \`account\`, \`training_guidance\`, \`guide_barsom_workflow\`.
+**Still usable offline:** already-downloaded results, local CSVs, draft notes / feedback drafts (queued under \`~/.barivia/deferred-feedback\`).
+**Needs API:** upload, train, list/status, feedback flush, other cloud tools.
+
+**Core tools (when healthy):** \`datasets\`, \`train\` (map, siom_map, impute, floop_siom where entitled), \`jobs\` (status/list/compare — lifecycle only), \`results\`, \`inference\`, \`account\`, \`training_guidance\`, \`guide_barsom_workflow\`.
+
+**Degraded-session rules:** Do not paste Cloudflare/HTML into chat — one-sentence summary. The proxy already burst-retried (3×~2s); wait ~${UNAVAILABLE_RETRY_AFTER_SEC}s (see \`retry_after_sec\`) before another round, then ask the user. Check \`account(health)\` or \`account(status)\` before large uploads/trains (\`ok:false\` + \`retry_after_sec\` = pause, not a crash). Save feedback drafts locally; resend via \`send_feedback\` when healthy.
 
 **Parameter hints:** call \`training_guidance\` (also API-scoped). **Async:** poll \`jobs(action=status)\` every 10–15s after submit.`;
 export function registerGuideBarsomTool(server) {
-    registerAuditedTool(server, "guide_barsom_workflow", "Plan-scoped orientation: proxy model, tool categories, async rules, training modes, and step-by-step SOP — loaded from the Barivia API when online. Call at the start of mapping work. Offline: short stub. For field-level parameters, use training_guidance; for a narrative pre-train checklist, use the prepare_training prompt.", {}, async () => {
+    registerAuditedTool(server, "guide_barsom_workflow", "Plan-scoped orientation: proxy model, tool categories, async rules, training modes, and step-by-step SOP — loaded from the Barivia API when online. Call at the start of mapping work. Offline: short stub with offline-vs-API capabilities and degraded-session rules. For field-level parameters, use training_guidance; for a narrative pre-train checklist, use the prepare_training prompt.", {}, async () => {
         const md = await fetchWorkflowGuideFromApi();
         if (md) {
             const text = "Plan-scoped workflow (from Barivia API). Text below reflects your API key / plan.\n\n" + md;

package/dist/tools/jobs.js

@@ -3,13 +3,15 @@ import { registerAuditedTool } from "../audit.js";
 import { apiCall, textResult } from "../shared.js";
 import { formatJobCancelText, formatJobStatusText } from "../job_status_format.js";
 import { DEFAULT_BLOCK_UNTIL_SEC, DEFAULT_POLL_INTERVAL_SEC, runJobMonitor } from "../job_monitor.js";
+import { buildJobsListQuery, extractJobsList, formatJobInventoryLine, } from "../inventory_format.js";
 export const JOBS_DESCRIPTION_BASE = `Manage and inspect jobs (lifecycle only).
 
 | Action | Use when |
 |--------|----------|
 | monitor | After async submit — blocks server-side with 5s snapshots until terminal (preferred for agents) |
 | status | One-shot progress check (manual poll every 10–15s if not using monitor) |
-| list | Finding job IDs / reviewing pipeline state (optionally filter by dataset_id) |
+| list | Finding job IDs / reviewing pipeline state (slim by default; filter by dataset_id/status/job_type; paginate with limit+cursor) |
+| update | Edit label / description / tags on an existing job |
 | compare | Picking the best TRAINING run from a set (metrics table). NOT inference(compare), which diffs one dataset's distribution against the training set. |
 | cancel | Stopping a running or pending job to free the worker |
 | delete | Permanently removing a job and all its S3 result files |
@@ -28,9 +30,13 @@ ASYNC POLLING PROTOCOL (action=status):
 - Map training typical times: 10×10 ~30s | 20×20 ~3–5 min | 40×40 ~15–30 min.
 - completed → results(action=get); failed → read error + optional failure_stage (preprocessing/training/metrics/visualization/upload): memory error → smaller grid/batch and retrain; column missing → datasets(action=preview); NaN on a standard map → train(action=impute) for sparse columns or clean the CSV.
 
+action=list: Slim rows by default (label,id,status,job_type,dataset_id,created_at,result_ref,description,tags — no fat params). Use status/job_type/has_results/limit/cursor to page. has_results=true is the results catalog. Pass fields="full" only when you need params/error.
+action=update: PATCH label/description/tags (pass at train submit when possible).
 action=compare: metrics table (QE, TE, explained variance, silhouette) for 2+ COMPLETED TRAINING jobs — pick the best run in a sweep. NOT inference(action=compare) (single trained job + second dataset → density-diff heatmap). Only hyperparameter columns that differ across runs are shown; pass label="…" at train time for readable rows.
 action=cancel: Not instant — worker checks between phases. Expect up to 30s delay.
-action=delete: WARNING — job ID will no longer work with results or any other tool.`;
+action=delete: WARNING — job ID will no longer work with results or any other tool.
+
+Org overview: prefer account(action=inventory) for a markdown datasets+jobs inventory.`;
 /**
  * Render the jobs(compare) markdown table. Strategy: always show job_id (or label
  * if present) + the four core metrics (QE, TE, Expl.Var, Silhouette); add any
@@ -143,12 +149,12 @@ export function renderCompareTable(comparisons) {
 export function registerJobsTool(server, description) {
     registerAuditedTool(server, "jobs", description, {
         action: z
-            .enum(["status", "monitor", "list", "compare", "cancel", "delete"])
-            .describe("status: one-shot check; monitor: block until terminal with snapshots; list/compare/cancel/delete as labeled. (Training via train; scoring via inference.)"),
+            .enum(["status", "monitor", "list", "update", "compare", "cancel", "delete"])
+            .describe("status: one-shot check; monitor: block until terminal with snapshots; list/update/compare/cancel/delete as labeled. (Training via train; scoring via inference.)"),
         job_id: z
             .string()
             .optional()
-            .describe("Job ID — required for action=status, monitor, cancel, delete."),
+            .describe("Job ID — required for action=status, monitor, update, cancel, delete."),
         block_until_sec: z
             .number()
             .int()
@@ -173,8 +179,38 @@ export function registerJobsTool(server, description) {
             .string()
             .optional()
             .describe("action=list: filter jobs by this dataset ID."),
+        status: z
+            .enum(["pending", "running", "completed", "failed", "cancelled"])
+            .optional()
+            .describe("action=list: filter by job status."),
+        job_type: z
+            .string()
+            .optional()
+            .describe("action=list: filter by MCP job_type label (e.g. train_map, train_impute, predict, cfd_mesh_convergence)."),
+        has_results: z
+            .boolean()
+            .optional()
+            .describe("action=list: true = completed jobs with result_ref (results catalog)."),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .optional()
+            .describe("action=list: page size (default 50, max 100)."),
+        cursor: z
+            .string()
+            .optional()
+            .describe("action=list: next_cursor from a prior list response for keyset pagination."),
+        fields: z
+            .enum(["slim", "full"])
+            .optional()
+            .describe("action=list: slim (default, no params) or full (includes params/error)."),
+        label: z.string().optional().describe("action=update: new job label (≤120 chars)."),
+        description: z.string().optional().describe("action=update: free-text description (pass \"\" to clear)."),
+        tags: z.array(z.string()).optional().describe("action=update: replace tags (pass [] to clear)."),
     }, async (args) => {
-        const { action, job_id, job_ids, dataset_id, block_until_sec, poll_interval_sec, wait_finalize } = args;
+        const { action, job_id, job_ids, dataset_id, status, job_type, has_results, limit, cursor, fields, block_until_sec, poll_interval_sec, wait_finalize, label, description, tags, } = args;
         // ---- Lifecycle ----
         if (action === "monitor") {
             if (!job_id)
@@ -188,17 +224,38 @@ export function registerJobsTool(server, description) {
             return { content: [{ type: "text", text: formatJobStatusText(job_id, data) }] };
         }
         if (action === "list") {
-            const listPath = dataset_id ? `/v1/jobs?dataset_id=${dataset_id}` : "/v1/jobs";
-            const data = (await apiCall("GET", listPath));
-            if (Array.isArray(data)) {
-                const lines = data.map((job) => {
-                    const id = String(job.id ?? "");
-                    const st = String(job.status ?? "");
-                    const label = job.label != null && job.label !== "" ? String(job.label) : null;
-                    return label ? `${label} (id: ${id}) — ${st}` : `id: ${id} — ${st}`;
-                });
-                return { content: [{ type: "text", text: lines.length > 0 ? lines.join("\n") : "No jobs found." }] };
+            const listPath = buildJobsListQuery({
+                dataset_id, status, job_type, has_results, limit, cursor, fields,
+            });
+            const data = await apiCall("GET", listPath);
+            const { jobs, next_cursor } = extractJobsList(data);
+            const lines = jobs.map((job) => formatJobInventoryLine(job));
+            if (next_cursor) {
+                lines.push("");
+                lines.push(`next_cursor: ${next_cursor}`);
+                lines.push(`Tip: jobs(action=list, cursor="${next_cursor}", limit=${limit ?? 50}) for the next page.`);
+            }
+            return {
+                content: [{
+                        type: "text",
+                        text: lines.length > 0 ? lines.join("\n") : "No jobs found.",
+                    }],
+            };
+        }
+        if (action === "update") {
+            if (!job_id)
+                throw new Error("jobs(update) requires job_id");
+            const body = {};
+            if (label !== undefined)
+                body.label = label;
+            if (description !== undefined)
+                body.description = description;
+            if (tags !== undefined)
+                body.tags = tags;
+            if (Object.keys(body).length === 0) {
+                throw new Error("jobs(update) requires at least one of label, description, tags");
             }
+            const data = await apiCall("PATCH", `/v1/jobs/${job_id}`, body);
             return textResult(data);
         }
         if (action === "compare") {

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;