@barivia/barsom-mcp 0.22.4 → 0.23.2

package/dist/shared.js

@@ -20,12 +20,16 @@ export const API_URL = process.env.BARIVIA_API_URL ??
     "https://api.barivia.se";
 export const API_KEY = process.env.BARIVIA_API_KEY ?? process.env.BARSOM_API_KEY ?? "";
 export const FETCH_TIMEOUT_MS = parseInt(process.env.BARIVIA_FETCH_TIMEOUT_MS ?? "60000", 10);
-export const MAX_RETRIES = 2;
-export const RETRY_BASE_MS = parseInt(process.env.BARIVIA_RETRY_BASE_MS ?? "1000", 10);
+/** Retries after the first attempt; default 2 → 3 total tries. Override with BARIVIA_MAX_RETRIES. */
+export const MAX_RETRIES = parseInt(process.env.BARIVIA_MAX_RETRIES ?? "2", 10);
+/** Delay between burst retries (ms). Default 2000 → ~2s between each of the 3 attempts. */
+export const RETRY_BASE_MS = parseInt(process.env.BARIVIA_RETRY_BASE_MS ?? "2000", 10);
 export const RETRYABLE_STATUS = new Set([502, 503, 504]);
-/** Exponential backoff for transient API retries (attempt 0 → base, 1 → 2×, …). */
-export function retryDelayMs(attempt) {
-    return RETRY_BASE_MS * 2 ** attempt;
+/** Cool-down hint after the burst is exhausted — agents should wait before another round. */
+export const UNAVAILABLE_RETRY_AFTER_SEC = 30;
+/** Fixed delay between burst retries (not exponential). */
+export function retryDelayMs(_attempt) {
+    return RETRY_BASE_MS;
 }
 function newRequestId() {
     return randomUUID();
@@ -35,7 +39,7 @@ function newRequestId() {
  * X-Barsom-Client-Version so the server can annotate tool guidance with the
  * wrapper version each action requires. Keep in sync with package.json on bump.
  */
-export const CLIENT_VERSION = "0.22.4";
+export const CLIENT_VERSION = "0.23.2";
 /** User-facing links; keep aligned with barivia.se / api.barivia.se. */
 export const PUBLIC_SITE_ORIGIN = "https://barivia.se";
 /** Self-serve account dashboard (manage plan, billing, and API keys). */
@@ -374,52 +378,237 @@ export async function resolveFilePathForUpload(filePath, mcpServer) {
             `"C:\\\\Users\\\\you\\\\data.csv") or a file:// URI. For relative paths, set BARIVIA_WORKSPACE_ROOT in your MCP config.`);
     }
 }
-/** User-visible API error line (includes request id for support). Exported for tests. */
-export function formatApiErrorMessage(status, bodyText, requestId) {
+function looksLikeHtml(bodyText) {
+    const t = bodyText.trim().slice(0, 200).toLowerCase();
+    return t.startsWith("<!doctype") || t.startsWith("<html") || /<\s*html[\s>]/.test(t);
+}
+function isStorageErrorCode(code) {
+    if (!code)
+        return false;
+    const c = code.toLowerCase();
+    return c === "storage_upload_failed" || (c.includes("storage") && !c.includes("unavailable"));
+}
+/**
+ * Classify an HTTP API failure into a compact structured error.
+ * Gateway HTML 502/503 bodies are never echoed — they become api_unreachable.
+ */
+export function classifyApiError(status, bodyText, requestId) {
     let parsed = null;
-    try {
-        const j = JSON.parse(bodyText);
-        if (j && typeof j === "object")
-            parsed = j;
-    }
-    catch {
-        /* ignore */
+    const html = looksLikeHtml(bodyText);
+    if (!html && bodyText.trim()) {
+        try {
+            const j = JSON.parse(bodyText);
+            if (j && typeof j === "object")
+                parsed = j;
+        }
+        catch {
+            /* non-JSON */
+        }
     }
-    const detail = (parsed?.error != null && String(parsed.error)) ||
-        (bodyText.trim() ? bodyText.trim() : `HTTP ${status}`);
-    const code = parsed?.error_code != null ? ` (error_code: ${parsed.error_code})` : "";
+    const apiCode = parsed?.error_code != null ? String(parsed.error_code) : "";
+    const apiMsg = parsed?.error != null && String(parsed.error).trim()
+        ? String(parsed.error).trim()
+        : "";
+    let cause = "server";
+    let error_code = apiCode || `http_${status}`;
+    let message = apiMsg || `HTTP ${status}`;
+    let hint = "";
+    let retryable = status === 502 || status === 503 || status === 504;
     const accountHint = ` Check your email or manage your key at ${PUBLIC_DASHBOARD_URL} if needed.`;
-    const hint = status === 400
-        ? " Check parameter types and required fields."
-        : status === 401
-            ? ` Check BARIVIA_API_KEY in your MCP config.${accountHint}`
-            : status === 403
-                ? ` Access denied for this operation (plan or permissions).${accountHint}`
-                : status === 402
-                    ? ` Credits or subscription may be insufficient — upgrade at ${PUBLIC_DASHBOARD_URL}.`
-                    : status === 404
-                        ? " The resource may not exist or may have been deleted."
-                        : status === 409
-                            ? " The job may not be in the expected state."
-                            : status === 429
-                                ? " Plan limit (e.g. dataset cap) or rate limit — read the error above; delete unused datasets or wait and retry."
-                                : status === 502
-                                    ? " Object storage (R2/S3) error from API — retry later."
-                                    : status === 503
-                                        ? parsed?.error_code === "system_info_unavailable"
-                                            ? " System info (plan/queue) temporarily unavailable — retry later."
-                                            : " API or database temporarily unavailable — retry later."
-                                        : status >= 500
-                                            ? " Server error — retry later."
-                                            : "";
-    const rid = ` (request id: ${requestId} — include if contacting support)`;
-    return `${detail}${code}${hint}${rid}`;
+    if (status === 400) {
+        cause = "client";
+        hint = "Check parameter types and required fields.";
+        retryable = false;
+    }
+    else if (status === 401) {
+        cause = "auth";
+        error_code = apiCode || "unauthorized";
+        hint = `Check BARIVIA_API_KEY in your MCP config.${accountHint}`;
+        retryable = false;
+    }
+    else if (status === 403) {
+        cause = "auth";
+        error_code = apiCode || "forbidden";
+        hint = `Access denied for this operation (plan or permissions).${accountHint}`;
+        retryable = false;
+    }
+    else if (status === 402) {
+        cause = "client";
+        hint = `Credits or subscription may be insufficient — upgrade at ${PUBLIC_DASHBOARD_URL}.`;
+        retryable = false;
+    }
+    else if (status === 404) {
+        cause = "client";
+        hint = "The resource may not exist or may have been deleted.";
+        retryable = false;
+    }
+    else if (status === 409) {
+        cause = "client";
+        hint = "The job may not be in the expected state.";
+        retryable = false;
+    }
+    else if (status === 429) {
+        cause = "rate_limit";
+        hint = "Plan limit (e.g. dataset cap) or rate limit — delete unused datasets or wait and retry.";
+        retryable = true;
+    }
+    else if (status === 502 || status === 503 || status === 504) {
+        if (isStorageErrorCode(apiCode) || /object storage|r2\/s3|storage upload/i.test(apiMsg)) {
+            cause = "storage";
+            error_code = apiCode || "storage_upload_failed";
+            message = apiMsg || "Object storage (R2/S3) error from API.";
+            hint = "Retry later; feedback may still succeed via DB when storage is degraded.";
+        }
+        else if (html || !parsed) {
+            cause = "api_unreachable";
+            error_code = apiCode || "api_unreachable";
+            message = "API temporarily unavailable (gateway/tunnel returned a non-JSON error).";
+            hint =
+                `Proxy already tried 3 times (~2s apart). Wait ~${UNAVAILABLE_RETRY_AFTER_SEC}s, then retry. ` +
+                    "Use account(action=health) — /health does not depend on R2. Pause — do not paste HTML.";
+        }
+        else if (apiCode === "system_info_unavailable") {
+            cause = "server";
+            message = apiMsg || "System info (plan/queue) temporarily unavailable.";
+            hint = `Wait ~${UNAVAILABLE_RETRY_AFTER_SEC}s, then retry.`;
+        }
+        else if (apiCode === "feedback_unavailable" || apiCode === "database_error") {
+            cause = "server";
+            error_code = apiCode;
+            message = apiMsg || "API or database temporarily unavailable.";
+            hint =
+                `Wait ~${UNAVAILABLE_RETRY_AFTER_SEC}s; send_feedback queues locally if the API stays down.`;
+        }
+        else {
+            cause = "server";
+            message = apiMsg || `HTTP ${status}`;
+            hint = `API or database temporarily unavailable — wait ~${UNAVAILABLE_RETRY_AFTER_SEC}s, then retry.`;
+        }
+    }
+    else if (status >= 500) {
+        cause = "server";
+        hint = `Server error — wait ~${UNAVAILABLE_RETRY_AFTER_SEC}s, then retry.`;
+        retryable = true;
+    }
+    else if (!apiMsg && html) {
+        cause = "api_unreachable";
+        error_code = "api_unreachable";
+        message = `HTTP ${status} (non-JSON gateway body)`;
+        hint = `Wait ~${UNAVAILABLE_RETRY_AFTER_SEC}s, then retry. Do not paste HTML.`;
+        retryable = status >= 500;
+    }
+    const retry_after_sec = retryable ? UNAVAILABLE_RETRY_AFTER_SEC : undefined;
+    return {
+        status,
+        error_code,
+        message,
+        hint,
+        request_id: requestId,
+        retryable,
+        cause,
+        ...(retry_after_sec !== undefined ? { retry_after_sec } : {}),
+    };
+}
+/** User-visible API error line (slim; includes request id). Exported for tests. */
+export function formatApiErrorMessage(status, bodyText, requestId) {
+    const c = classifyApiError(status, bodyText, requestId);
+    const parts = [
+        c.message,
+        `error_code=${c.error_code}`,
+        `cause=${c.cause}`,
+        c.retry_after_sec != null ? `retry_after_sec=${c.retry_after_sec}` : "",
+        c.hint,
+        `request_id=${c.request_id}`,
+    ].filter((p) => p && String(p).trim());
+    return parts.join(" | ");
 }
 function throwApiError(status, bodyText, requestId) {
+    const classified = classifyApiError(status, bodyText, requestId);
     const err = new Error(formatApiErrorMessage(status, bodyText, requestId));
     err.httpStatus = status;
+    err.errorCode = classified.error_code;
+    err.requestId = requestId;
+    err.retryable = classified.retryable;
+    err.cause = classified.cause;
+    err.retryAfterSec = classified.retry_after_sec;
+    err.classified = classified;
     throw err;
 }
+/** Final network failure after the burst — same calm shape as gateway HTML 502. */
+function throwNetworkUnreachable(requestId, err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    const classified = {
+        status: 0,
+        error_code: "api_unreachable",
+        message: "API temporarily unavailable (network error).",
+        hint: `Proxy already tried 3 times (~2s apart). Wait ~${UNAVAILABLE_RETRY_AFTER_SEC}s, then retry. ` +
+            `Detail: ${detail.slice(0, 120)}`,
+        request_id: requestId,
+        retryable: true,
+        cause: "api_unreachable",
+        retry_after_sec: UNAVAILABLE_RETRY_AFTER_SEC,
+    };
+    const msg = [
+        classified.message,
+        `error_code=${classified.error_code}`,
+        `cause=${classified.cause}`,
+        `retry_after_sec=${classified.retry_after_sec}`,
+        classified.hint,
+        `request_id=${classified.request_id}`,
+    ].join(" | ");
+    const out = new Error(msg);
+    out.httpStatus = 0;
+    out.errorCode = classified.error_code;
+    out.requestId = requestId;
+    out.retryable = true;
+    out.cause = "api_unreachable";
+    out.retryAfterSec = UNAVAILABLE_RETRY_AFTER_SEC;
+    out.classified = classified;
+    throw out;
+}
+/**
+ * Liveness (+ optional readiness) probe against the API origin.
+ * Uses GET /health which never touches R2 — safe during storage outages.
+ */
+export async function probeApiHealth() {
+    const base = { storage: "not_probed" };
+    try {
+        const live = await fetchWithTimeout(`${API_URL}/health`, { method: "GET" }, 8_000);
+        const liveText = await live.text();
+        if (!live.ok) {
+            return { ...base, liveness: "down", readiness: "unknown", detail: `health HTTP ${live.status}` };
+        }
+        let readiness = "unknown";
+        let db;
+        let redis;
+        try {
+            const ready = await fetchWithTimeout(`${API_URL}/ready`, { method: "GET" }, 8_000);
+            const readyText = await ready.text();
+            try {
+                const j = JSON.parse(readyText);
+                readiness = ready.ok && j.status === "ready" ? "ready" : "not_ready";
+                db = j.db;
+                redis = j.redis;
+            }
+            catch {
+                readiness = ready.ok ? "ready" : "not_ready";
+            }
+        }
+        catch {
+            readiness = "unknown";
+        }
+        void liveText;
+        return { ...base, liveness: "ok", readiness, db, redis };
+    }
+    catch (err) {
+        return {
+            ...base,
+            liveness: "down",
+            readiness: "unknown",
+            detail: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
 /**
  * @param requestTimeoutMs Optional per-request timeout (default `BARIVIA_FETCH_TIMEOUT_MS`).
  */
@@ -532,9 +721,13 @@ export async function apiCall(method, path, body, extraHeaders, requestTimeoutMs
                 !err.httpStatus) {
                 throw new Error(`Request timed out after ${effectiveTimeout}ms. Increase BARIVIA_FETCH_TIMEOUT_MS in your MCP env (e.g. 120000) for slow or large requests. (request id: ${requestId})`);
             }
+            if (err instanceof TypeError)
+                throwNetworkUnreachable(requestId, err);
             throw err;
         }
     }
+    if (lastError instanceof TypeError)
+        throwNetworkUnreachable(requestId, lastError);
     throw lastError;
 }
 /** Fetch raw bytes from the API (for image downloads). */
@@ -596,9 +789,13 @@ export async function apiRawCall(path, requestTimeoutMs) {
                 !err.httpStatus) {
                 throw new Error(`Request timed out after ${effectiveTimeout}ms. Increase BARIVIA_FETCH_TIMEOUT_MS (e.g. 120000) for large images. (request id: ${requestId})`);
             }
+            if (err instanceof TypeError)
+                throwNetworkUnreachable(requestId, err);
             throw err;
         }
     }
+    if (lastError instanceof TypeError)
+        throwNetworkUnreachable(requestId, lastError);
     throw lastError;
 }
 // ---------------------------------------------------------------------------

package/dist/siom_occupation_format.js

@@ -0,0 +1,57 @@
+/**
+ * Format the SIOM occupation / coverage block for results(get) text.
+ * Surfaces effective hyperparams + util/Gini/entropy/siom_qe alongside grid
+ * dead-node counts (which come from hit_stats elsewhere).
+ */
+export function formatSiomOccupationSummary(siom, opts) {
+    if (!siom || typeof siom !== "object")
+        return [];
+    const fmt4 = (v) => v !== null && v !== undefined && v !== "" && Number.isFinite(Number(v))
+        ? Number(v).toFixed(4)
+        : "N/A";
+    const fmt3 = (v) => v !== null && v !== undefined && v !== "" && Number.isFinite(Number(v))
+        ? Number(v).toFixed(3)
+        : "N/A";
+    const fmtAny = (v) => v === null || v === undefined || v === "" ? "N/A" : String(v);
+    const hasHyper = siom.gamma !== undefined ||
+        siom.gamma_f !== undefined ||
+        siom.decay !== undefined ||
+        siom.siom_decay !== undefined ||
+        siom.penalty !== undefined ||
+        siom.siom_penalty !== undefined ||
+        siom.reset_per_epoch !== undefined;
+    const decay = siom.decay ?? siom.siom_decay;
+    const penalty = siom.penalty ?? siom.siom_penalty;
+    const files = opts?.files ?? [];
+    const hasOccFile = files.some((f) => String(f).includes("siom_occupation"));
+    if (opts?.compact) {
+        const parts = [
+            `utilization: ${fmt4(siom.utilization)}`,
+            `dead_fraction: ${fmt4(siom.dead_fraction)}`,
+            `gini: ${fmt4(siom.gini)}`,
+            `entropy: ${fmt4(siom.entropy)}`,
+            siom.siom_qe !== undefined ? `siom_qe: ${fmt4(siom.siom_qe)}` : "",
+            hasHyper
+                ? `γ=${fmt3(siom.gamma)}${siom.gamma_f !== undefined && Number(siom.gamma_f) > 0 ? `→${fmt3(siom.gamma_f)}` : ""} penalty=${fmtAny(penalty)} decay=${fmt4(decay)}`
+                : "",
+        ].filter(Boolean);
+        return [`SIOM occupation summary — ${parts.join(" | ")}`];
+    }
+    const lines = [
+        "SIOM occupation summary (layer coverage; distinct from grid BMU dead nodes):",
+        `  Utilization: ${fmt4(siom.utilization)} | dead_fraction: ${fmt4(siom.dead_fraction)}`,
+        `  Gini: ${fmt4(siom.gini)} | Entropy: ${fmt4(siom.entropy)}${siom.max_entropy !== undefined ? ` / max ${fmt4(siom.max_entropy)}` : ""}`,
+        siom.siom_qe !== undefined ? `  SIOM QE: ${fmt4(siom.siom_qe)}` : "",
+    ];
+    if (hasHyper) {
+        lines.push(`  Knobs: gamma=${fmt3(siom.gamma)}` +
+            (siom.gamma_f !== undefined ? ` gamma_f=${fmt3(siom.gamma_f)}` : "") +
+            ` siom_decay=${fmt4(decay)} siom_penalty=${fmtAny(penalty)}` +
+            (siom.penalty_alpha !== undefined ? ` α=${fmt3(siom.penalty_alpha)}` : "") +
+            (siom.reset_per_epoch !== undefined ? ` reset_per_epoch=${fmtAny(siom.reset_per_epoch)}` : ""));
+    }
+    if (hasOccFile) {
+        lines.push("  Artifact: siom_occupation.json (per-node μ) — results(action=download, include_json=true).");
+    }
+    return lines.filter((l) => l !== "");
+}

package/dist/tools/account.js

@@ -1,27 +1,95 @@
 import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
-import { apiCall, CLIENT_VERSION } from "../shared.js";
+import { apiCall, CLIENT_VERSION, probeApiHealth, structuredTextResult, UNAVAILABLE_RETRY_AFTER_SEC, } from "../shared.js";
 import { getMcpClientDiagnostics } from "../ui-delivery.js";
+import { listDeferredFeedback } from "../deferred_feedback.js";
+import { buildJobsListQuery, extractJobsList, formatDatasetInventoryLine, formatJobInventoryLine, } from "../inventory_format.js";
+function degradedStatusResult(opts) {
+    const retry_after_sec = UNAVAILABLE_RETRY_AFTER_SEC;
+    const payload = {
+        ok: false,
+        retry_after_sec,
+        api_reachable: false,
+        message: "Barivia is temporarily unavailable (we could not reach the API). " +
+            "Your local files and prior downloads are still fine. Try again in about 30 seconds.",
+        offline_ok: [
+            "already-downloaded results",
+            "local CSVs",
+            "draft notes / deferred feedback queue",
+        ],
+        needs_api: ["upload", "train", "feedback flush", "list/status", "other cloud tools"],
+        request_id: opts.requestId ?? null,
+        hint_for_host: "Barivia: reconnecting…",
+        detail: opts.detail ?? null,
+    };
+    const rid = opts.requestId
+        ? ` (request id: ${opts.requestId} — include if contacting support)`
+        : "";
+    const text = [
+        payload.message + rid,
+        `retry_after_sec=${retry_after_sec} | api_reachable=false`,
+        `AGENT: Calm banner ("${payload.hint_for_host}"); do not dump HTML. Proxy already burst-retried; wait ~${retry_after_sec}s before another round. Do not start large uploads/trains until ok.`,
+    ].join("\n");
+    return structuredTextResult(payload, text);
+}
 export function registerAccountTool(server) {
-    registerAuditedTool(server, "account", `Manage your Barivia account — check plan/license info, view usage history, add funds.
+    registerAuditedTool(server, "account", `Manage your Barivia account — check plan/license info, view usage history, rebuild an org inventory, add funds, or probe API health.
 
 | Action | Use when |
 |--------|----------|
-| status | Before large jobs — see plan tier, GPU availability, queue depth, training time estimates, credit balance |
+| status | Before large jobs — see plan tier, GPU availability, queue depth, training time estimates, credit balance. When the API is down, returns calm \`{ok:false, retry_after_sec}\` instead of HTML. |
 | history | Viewing recent compute usage and credit spend |
+| inventory | Rebuild a durable markdown overview of datasets + recent jobs (agent-friendly org catalog) |
 | add_funds | Getting instructions to add credits |
+| health | Diagnose API reachability during outages — GET /health + /ready; does **not** probe R2/object storage |
 
 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.
+  When the API/gateway is down, returns structured \`{ok:false, retry_after_sec, …}\` — treat as a pause, not a crash.
+action=inventory: Lists datasets (name/id/rows/cols/description/tags) and slim recent jobs (label/id/status/job_type/dataset_id/created_at/result). Prefer this over hand-assembling datasets(list)+jobs(list). Page jobs with jobs(action=list, cursor=…).
+action=health: Lightweight liveness/readiness (no R2). Use when tools return api_unreachable or before retrying deferred send_feedback.
 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", "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)"),
+            .enum(["status", "history", "inventory", "add_funds", "health"])
+            .describe("status: plan/license/queue info; history: recent compute usage; inventory: datasets+jobs overview; add_funds: instructions; health: API liveness without R2"),
+        limit: z.number().optional().describe("action=history or inventory: number of job records to return (default: 10 history / 50 inventory)"),
     }, async ({ action, limit }) => {
+        if (action === "health") {
+            const health = await probeApiHealth();
+            const deferred = await listDeferredFeedback("barsom").catch(() => []);
+            const lines = [
+                `API liveness: ${health.liveness}`,
+                `API readiness: ${health.readiness}`,
+                health.db ? `DB: ${health.db}` : null,
+                health.redis ? `Redis: ${health.redis}` : null,
+                `Object storage (R2): ${health.storage} (intentionally not checked)`,
+                health.detail ? `Detail: ${health.detail}` : null,
+                `Deferred feedback drafts (barsom): ${deferred.length}`,
+                health.liveness === "down"
+                    ? `retry_after_sec=${UNAVAILABLE_RETRY_AFTER_SEC} (wait before another tool round)`
+                    : null,
+            ].filter(Boolean);
+            return structuredTextResult({
+                ...health,
+                deferred_feedback_pending: deferred.length,
+                ...(health.liveness === "down"
+                    ? { ok: false, retry_after_sec: UNAVAILABLE_RETRY_AFTER_SEC }
+                    : { ok: true }),
+            }, lines.join("\n"));
+        }
         if (action === "status") {
-            const data = (await apiCall("GET", "/v1/system/info"));
+            let data;
+            try {
+                data = (await apiCall("GET", "/v1/system/info"));
+            }
+            catch (err) {
+                const e = err;
+                return degradedStatusResult({
+                    requestId: e.requestId,
+                    detail: e.message,
+                });
+            }
             const plan = data.plan ?? {};
             const backend = data.backend ?? {};
             const status = data.status ?? {};
@@ -95,6 +163,42 @@ NOT FOR: Training itself — use train(action=map). This tool only manages the a
                 content: [{ type: "text", text: `Credit Balance: $${(data.credit_balance_cents / 100).toFixed(2)}\n\nRecent Usage:\n${history}` }]
             };
         }
+        if (action === "inventory") {
+            const jobLimit = limit && limit > 0 ? Math.min(Math.floor(limit), 100) : 50;
+            const [datasetsRaw, jobsRaw] = await Promise.all([
+                apiCall("GET", "/v1/datasets"),
+                apiCall("GET", buildJobsListQuery({ limit: jobLimit })),
+            ]);
+            const datasets = Array.isArray(datasetsRaw) ? datasetsRaw : [];
+            const { jobs, next_cursor } = extractJobsList(jobsRaw);
+            const lines = [
+                `# Org inventory`,
+                ``,
+                `## Datasets (${datasets.length})`,
+            ];
+            if (datasets.length === 0) {
+                lines.push("(none)");
+            }
+            else {
+                for (const ds of datasets)
+                    lines.push(`- ${formatDatasetInventoryLine(ds)}`);
+            }
+            lines.push(``, `## Jobs (latest ${jobs.length}${next_cursor ? ", more available" : ""})`);
+            if (jobs.length === 0) {
+                lines.push("(none)");
+            }
+            else {
+                for (const job of jobs)
+                    lines.push(`- ${formatJobInventoryLine(job)}`);
+            }
+            if (next_cursor) {
+                lines.push(``);
+                lines.push(`More jobs: jobs(action=list, cursor="${next_cursor}", limit=${jobLimit})`);
+            }
+            lines.push(``);
+            lines.push(`Tips: set description/tags on datasets(upload|update) and train(...)/jobs(update). Filter jobs with status/job_type/has_results.`);
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
         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:
@@ -102,7 +206,7 @@ bash scripts/billing/manage-credits.sh add <org_id> <amount_usd>` }]
             };
         }
         return {
-            content: [{ type: "text", text: `Unknown action: ${action}. Valid: status, history, add_funds.` }]
+            content: [{ type: "text", text: `Unknown action: ${action}. Valid: status, history, inventory, add_funds, health.` }]
         };
     });
 }