@barivia/barsom-mcp 0.22.4 → 0.23.2

package/dist/tools/datasets.js

@@ -6,6 +6,8 @@ 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";
+import { PERIODICITY_ROW_ORDER_NOTE, SMALL_N_SOFT, buildCpuScaleGuidanceLines, buildSmallNGuardrailLines, } from "../training_scale_guidance.js";
 /**
  * Normalize a nullable string field from the API. Returns "" for absent values,
  * empty strings, and the literal SQL/serialization sentinels "missing"/"null"
@@ -110,6 +112,16 @@ function formatAnalyzeResult(data, dataset_id) {
         lines.push(``);
     }
     const nextSteps = [];
+    const nRows = typeof totalRows === "number" && Number.isFinite(totalRows) ? totalRows : 0;
+    if (nRows > 0 && nRows < SMALL_N_SOFT) {
+        nextSteps.push(...buildSmallNGuardrailLines({ n: nRows, nFeatures: trainList.length || columns.length }));
+    }
+    if (nRows > 0) {
+        nextSteps.push(...buildCpuScaleGuidanceLines(nRows));
+    }
+    if (considerDropping.length > 0) {
+        nextSteps.push(`Drop redundant correlated columns before train (e.g. keep distance OR lat/lon, not all three when |r|>0.9): ${considerDropping.join(", ")}.`);
+    }
     if (trainList.length > 0) {
         nextSteps.push(`Train with columns: [${trainList.join(", ")}].`);
     }
@@ -119,11 +131,11 @@ function formatAnalyzeResult(data, dataset_id) {
     const periodicStrong = periodicity.filter((p) => p.dominant_score > 0.4);
     if (periodicStrong.length > 0) {
         const lags = [...new Set(periodicStrong.map((p) => p.dominant_lag))].sort((a, b) => a - b);
-        nextSteps.push(`Note: periodicity is computed on row order. If your CSV is not sorted by time, ignore lag-based suggestions; only use cyclic_features when the column is genuinely cyclic (e.g. hour, month, angle).`);
+        nextSteps.push(`Note: ${PERIODICITY_ROW_ORDER_NOTE}`);
         nextSteps.push(`Columns show periodic behavior at lags ${lags.join(", ")} (assuming row order is meaningful). Consider cyclic_features or temporal_features with matching periods.`);
         nextSteps.push(`For datetime columns: run datasets(action=preview) for temporal_suggestions; match lags (e.g. 365→day_of_year, 12→month, 7→day_of_week, 24→hour_of_day) to choose which temporal components to extract.`);
     }
-    nextSteps.push(`Then call train(action=map, dataset_id=${dataset_id}, columns=[...], ...).`);
+    nextSteps.push(`Then call train(action=map, dataset_id=${dataset_id}, columns=[...], ...) — omit grid_x/grid_y for auto-size unless you intentionally override.`);
     lines.push(`Next steps:`, ...nextSteps.map((s) => `  ${s}`));
     return lines.join("\n");
 }
@@ -137,9 +149,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 | ONLY when the user asks for row_range, filters, or sample_n — never auto-shrink before train/analyze |
+| 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 (CPU quick is fast to ~100k; do not sample_n by default below that) |
 | 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,9 +164,12 @@ 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)
@@ -175,9 +191,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)"),
@@ -266,7 +284,7 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
             .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");
@@ -306,7 +324,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);
@@ -344,12 +367,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.`;
@@ -373,6 +401,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"));
@@ -466,7 +498,13 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
                     lines.push(`| ${cols.map((c) => String(row[c] ?? "")).join(" | ")} |`);
                 }
             }
-            lines.push(``, `Suggested next step: train(action=map, dataset_id=${dataset_id}, ...) or use the prepare_training prompt; to add derived columns use datasets(action=add_expression, dataset_id=${dataset_id}, name=..., expression=...).`);
+            if (totalRows > 0 && totalRows < SMALL_N_SOFT) {
+                lines.push(``, ...buildSmallNGuardrailLines({ n: totalRows, nFeatures: cols.length }));
+            }
+            if (totalRows > 0) {
+                lines.push(``, ...buildCpuScaleGuidanceLines(totalRows));
+            }
+            lines.push(``, `Suggested next step: datasets(action=analyze) then train(action=map, dataset_id=${dataset_id}, ...) or use the prepare_training prompt; to add derived columns use datasets(action=add_expression, dataset_id=${dataset_id}, name=..., expression=...).`);
             return { content: [{ type: "text", text: lines.join("\n") }] };
         }
         if (action === "analyze") {
@@ -681,15 +719,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." }] };
             }
@@ -699,11 +731,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))` : "",
@@ -712,6 +747,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/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=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=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 (including SIOM knobs gamma/gamma_f/siom_decay/siom_penalty/reset_per_epoch when they vary); pass label="…" at train time for readable rows.
 action=cancel: Not instant — worker checks between phases. Expect up to 30s delay.
-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
@@ -74,7 +80,11 @@ export function renderCompareTable(comparisons) {
         { key: "n_initial", label: "NInitial", render: fmtAny },
         { key: "growth_interval", label: "GrowthInt", render: fmtAny },
         { key: "gamma", label: "Gamma", render: fmtAny },
+        { key: "gamma_f", label: "GammaF", render: fmtAny },
         { key: "siom_decay", label: "SIOMDecay", render: fmtAny },
+        { key: "siom_penalty", label: "SIOMPenalty", render: fmtAny },
+        { key: "penalty_alpha", label: "Penaltyα", render: fmtAny },
+        { key: "reset_per_epoch", label: "Reset/Epoch", render: fmtAny },
         { key: "elastic_lambda", label: "Elasticλ", render: fmtAny },
         { key: "elastic_mu", label: "Elasticμ", render: fmtAny },
         { key: "elastic_anchor", label: "ElasticAnchor", render: fmtAny },
@@ -143,12 +153,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 +183,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 +228,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

@@ -3,6 +3,7 @@ import fs from "node:fs/promises";
 import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
 import { apiCall, apiRawCall, getWorkspaceRootAsync, sandboxPath, pollUntilComplete, tryAttachImage, resetInlineAttachBudget, attachResultsImages, resolveOutputDpi, POLL_RECOLOR_MAX_MS, fmtDensityDiffNode, getCaptionForImage, shouldFetchAllRemainingFigures, mimeForFilename, structuredTextResult, } from "../shared.js";
+import { formatSiomOccupationSummary } from "../siom_occupation_format.js";
 export function registerResultsTool(server) {
     registerAuditedTool(server, "results", `Retrieve, recolor, download, or export figures and metrics for a completed map job. Presentation and artifact access only — operations on the frozen map (predict, compare, project, impute_column, transition_flow) live in **inference**.
 
@@ -225,7 +226,10 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
                     hitStats.active_node_fraction !== undefined
                         ? `Grid BMU occupancy: ${(Number(hitStats.active_node_fraction) * 100).toFixed(1)}% active nodes on the map grid`
                         : "",
-                    ...(siom ? [`SIOM layer coverage (distinct from grid dead nodes) — utilization: ${fmt(siom.utilization)} | dead_fraction: ${fmt(siom.dead_fraction)} | siom_qe: ${fmt(siom.siom_qe)}`] : []),
+                    ...formatSiomOccupationSummary(siom, {
+                        files: summary.files ?? [],
+                        compact: true,
+                    }),
                     hitStats.grid_suggestion ? `Grid hint: ${String(hitStats.grid_suggestion)}` : "",
                     ...(policy.auto_rules_applied && Array.isArray(policy.auto_rules_applied) && policy.auto_rules_applied.length > 0
                         ? [`Auto policy: ${policy.auto_rules_applied.join(", ")} (${policy.viz_mode ?? "viz"}, metrics=${policy.quality_metrics ?? "?"})`]
@@ -296,19 +300,15 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
                     `Coverage Assessment:`,
                     `  Status:        ${coverageStatus}${isDegenerate ? " *** NON-COMPETITIVE ***" : isWarning ? " * CAUTION *" : ""}`,
                     `  Diagnosis:     ${String(coverage.diagnosis ?? "No plain-language diagnosis available.")}`,
-                    `  Utilization:   ${siom.utilization !== undefined ? Number(siom.utilization).toFixed(4) : "N/A"}`,
-                    `  SIOM dead fraction (layer coverage, not grid BMU hits): ${siom.dead_fraction !== undefined ? Number(siom.dead_fraction).toFixed(4) : "N/A"}`,
+                    ...formatSiomOccupationSummary(siom, { files }),
                     `  Occupied nodes:${hitStats.occupied_nodes !== undefined ? ` ${hitStats.occupied_nodes}` : " N/A"}`,
                     `  Top hit share: ${hitStats.top_hit_share !== undefined ? Number(hitStats.top_hit_share).toFixed(4) : "N/A"}`,
-                    `  Gini:          ${siom.gini !== undefined ? Number(siom.gini).toFixed(4) : "N/A"}`,
-                    `  Entropy:       ${siom.entropy !== undefined ? Number(siom.entropy).toFixed(4) : "N/A"}`,
-                    `  SIOM gamma:    ${siom.gamma !== undefined ? Number(siom.gamma).toFixed(3) : "N/A"} | decay: ${siom.decay !== undefined ? Number(siom.decay).toFixed(4) : "N/A"}`,
                     ...(summary.elastic ? (() => {
                         const el = summary.elastic;
                         return [`  Elastic:       λ=${el.lambda !== undefined ? Number(el.lambda).toFixed(3) : "0"} μ=${el.mu !== undefined ? Number(el.mu).toFixed(3) : "0"} anchor=${el.anchor !== undefined ? Number(el.anchor).toFixed(3) : "0"}`];
                     })() : []),
                     ``,
-                    `Layout tuning: if Voronoi cells look crowded in weight space (high top_hit_share), reduce max_nodes and/or raise gamma/siom_decay before growth_interval. See training_guidance keys floop_voronoi_crowding, floop_siom_params, floop_elastic_params.`,
+                    `Layout tuning: if Voronoi cells look crowded in weight space (high top_hit_share), reduce max_nodes and/or raise gamma/siom_decay before growth_interval. See training_guidance keys floop_voronoi_crowding, floop_siom_params, floop_elastic_params, siom_gamma.`,
                     ``,
                     `Quality Metrics:`,
                     `  Quantization Error: ${summary.quantization_error !== undefined ? Number(summary.quantization_error).toFixed(4) : "N/A"}${qeNote}`,
@@ -386,11 +386,11 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
                     ...(compLines ? [`Component value ranges:\n${compLines}`] : []),
                     ...(clusterLines ? ["", "Cluster map (defining features):", clusterLines] : []),
                     ...(topCorrLine ? ["", topCorrLine] : []),
-                    ...(siom ? ["", "SIOM layer coverage (distinct from grid dead nodes):",
-                        `  Utilization: ${siom.utilization !== undefined ? Number(siom.utilization).toFixed(4) : "N/A"}`,
-                        `  SIOM dead fraction: ${siom.dead_fraction !== undefined ? Number(siom.dead_fraction).toFixed(4) : "N/A"}`,
-                        `  Gini: ${siom.gini !== undefined ? Number(siom.gini).toFixed(4) : "N/A"}`,
-                        `  Entropy: ${siom.entropy !== undefined ? Number(siom.entropy).toFixed(4) : "N/A"}`] : []),
+                    ...(siom
+                        ? ["", ...formatSiomOccupationSummary(siom, {
+                                files: summary.files ?? [],
+                            })]
+                        : []),
                     ``, `Features: ${features.join(", ")}`,
                     summary.selected_columns ? `Selected columns: ${summary.selected_columns.join(", ")}` : "",
                     summary.transforms ? `Transforms: ${Object.entries(summary.transforms).map(([k, v]) => `${k}=${v}`).join(", ")}` : "",