@barivia/barsom-mcp 0.21.0 → 0.22.2

package/dist/tools/account.js

@@ -2,28 +2,23 @@ import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
 import { apiCall } from "../shared.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 +30,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 +56,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 +67,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);
@@ -92,63 +82,6 @@ NOT FOR: Training itself — use train(action=map). This tool only manages the a
             }
             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." }] };
-            }
-            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.` }]
-            };
-        }
         if (action === "history") {
             const data = await apiCall("GET", `/v1/compute/history?limit=${limit || 10}`);
             const history = data.history.map((h) => `- ${h.started_at} | ${h.tier} | ${h.duration_minutes} min | $${(h.credits_charged / 100).toFixed(2)}`).join("\n");
@@ -159,11 +92,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, UPLOAD_DATASET_TIMEOUT_MS, LARGE_UPLOAD_BYTES, PRESIGNED_PUT_TIMEOUT_MS, POLL_STAGE_MAX_MS, streamFileSha256, putPresignedStream, } 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,
@@ -269,9 +269,11 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
             if (!name)
                 throw new Error("datasets(upload) requires name");
             let body;
+            let uploadContentType = "text/csv";
             if (file_path) {
                 await apiCall("GET", "/v1/system/info");
                 const resolved = await resolveFilePathForUpload(file_path, server);
+                uploadContentType = resolveUploadContentType(resolved);
                 const lower = resolved.toLowerCase();
                 // Accept pre-gzipped CSV/TSV (.csv.gz / .tsv.gz) so large tables transfer
                 // ~3x smaller. Already-gzipped files are stored as-is (the platform stores
@@ -317,9 +319,9 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
                     // a fresh upload_url and no idempotent_replay flag, so we re-PUT below.
                     if (init.idempotent_replay && !init.upload_url) {
                         return textResult({ id: datasetId, status: init.status, idempotent_replay: true,
-                            suggested_next_step: `datasets(action=preview, dataset_id=${datasetId})` });
+                            suggested_next_step: suggestDatasetPreview(datasetId) });
                     }
-                    await putPresignedStream(init.upload_url, resolved, init.content_type ?? "application/octet-stream", PRESIGNED_PUT_TIMEOUT_MS, isGzipInput);
+                    await putPresignedStream(init.upload_url, resolved, init.content_type ?? uploadContentType, PRESIGNED_PUT_TIMEOUT_MS, isGzipInput);
                     const fin = (await apiCall("POST", `/v1/datasets/${datasetId}/finalize`, {}));
                     const jobId = (fin.id ?? fin.job_id);
                     const poll = await pollUntilComplete(jobId, POLL_STAGE_MAX_MS);
@@ -332,8 +334,8 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
                         status: ready ? "ready" : "staging",
                         job_id: jobId,
                         suggested_next_step: ready
-                            ? `datasets(action=preview, dataset_id=${datasetId}) to inspect columns before training.`
-                            : `Still staging; poll jobs(action=status, job_id="${jobId}") then datasets(action=preview, dataset_id=${datasetId}).`,
+                            ? `${suggestDatasetPreview(datasetId)} to inspect columns before training.`
+                            : `Still staging; poll jobs(action=status, job_id="${jobId}") then ${suggestDatasetPreview(datasetId)}.`,
                     });
                 }
                 // Small pre-gzipped files: send the bytes as-is (the API decompresses
@@ -342,13 +344,13 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
                     const gzBytes = await fs.readFile(resolved);
                     const data = (await apiCall("POST", "/v1/datasets", gzBytes, {
                         "X-Dataset-Name": name,
-                        "Content-Type": "text/csv",
+                        "Content-Type": uploadContentType,
                         "Content-Encoding": "gzip",
                         "Idempotency-Key": createHash("sha256").update(`${name}\n`).update(gzBytes).digest("hex"),
                     }, UPLOAD_DATASET_TIMEOUT_MS));
                     const gid = data.id ?? data.dataset_id;
                     if (gid != null)
-                        data.suggested_next_step = `Suggested next step: datasets(action=preview, dataset_id=${gid}) to inspect columns before training.`;
+                        data.suggested_next_step = `${suggestDatasetPreview(String(gid))} to inspect columns before training.`;
                     return textResult(data);
                 }
                 body = await fs.readFile(resolved, "utf-8");
@@ -364,7 +366,7 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
             const GZIP_THRESHOLD = 1024 * 1024; // 1 MB
             const uploadHeaders = {
                 "X-Dataset-Name": name,
-                "Content-Type": "text/csv",
+                "Content-Type": uploadContentType,
                 // Deterministic key so a timed-out retry of the SAME upload reconciles to
                 // the original dataset server-side instead of creating a duplicate.
                 "Idempotency-Key": createHash("sha256").update(`${name}\n`).update(body).digest("hex"),
@@ -377,7 +379,7 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
             const data = (await apiCall("POST", "/v1/datasets", uploadBody, uploadHeaders, UPLOAD_DATASET_TIMEOUT_MS));
             const id = data.id ?? data.dataset_id;
             if (id != null)
-                data.suggested_next_step = `Suggested next step: datasets(action=preview, dataset_id=${id}) to inspect columns before training.`;
+                data.suggested_next_step = `${suggestDatasetPreview(String(id))} to inspect columns before training.`;
             return textResult(data);
         }
         if (action === "preview") {
@@ -477,12 +479,22 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
                 const jobId = (submit.id ?? submit.job_id);
                 if (!jobId)
                     throw new Error("analyze did not return a job id");
-                const poll = await pollUntilComplete(jobId, POLL_DERIVE_MAX_MS);
+                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: "If the dataset is very large, try datasets(action=subset, sample_n=10000) then analyze again.",
+                    }, 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);
@@ -492,7 +504,8 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
                     data = (await apiCall("GET", `/v1/datasets/${dataset_id}/analyze`));
                 }
                 else {
-                    throw err;
+                    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.`);
                 }
             }
             return { content: [{ type: "text", text: formatAnalyzeResult(data, dataset_id) }] };

package/dist/tools/guide_barsom.js

@@ -5,7 +5,7 @@ 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.
 
-**Core tools:** \`datasets\`, \`jobs\` (train_map, train_siom_map, train_floop_siom where entitled), \`results\`, \`inference\`, \`account\`, \`training_guidance\`, \`guide_barsom_workflow\`.
+**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\`.
 
 **Parameter hints:** call \`training_guidance\` (also API-scoped). **Async:** poll \`jobs(action=status)\` every 10–15s after submit.`;
 export function registerGuideBarsomTool(server) {

package/dist/tools/inference.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
-import { apiCall, pollUntilComplete, tryAttachImage } from "../shared.js";
+import { apiCall, pollUntilComplete, tryAttachImage, POLL_INFERENCE_MAX_MS, POLL_PROJECT_MAX_MS, resolveOutputDpi, fmtDensityDiffNode } from "../shared.js";
 import { pollPrepareIfPresent } from "../inference_prepare.js";
 const PREDICT_PREVIEW_ROW_CAP = 10;
 /** One line per scored row when worker embedded `predictions_preview` (n_rows ≤ cap). Exported for tests. */
@@ -123,8 +123,7 @@ action=report: Returns a report manifest for the given job_id (job must be compl
         top_k: z.number().int().min(1).optional().default(10)
             .describe("action=transition_flow: number of top-flow nodes in the statistics summary (default 10)."),
     }, async ({ action, job_id, dataset_id, columns, rows, output, colormap, output_format, output_dpi, top_n, target_column, only_missing, impute_aggregation, cv_folds, target_column_kind, weighting, inputs, lag, min_transitions, top_k }) => {
-        const dpiMap = { standard: 1, retina: 2, print: 4 };
-        const numericDpi = dpiMap[output_dpi ?? "retina"] ?? 2;
+        const numericDpi = resolveOutputDpi(output_dpi);
         if (action === "batch_predict")
             return runBatchPredict({ job_id, inputs });
         if (action === "transition_flow") {
@@ -136,10 +135,10 @@ action=report: Returns a report manifest for the given job_id (job must be compl
             if (colormap !== undefined)
                 body.colormap = colormap;
             if (output_dpi && output_dpi !== "retina")
-                body.output_dpi = dpiMap[output_dpi] ?? 2;
+                body.output_dpi = resolveOutputDpi(output_dpi);
             const data = (await apiCall("POST", `/v1/results/${job_id}/transition-flow`, body));
             const flowJobId = data.id;
-            const poll = await pollUntilComplete(flowJobId, 120_000);
+            const poll = await pollUntilComplete(flowJobId, POLL_INFERENCE_MAX_MS);
             if (poll.status === "completed") {
                 const res = (await apiCall("GET", `/v1/results/${flowJobId}`));
                 const summary = (res.summary ?? {});
@@ -195,7 +194,7 @@ action=report: Returns a report manifest for the given job_id (job must be compl
             const predictJobId = data.id;
             const prepareId = await pollPrepareIfPresent(data, "inference(predict)");
             // annotated runs over the full dataset; allow up to 120s like compact
-            const poll = await pollUntilComplete(predictJobId, 120_000);
+            const poll = await pollUntilComplete(predictJobId, POLL_INFERENCE_MAX_MS);
             if (poll.status === "completed") {
                 const results = (await apiCall("GET", `/v1/results/${predictJobId}`));
                 const summary = (results.summary ?? {});
@@ -254,7 +253,7 @@ action=report: Returns a report manifest for the given job_id (job must be compl
                 body.weighting = weighting;
             const data = (await apiCall("POST", `/v1/results/${job_id}/impute_column`, body));
             const imputeJobId = data.id;
-            const poll = await pollUntilComplete(imputeJobId, 120_000);
+            const poll = await pollUntilComplete(imputeJobId, POLL_INFERENCE_MAX_MS);
             if (poll.status === "completed") {
                 const results = (await apiCall("GET", `/v1/results/${imputeJobId}`));
                 const summary = (results.summary ?? {});
@@ -281,19 +280,18 @@ action=report: Returns a report manifest for the given job_id (job must be compl
                 body.colormap = colormap;
             const data = (await apiCall("POST", `/v1/results/${job_id}/compare_datasets`, body));
             const compareJobId = data.id;
-            const poll = await pollUntilComplete(compareJobId, 120_000);
+            const poll = await pollUntilComplete(compareJobId, POLL_INFERENCE_MAX_MS);
             if (poll.status === "completed") {
                 const results = (await apiCall("GET", `/v1/results/${compareJobId}`));
                 const summary = (results.summary ?? {});
                 const gained = summary.top_gained_nodes ?? [];
                 const lost = summary.top_lost_nodes ?? [];
-                const fmtNode = (n) => `  node ${n.node_index ?? "?"} [${(n.coords ?? [0, 0]).map(v => Number(v).toFixed(1)).join(",")}] Δ=${Number(n.density_diff ?? 0).toFixed(4)}`;
                 const n = top_n ?? 10;
                 const content = [{ type: "text", text: [
                             `Dataset comparison — job: ${compareJobId}`,
                             `Dataset A rows: ${summary.n_rows_a ?? "?"} | Dataset B rows: ${summary.n_rows_b ?? "?"}`,
-                            `Top ${Math.min(n, gained.length)} gained (B > A):`, ...gained.slice(0, n).map(fmtNode),
-                            `Top ${Math.min(n, lost.length)} lost (A > B):`, ...lost.slice(0, n).map(fmtNode),
+                            `Top ${Math.min(n, gained.length)} gained (B > A):`, ...gained.slice(0, n).map(fmtDensityDiffNode),
+                            `Top ${Math.min(n, lost.length)} lost (A > B):`, ...lost.slice(0, n).map(fmtDensityDiffNode),
                         ].join("\n") }];
                 content.push({ type: "text", text: "Density difference — Positive (red) = Dataset B gained density; Negative (blue) = Dataset A had more density." });
                 await tryAttachImage(content, compareJobId, `density_diff.${summary.output_format ?? output_format ?? "png"}`);
@@ -314,7 +312,7 @@ action=report: Returns a report manifest for the given job_id (job must be compl
             const data = (await apiCall("POST", `/v1/results/${job_id}/project_columns`, body));
             const projJobId = data.id;
             const prepareId = await pollPrepareIfPresent(data, "inference(project_columns)");
-            const poll = await pollUntilComplete(projJobId, 90_000);
+            const poll = await pollUntilComplete(projJobId, POLL_PROJECT_MAX_MS);
             if (poll.status === "completed") {
                 const results = (await apiCall("GET", `/v1/results/${projJobId}`));
                 const summary = (results.summary ?? {});

package/dist/tools/results.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import fs from "node:fs/promises";
 import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
-import { apiCall, apiRawCall, getWorkspaceRootAsync, sandboxPath, pollUntilComplete, tryAttachImage, resetInlineAttachBudget, getResultsImagesToFetch, getCaptionForImage, shouldFetchAllRemainingFigures, mimeForFilename, } from "../shared.js";
+import { apiCall, apiRawCall, getWorkspaceRootAsync, sandboxPath, pollUntilComplete, tryAttachImage, resetInlineAttachBudget, attachResultsImages, resolveOutputDpi, POLL_RECOLOR_MAX_MS, fmtDensityDiffNode, getCaptionForImage, shouldFetchAllRemainingFigures, mimeForFilename, structuredTextResult, } from "../shared.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**.
 
@@ -85,7 +85,7 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
             .optional()
             .describe("action=export: training_log=learning curve; weights=weight matrix; nodes=per-node stats; clusters=regime boundaries; transition_matrix=Markov transition matrix"),
     }, async ({ action, job_id, figures, include_individual, include_json, folder, colormap, output_format, output_dpi, recolor_figures, export_type: exportType }) => {
-        const dpiMap = { standard: 1, retina: 2, print: 4 };
+        const figuresArg = figures;
         if (action === "get") {
             resetInlineAttachBudget();
             const data = (await apiCall("GET", `/v1/results/${job_id}`));
@@ -119,13 +119,7 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
                         ``, `Arrows show net directional drift. Long/bright = frequent transitions. Short = stable states.`,
                         `Background = U-matrix. Use results(action=transition_flow, lag=N) with larger N for longer-term structure.`,
                     ].join("\n") });
-                for (const name of getResultsImagesToFetch(jobType, summary, figures, include_individual)) {
-                    const cap = getCaptionForImage(name);
-                    if (cap)
-                        content.push({ type: "text", text: cap });
-                    await tryAttachImage(content, job_id, name);
-                    inlinedImages.add(name);
-                }
+                await attachResultsImages(content, job_id, jobType, summary, figuresArg, include_individual, inlinedImages);
             }
             else if (jobType === "project_variable") {
                 const varName = summary.variable_name ?? "variable";
@@ -140,13 +134,7 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
                         `  Mean: ${stats.mean !== undefined ? Number(stats.mean).toFixed(3) : "N/A"}`,
                         `  Nodes with data: ${stats.n_nodes_with_data ?? "N/A"}`,
                     ].join("\n") });
-                for (const name of getResultsImagesToFetch(jobType, summary, figures, include_individual)) {
-                    const cap = getCaptionForImage(name);
-                    if (cap)
-                        content.push({ type: "text", text: cap });
-                    await tryAttachImage(content, job_id, name);
-                    inlinedImages.add(name);
-                }
+                await attachResultsImages(content, job_id, jobType, summary, figuresArg, include_individual, inlinedImages);
             }
             else if (jobType === "project_columns") {
                 const cols = summary.columns ?? [];
@@ -158,18 +146,12 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
                     ...Object.entries(colStats).map(([col, s]) => `  ${col}: nodes=${s.n_nodes_with_data ?? "?"} | min=${s.min !== undefined ? Number(s.min).toFixed(3) : "—"} | max=${s.max !== undefined ? Number(s.max).toFixed(3) : "—"}`),
                 ];
                 content.push({ type: "text", text: lines.join("\n") });
-                for (const name of getResultsImagesToFetch(jobType, summary, figures, include_individual)) {
-                    const cap = getCaptionForImage(name);
-                    if (cap)
-                        content.push({ type: "text", text: cap });
-                    await tryAttachImage(content, job_id, name);
-                    inlinedImages.add(name);
-                }
+                await attachResultsImages(content, job_id, jobType, summary, figuresArg, include_individual, inlinedImages);
             }
             else if (jobType === "compare_datasets") {
                 const gained = summary.top_gained_nodes ?? [];
                 const lost = summary.top_lost_nodes ?? [];
-                const fmtNode = (n) => `  node ${n.node_index ?? "?"} [${(n.coords ?? [0, 0]).map((v) => Number(v).toFixed(1)).join(",")}] Δ=${Number(n.density_diff ?? 0).toFixed(4)}`;
+                const fmtNode = fmtDensityDiffNode;
                 const lines = [
                     `Dataset Comparison — ${resultsHeader}`,
                     `Parent map job: ${summary.parent_job_id ?? "N/A"} | Dataset A: ${summary.n_rows_a ?? "?"} rows | Dataset B: ${summary.n_rows_b ?? "?"} rows`,
@@ -179,13 +161,7 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
                     ...lost.slice(0, 5).map(fmtNode),
                 ];
                 content.push({ type: "text", text: lines.join("\n") });
-                for (const name of getResultsImagesToFetch(jobType, summary, figures, include_individual)) {
-                    const cap = getCaptionForImage(name);
-                    if (cap)
-                        content.push({ type: "text", text: cap });
-                    await tryAttachImage(content, job_id, name);
-                    inlinedImages.add(name);
-                }
+                await attachResultsImages(content, job_id, jobType, summary, figuresArg, include_individual, inlinedImages);
             }
             else if (jobType === "enrich_dataset") {
                 // Older exports: summary.job_type from stored results (read-only display).
@@ -256,23 +232,22 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
                         : []),
                     cv ? [
                         "",
-                        `Held-out imputation accuracy (cv_folds=${cv.cv_folds ?? "?"}, method=${cv.cv_method ?? "held_out_prototype_on_trained_map"}):`,
+                        `Held-out imputation accuracy (cv_folds=${cv.cv_folds ?? "?"}, method=${cv.cv_method ?? "kfold_holdout_pool"}):`,
                         cv.columns_sampled ? `  (sampled ${cv.columns_evaluated ?? "?"} columns for speed)` : "",
-                        cv.aggregate ? `  Aggregate MAE: ${fmt(cv.aggregate.mae)} | RMSE: ${fmt(cv.aggregate.rmse)}` : "",
-                        "  See quality.csv (header column: feature).",
+                        cv.aggregate ? `  Aggregate MAE/RMSE (non-cyclic columns): ${fmt(cv.aggregate.mae)} | ${fmt(cv.aggregate.rmse)}` : "",
+                        cv.aggregate?.excluded_cyclic_columns
+                            ? `  Excluded cyclic columns from aggregate: ${cv.aggregate.excluded_cyclic_columns}`
+                            : "",
+                        "  See quality.csv — linear: mae/rmse/r2; cyclic_pairs: circ_mae_rad + mean_resultant_length only.",
+                        "  k-fold is relative column difficulty, not external missing-cell ground truth.",
                     ].filter(Boolean).join("\n") : "\nHeld-out accuracy: skipped (cv_folds=0). Set cv_folds=5 to validate imputation.",
                     "",
                     `Artifacts: ${(summary.files ?? []).filter((f) => f !== "summary.json").join(", ")}`,
                     "Next: results(action=download) for imputed.csv / quality.csv; inference(impute_column) with this job_id as parent for held-out columns.",
+                    "Optional imputation_uncertainty.csv pool_std is prototype-neighbourhood dispersion (not calibrated predictive SD).",
                 ].filter((l) => l !== "");
                 content.push({ type: "text", text: lines.join("\n") });
-                for (const name of getResultsImagesToFetch(jobType, summary, figures, include_individual)) {
-                    const cap = getCaptionForImage(name);
-                    if (cap)
-                        content.push({ type: "text", text: cap });
-                    await tryAttachImage(content, job_id, name);
-                    inlinedImages.add(name);
-                }
+                await attachResultsImages(content, job_id, jobType, summary, figuresArg, include_individual, inlinedImages);
             }
             else if (jobType === "reduce_spectral") {
                 const method = String(summary.method ?? "?");
@@ -349,13 +324,7 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
                     files.length > 0 ? `Artifacts: ${files.join(", ")}` : "",
                 ].filter((l) => l !== "");
                 content.push({ type: "text", text: lines.join("\n") });
-                for (const name of getResultsImagesToFetch(jobType, summary, figures, include_individual)) {
-                    const cap = getCaptionForImage(name);
-                    if (cap)
-                        content.push({ type: "text", text: cap });
-                    await tryAttachImage(content, job_id, name);
-                    inlinedImages.add(name);
-                }
+                await attachResultsImages(content, job_id, jobType, summary, figuresArg, include_individual, inlinedImages);
             }
             else {
                 const grid = summary.grid ?? [0, 0];
@@ -438,14 +407,7 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
                     ...((jobType === "train_som" || jobType === "train_siom" || jobType === "train_impute") ? ["", `Next: results_explorer(job_id="${job_id}") to browse all figures interactively; results(action=export, export_type=training_log) for learning curve; results(action=download) to save figures${jobType === "train_impute" ? " (includes imputed.csv)" : ""}; jobs(action=compare, job_ids=[...]) to compare runs; inference(action=predict) to score new data; inference(action=project_columns) to project other variables onto the map.`] : []),
                 ].filter((l) => l !== "").join("\n");
                 content.push({ type: "text", text: textSummary });
-                const imagesToFetch = getResultsImagesToFetch(jobType, summary, figures, include_individual);
-                for (const name of imagesToFetch) {
-                    const cap = getCaptionForImage(name);
-                    if (cap)
-                        content.push({ type: "text", text: cap });
-                    await tryAttachImage(content, job_id, name);
-                    inlinedImages.add(name);
-                }
+                await attachResultsImages(content, job_id, jobType, summary, figuresArg, include_individual, inlinedImages);
             }
             const files = summary.files ?? [];
             const jobType2 = summary.job_type ?? "train_som";
@@ -476,7 +438,16 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
                     : "";
                 content.push({ type: "text", text: `Available: ${files.join(", ")}. ${logicalNames}Use results(action=get, figures=[...]) for specific plots, figures=all for everything, or figures="none" for metrics-only.` });
             }
-            return { content };
+            const structuredPayload = {
+                job_id,
+                job_type: jobType2,
+                label: jobLabel,
+                summary,
+                files,
+                figures_inlined: [...inlinedImages],
+            };
+            const summaryText = content.filter((c) => c.type === "text").map((c) => c.text).join("\n\n");
+            return structuredTextResult(structuredPayload, summaryText, content);
         }
         if (action === "export") {
             if (!exportType)
@@ -633,16 +604,36 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
             }
             await fs.mkdir(resolvedDir, { recursive: true });
             const saved = [];
+            const missing = [];
             for (const filename of toDownload) {
                 try {
                     const { data: buf } = await apiRawCall(`/v1/results/${job_id}/image/${filename}`);
                     await fs.writeFile(path.join(resolvedDir, filename), buf);
                     saved.push(filename);
                 }
-                catch { /* skip missing files */ }
+                catch {
+                    missing.push(filename);
+                }
             }
             const savedDir = path.join(folder, jobSubfolder);
-            return { content: [{ type: "text", text: saved.length > 0 ? `Saved ${saved.length} file(s) to ${savedDir}: ${saved.join(", ")}` : `No files saved. Check job_id and that the job is completed.` }] };
+            if (saved.length === 0) {
+                const missNote = missing.length > 0 ? ` Missing/failed: ${missing.join(", ")}.` : "";
+                return {
+                    content: [{
+                            type: "text",
+                            text: `No files saved.${missNote} Check job_id and that the job is completed.`,
+                        }],
+                };
+            }
+            const missNote = missing.length > 0
+                ? ` Missing/failed (${missing.length}): ${missing.join(", ")}.`
+                : "";
+            return {
+                content: [{
+                        type: "text",
+                        text: `Saved ${saved.length} file(s) to ${savedDir}: ${saved.join(", ")}.${missNote}`,
+                    }],
+            };
         }
         if (action === "recolor") {
             if (!colormap)
@@ -651,11 +642,11 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
                 colormap,
                 figures: recolor_figures ?? ["combined"],
                 output_format: output_format ?? "png",
-                output_dpi: dpiMap[output_dpi ?? "retina"] ?? 2,
+                output_dpi: resolveOutputDpi(output_dpi),
             };
             const data = (await apiCall("POST", `/v1/results/${job_id}/render`, body));
             const newJobId = data.id;
-            const poll = await pollUntilComplete(newJobId, 60_000);
+            const poll = await pollUntilComplete(newJobId, POLL_RECOLOR_MAX_MS);
             if (poll.status === "completed") {
                 const content = [{ type: "text", text: `Re-rendered with colormap "${colormap}". New job_id: ${newJobId}.` }];
                 for (const fig of recolor_figures ?? ["combined"]) {