@runpod/mcp-server 3.0.0 → 3.2.0

package/dist/tools.cjs

@@ -38,11 +38,150 @@ module.exports = __toCommonJS(tools_exports);
 var import_node_fetch = __toESM(require("node-fetch"), 1);
 var import_node_crypto = require("crypto");
 
+// src/_shared/rate-limit.ts
+var GENERIC_RATE_LIMIT_HINT = "rate limited \u2014 back off before retrying, and pace bulk operations";
+var MAX_PLAUSIBLE_WAIT_S = 7 * 86400;
+function remainingRequests(raw) {
+  const value = raw?.trim();
+  return value && /^\d+$/.test(value) ? Number(value) : null;
+}
+function waitSeconds(raw) {
+  const value = raw?.trim();
+  if (!value || !/^\d+$/.test(value)) return null;
+  const seconds = Number(value);
+  return seconds <= MAX_PLAUSIBLE_WAIT_S ? seconds : null;
+}
+var WINDOW_NAME_RE = /^(?:"([\x20-\x21\x23-\x5b\x5d-\x7e]{1,32})"|([A-Za-z*][A-Za-z0-9!#$%&'*+.^_`|~:/-]{0,31}))$/;
+function windowName(raw) {
+  const match = WINDOW_NAME_RE.exec(raw.trim());
+  return match ? match[1] ?? match[2] : null;
+}
+var QUOTED_VALUE_RE = /^"(?:[\x20-\x21\x23-\x5b\x5d-\x7e]|\\["\\])*"$/;
+var DISPLAY_VALUE_RE = /^%"(?:[\x20-\x21\x23-\x24\x26-\x5b\x5d-\x7e]|\\|%[0-9a-f]{2})*"$/;
+function isWellFormedParam(param) {
+  const eq = param.indexOf("=");
+  const key = (eq === -1 ? param : param.slice(0, eq)).trim();
+  if (key.includes('"')) return false;
+  if (eq === -1) return true;
+  const value = param.slice(eq + 1).trim();
+  if (value.startsWith('"')) return QUOTED_VALUE_RE.test(value);
+  if (value.startsWith('%"')) return DISPLAY_VALUE_RE.test(value);
+  return !/[\s"]/.test(value);
+}
+function splitOutsideStrings(input, sep) {
+  const parts = [];
+  let current = "";
+  let inString = false;
+  let inDisplay = false;
+  let escaped = false;
+  let prev = "";
+  for (const ch of input) {
+    if (escaped) escaped = false;
+    else if (inString && !inDisplay && ch === "\\") escaped = true;
+    else if (ch === '"') {
+      if (!inString) inDisplay = prev === "%";
+      inString = !inString;
+    } else if (ch === sep && !inString) {
+      parts.push(current);
+      current = "";
+      prev = ch;
+      continue;
+    }
+    current += ch;
+    prev = ch;
+  }
+  parts.push(current);
+  return parts;
+}
+function readParams(params) {
+  const values = /* @__PURE__ */ new Map();
+  let unreadable = false;
+  let valuelessAt = -1;
+  for (const [index, param] of params.entries()) {
+    const eq = param.indexOf("=");
+    const key = (eq === -1 ? param : param.slice(0, eq)).trim().toLowerCase();
+    if (!key) continue;
+    if (eq === -1) {
+      if (key === "r") unreadable = true;
+      if (key === "t") values.delete("t");
+      valuelessAt = index;
+      continue;
+    }
+    if ((key === "r" || key === "t") && (values.has(key) || valuelessAt !== -1 && index > valuelessAt)) {
+      unreadable = true;
+    }
+    values.set(key, param.slice(eq + 1));
+  }
+  return { values, unreadable };
+}
+function parseExhaustedWindows(header) {
+  if (!header) return { windows: [], dropped: false };
+  const windows = [];
+  let dropped = false;
+  for (const item of splitOutsideStrings(header, ",")) {
+    if (item.trim() === "") continue;
+    const [rawName, ...params] = splitOutsideStrings(item, ";");
+    if (!params.every(isWellFormedParam)) {
+      dropped = true;
+      continue;
+    }
+    const { values, unreadable } = readParams(params);
+    if (unreadable) {
+      dropped = true;
+      continue;
+    }
+    const remaining = remainingRequests(values.get("r"));
+    if (remaining === null) {
+      dropped = true;
+      continue;
+    }
+    if (remaining !== 0) continue;
+    windows.push({
+      window: windowName(rawName),
+      resetS: waitSeconds(values.get("t"))
+    });
+  }
+  return { windows, dropped };
+}
+function humanWait(seconds) {
+  if (seconds < 120) return `~${seconds}s`;
+  if (seconds < 3600)
+    return `~${Math.ceil(seconds / 60)} minutes (${seconds}s)`;
+  if (seconds < 2 * 86400) {
+    const hours = Math.ceil(seconds / 3600);
+    return `~${hours} hour${hours === 1 ? "" : "s"} (${seconds}s)`;
+  }
+  return `~${Math.ceil(seconds / 86400)} days (${seconds}s)`;
+}
+function rateLimitHint(rateLimitHeader, retryAfterHeader) {
+  const { windows, dropped } = parseExhaustedWindows(rateLimitHeader);
+  windows.sort((a, b) => (b.resetS ?? -1) - (a.resetS ?? -1));
+  const longestWindow = windows[0];
+  const waitCandidates = [
+    waitSeconds(retryAfterHeader),
+    longestWindow?.resetS
+  ].filter((n) => typeof n === "number" && n > 0);
+  const waitS = waitCandidates.length ? Math.max(...waitCandidates) : null;
+  const retryAfterUnreadable = typeof retryAfterHeader === "string" && retryAfterHeader.trim() !== "" && waitSeconds(retryAfterHeader) === null;
+  if (!longestWindow && waitS === null) {
+    if (!retryAfterUnreadable) return GENERIC_RATE_LIMIT_HINT;
+  }
+  const namedClause = longestWindow?.window ? `the ${longestWindow.window} quota is exhausted` : "";
+  if (waitS === null) {
+    const cause = namedClause ? `${namedClause}, but the response gave no usable reset time` : "the response gave no usable reset time";
+    return `rate limited \u2014 ${cause}; back off substantially before retrying, and pace bulk operations`;
+  }
+  const hedge = dropped || retryAfterUnreadable || windows.some((w) => w.resetS === null) ? "at least " : "";
+  const wait = `wait ${hedge}${humanWait(waitS)} before retrying, and pace bulk operations`;
+  return `rate limited \u2014 ${namedClause ? `${namedClause}; ` : ""}${wait}`;
+}
+
 // src/_shared/http.ts
+var EXPIRED_CREDENTIAL_HINT = "the Runpod API rejected the credential \u2014 the API key may be expired or revoked; re-authenticate or update RUNPOD_API_KEY";
 var HttpError = class extends Error {
-  constructor(prefix, status, body) {
-    const hint = status === 401 ? " (the Runpod API rejected the credential \u2014 the API key may be expired or revoked; re-authenticate or update RUNPOD_API_KEY)" : "";
-    super(`${prefix}: ${status} - ${body}${hint}`);
+  constructor(prefix, status, body, hint) {
+    const shownBody = body.length > 2048 ? `${body.slice(0, 2048)}\u2026 [truncated ${body.length - 2048} chars]` : body;
+    super(`${prefix}: ${status} - ${shownBody}${hint ? ` (${hint})` : ""}`);
     this.name = "HttpError";
     this.status = status;
     this.body = body;
@@ -77,7 +216,11 @@ function createHttpClient(deps) {
       throw new HttpError(
         deps.errorPrefix,
         response.status,
-        await response.text()
+        await response.text(),
+        response.status === 429 ? rateLimitHint(
+          response.headers.get("ratelimit"),
+          response.headers.get("retry-after")
+        ) : response.status === 401 ? EXPIRED_CREDENTIAL_HINT : void 0
       );
     }
     return isJsonContentType(response.headers.get("content-type")) ? response.json() : { success: true, status: response.status };
@@ -136,7 +279,15 @@ async function readSseSnapshot(fetchImpl, url, headers, opts) {
       throw new HttpError(
         "Runpod API Error",
         res.status,
-        await res.text().catch(() => "")
+        await res.text().catch(() => ""),
+        // This throw bypasses createHttpClient, so the status hints are built
+        // here too or these two tools alone return a bare 429/401. The 401
+        // hint applies: this request always carries Authorization (see the
+        // headers bound in runtime.ts streamSse).
+        res.status === 429 ? rateLimitHint(
+          res.headers.get("ratelimit"),
+          res.headers.get("retry-after")
+        ) : res.status === 401 ? EXPIRED_CREDENTIAL_HINT : void 0
       );
     }
     for await (const chunk of res.body ?? []) {
@@ -255,15 +406,27 @@ function mapPodUpdateToV2(params) {
     ...compact({ name: params.name })
   };
 }
-function nestedOrUndefined(obj) {
-  const c = compact(obj);
-  return Object.keys(c).length ? c : void 0;
+var DEFAULT_ENDPOINT_TYPE = "QUEUE";
+var DEFAULT_SCALER_VALUE = 4;
+function defaultScalerType(endpointType) {
+  return endpointType === "LOAD_BALANCER" ? "REQUEST_COUNT" : "QUEUE_DELAY";
+}
+function endpointScaling(scalerType, value) {
+  return scalerType === "REQUEST_COUNT" ? { type: "REQUEST_COUNT", requestCount: value } : { type: "QUEUE_DELAY", queueDelay: value };
 }
 function endpointGpuConfig(pools, count) {
   if (!pools?.length) return void 0;
   return compact({ pools, count });
 }
-function mapEndpointToV2(params) {
+function endpointWorkers(params) {
+  const workers = compact({
+    min: params.workersMin,
+    max: params.workersMax,
+    idleTimeout: params.idleTimeout
+  });
+  return Object.keys(workers).length ? workers : void 0;
+}
+function endpointCommonToV2(params) {
   return compact({
     name: params.name,
     image: params.imageName,
@@ -273,23 +436,33 @@ function mapEndpointToV2(params) {
     env: params.env,
     registry: params.containerRegistryAuthId,
     gpu: endpointGpuConfig(params.gpuPoolIds, params.gpuCount),
-    workers: nestedOrUndefined({
-      min: params.workersMin,
-      max: params.workersMax
-    }),
-    scaling: nestedOrUndefined({
-      type: params.scalerType,
-      value: params.scalerValue,
-      idleTimeout: params.idleTimeout
-    }),
+    workers: endpointWorkers(params),
     dataCenterIds: params.dataCenterIds?.length ? params.dataCenterIds : void 0,
     networkVolumes: params.networkVolumeIds?.length ? params.networkVolumeIds : void 0,
     timeout: params.executionTimeoutMs,
     flashboot: params.flashboot
   });
 }
-var mapEndpointCreateToV2 = mapEndpointToV2;
-var mapEndpointUpdateToV2 = mapEndpointToV2;
+function mapEndpointCreateToV2(params) {
+  const endpointType = params.endpointType ?? DEFAULT_ENDPOINT_TYPE;
+  return compact({
+    ...endpointCommonToV2(params),
+    type: endpointType,
+    scaling: endpointScaling(
+      params.scalerType ?? defaultScalerType(endpointType),
+      params.scalerValue ?? DEFAULT_SCALER_VALUE
+    )
+  });
+}
+function mapEndpointUpdateToV2(params) {
+  return compact({
+    ...endpointCommonToV2(params),
+    scaling: params.scalerType ? endpointScaling(
+      params.scalerType,
+      params.scalerValue ?? DEFAULT_SCALER_VALUE
+    ) : void 0
+  });
+}
 function mapNetworkVolumeCreateToV2(params) {
   return compact({
     name: params.name,
@@ -373,7 +546,7 @@ function restV1Base(env) {
   return env.RUNPOD_REST_API_URL ?? "https://rest.runpod.io/v1";
 }
 function restV2Base(env) {
-  return env.RUNPOD_REST_V2_API_URL ?? "https://v2-rest.runpod.io/v2";
+  return env.RUNPOD_REST_V2_API_URL ?? "https://api.runpod.io/v2";
 }
 function serverlessBase(env) {
   return env.RUNPOD_SERVERLESS_API_URL ?? "https://api.runpod.ai/v2";
@@ -536,7 +709,7 @@ function resolveBackend(opts) {
 }
 
 // src/tools/runtime.ts
-var MCP_SERVER_VERSION = true ? "3.0.0" : "dev";
+var MCP_SERVER_VERSION = true ? "3.2.0" : "dev";
 var SESSION_ID = (0, import_node_crypto.randomUUID)();
 function trackingHeaders(server, ctx) {
   const info = server.server.getClientVersion();
@@ -586,6 +759,36 @@ async function graphqlRequest(query, tracking, fetchImpl, url, options) {
       ...options?.variables ? { variables: options.variables } : {}
     })
   });
+  if (!response.ok) {
+    const bodyText = await response.text();
+    let gqlErrors;
+    try {
+      gqlErrors = JSON.parse(bodyText).errors;
+    } catch {
+    }
+    if (Array.isArray(gqlErrors) && gqlErrors.length > 0 && response.status !== 401 && response.status !== 429) {
+      throw new HttpError(
+        "Runpod GraphQL Error",
+        response.status,
+        gqlErrors.map((e) => String(e?.message ?? JSON.stringify(e))).join(", ")
+      );
+    }
+    throw new HttpError(
+      "Runpod GraphQL Error",
+      response.status,
+      bodyText,
+      response.status === 429 ? rateLimitHint(
+        response.headers.get("ratelimit"),
+        response.headers.get("retry-after")
+      ) : (
+        // Only when this request actually carried the caller's API key: the
+        // public path sends no Authorization header, so a 401 from that
+        // host (WAF, misconfigured RUNPOD_PUBLIC_GRAPHQL_URL) says nothing
+        // about the credential — same rationale as observeUnauthorized.
+        response.status === 401 && options?.apiKey ? EXPIRED_CREDENTIAL_HINT : void 0
+      )
+    );
+  }
   const result = await response.json();
   if (result.errors && result.errors.length > 0) {
     throw new Error(
@@ -1002,6 +1205,178 @@ function registerCatalogTools(server, rt) {
       return jsonReply2(result);
     }
   );
+  server.tool(
+    "get-capacity",
+    "GPU capacity across host CUDA versions, as a matrix. Use this to choose an endpoint's allowedCudaVersions/minCudaVersion (or diagnose/widen a capacity-starved one) and to distinguish capacity problems from compatibility problems. Default mode is one call returning, per GPU type, overall stock plus AVAILABLE/UNAVAILABLE per host-reported CUDA version. Pass cudaVersions to deep-probe instead: one stock lookup per listed version, returning graded stock (High/Medium/Low/Out) and the lowest on-demand price per version; a probe that fails transiently reports a per-version error instead of failing the call. Nothing is hidden by default \u2014 set includeUnavailable:false to drop GPUs with no stock on any listed version. Credential-free public catalog data; works on both v1 and v2 APIs. Stock is live, so page cursors can shift between calls. Note: the matrix reflects host-reported versions, but endpoint allowedCudaVersions only accepts values from the platform enum \u2014 check create-endpoint/update-endpoint for the accepted list.",
+    {
+      ...listPaginationParams,
+      cudaVersions: import_zod3.z.array(import_zod3.z.string().regex(/^\d{1,2}\.\d{1,2}$/)).min(1).max(12).optional().describe(
+        'Deep-probe these host CUDA versions (e.g. ["12.8", "13.0"], max 12): one stock lookup per version returns graded stock and price. Omit for the single-call AVAILABLE/UNAVAILABLE matrix across all versions the fleet currently reports.'
+      ),
+      includeUnavailable: import_zod3.z.boolean().optional().describe(
+        'Out-of-stock GPUs are included by default (explicit "Out" cells / all-UNAVAILABLE rows, sorted last). Set false to hide GPUs with no stock on any listed version.'
+      ),
+      gpuTypeIds: import_zod3.z.array(import_zod3.z.string()).optional().describe(
+        "Filter to GPU types matching any of these ids or display names (case-insensitive substring, e.g. ['NVIDIA GeForce RTX 4090'] or ['4090', 'H200'])."
+      ),
+      gpuCount: import_zod3.z.number().int().min(1).max(8).optional().describe("GPUs per worker/pod to check stock for (default 1)."),
+      secureCloudOnly: import_zod3.z.boolean().optional().describe("Restrict the stock lookup to Secure Cloud hosts.")
+    },
+    { title: "Get GPU capacity by CUDA version", ...READ_ONLY },
+    async (params) => {
+      const gpuCount = Math.min(
+        8,
+        Math.max(1, Math.floor(Number(params.gpuCount)) || 1)
+      );
+      const secureArg = params.secureCloudOnly ? ", secureCloud: true" : "";
+      const filterTerms = (params.gpuTypeIds ?? []).filter((t) => typeof t === "string" && t.trim().length > 0).map((t) => t.toLowerCase());
+      const matchesFilter = (gpu) => {
+        if (filterTerms.length === 0) return true;
+        const id = gpu.id.toLowerCase();
+        const name = gpu.displayName.toLowerCase();
+        return filterTerms.some(
+          (term) => id.includes(term) || name.includes(term)
+        );
+      };
+      const stockPriority = {
+        High: 3,
+        Medium: 2,
+        Low: 1
+      };
+      if (!params.cudaVersions?.length) {
+        const data = await graphql(`
+          query {
+            gpuTypes {
+              id
+              displayName
+              memoryInGb
+              secureCloud
+              communityCloud
+              lowestPrice(input: { gpuCount: ${gpuCount}${secureArg} }) {
+                stockStatus
+                uninterruptablePrice
+                gpuTypeCudaVersions {
+                  cudaVersion
+                  availability
+                }
+              }
+            }
+          }
+        `);
+        let rows2 = data.gpuTypes.filter((gpu) => gpu.id !== "unknown" && matchesFilter(gpu)).map((gpu) => {
+          const cuda = {};
+          for (const c of gpu.lowestPrice?.gpuTypeCudaVersions ?? []) {
+            cuda[c.cudaVersion] = c.availability;
+          }
+          return {
+            id: gpu.id,
+            displayName: gpu.displayName,
+            memoryGb: gpu.memoryInGb,
+            secureCloud: gpu.secureCloud,
+            communityCloud: gpu.communityCloud,
+            stockStatus: gpu.lowestPrice?.stockStatus || "unavailable",
+            pricePerHr: gpu.lowestPrice?.uninterruptablePrice ?? null,
+            cudaVersions: cuda
+          };
+        });
+        const availableCount = (r) => Object.values(r.cudaVersions).filter((a) => a === "AVAILABLE").length;
+        if (params.includeUnavailable === false)
+          rows2 = rows2.filter((r) => availableCount(r) > 0);
+        rows2.sort((a, b) => {
+          const diff = availableCount(b) - availableCount(a);
+          if (diff !== 0) return diff;
+          const stockDiff = (stockPriority[b.stockStatus] || 0) - (stockPriority[a.stockStatus] || 0);
+          if (stockDiff !== 0) return stockDiff;
+          return b.memoryGb - a.memoryGb;
+        });
+        return capListResult(rows2, {
+          limit: params.limit,
+          cursor: params.cursor
+        });
+      }
+      const versions = [...new Set(params.cudaVersions)].slice(0, 12);
+      const invalid = versions.filter((v) => !/^\d{1,2}\.\d{1,2}$/.test(v));
+      if (invalid.length > 0) {
+        return jsonReply2({
+          error: `Invalid CUDA version format: ${invalid.join(", ")}. Use "major.minor" strings like "12.8".`,
+          status: 400
+        });
+      }
+      const perVersion = await Promise.allSettled(
+        versions.map(
+          (v) => graphql(`
+            query {
+              gpuTypes {
+                id
+                displayName
+                memoryInGb
+                secureCloud
+                communityCloud
+                lowestPrice(input: { gpuCount: ${gpuCount}, allowedCudaVersions: ["${v}"]${secureArg} }) {
+                  stockStatus
+                  uninterruptablePrice
+                }
+              }
+            }
+          `)
+        )
+      );
+      const probeErrors = {};
+      const byId = /* @__PURE__ */ new Map();
+      versions.forEach((v, i) => {
+        const settled = perVersion[i];
+        if (settled.status === "rejected") {
+          probeErrors[v] = settled.reason instanceof Error ? settled.reason.message : String(settled.reason);
+          return;
+        }
+        for (const gpu of settled.value.gpuTypes) {
+          if (gpu.id === "unknown" || !matchesFilter(gpu)) continue;
+          let row = byId.get(gpu.id);
+          if (!row) {
+            row = {
+              id: gpu.id,
+              displayName: gpu.displayName,
+              memoryGb: gpu.memoryInGb,
+              secureCloud: gpu.secureCloud,
+              communityCloud: gpu.communityCloud,
+              cudaVersions: {}
+            };
+            byId.set(gpu.id, row);
+          }
+          const stock = gpu.lowestPrice?.stockStatus;
+          row.cudaVersions[v] = !stock || stock === "Out" ? { stock: "Out", pricePerHr: null } : {
+            stock,
+            pricePerHr: gpu.lowestPrice?.uninterruptablePrice ?? null
+          };
+        }
+      });
+      let rows = [...byId.values()];
+      const inStockCount = (r) => Object.values(r.cudaVersions).filter((c) => c.stock !== "Out").length;
+      if (params.includeUnavailable === false)
+        rows = rows.filter((r) => inStockCount(r) > 0);
+      rows.sort((a, b) => {
+        const diff = inStockCount(b) - inStockCount(a);
+        if (diff !== 0) return diff;
+        const best = (r) => Math.max(
+          0,
+          ...Object.values(r.cudaVersions).map(
+            (c) => stockPriority[c.stock] || 0
+          )
+        );
+        const bestDiff = best(b) - best(a);
+        if (bestDiff !== 0) return bestDiff;
+        return b.memoryGb - a.memoryGb;
+      });
+      return capListResult(
+        rows,
+        { limit: params.limit, cursor: params.cursor },
+        {
+          probedCudaVersions: versions,
+          ...Object.keys(probeErrors).length > 0 ? { probeErrors } : {}
+        }
+      );
+    }
+  );
   server.tool(
     "get-data-center",
     "Get details for a single data center by id. v2-only \u2014 returns a 501 notice on the v1 API (use list-data-centers there).",
@@ -1686,7 +2061,9 @@ function registerPodTools(server, rt) {
     "create-pod",
     'Create a new GPU/CPU pod on Runpod. Pass gpuTypeIds for a GPU pod, or computeType:"CPU" for a CPU pod (CPU pods are served by the v1 API for now). Pass either imageName or templateId (templateId deploys from an existing template \u2014 its name, image, start command, ports, env, disk, volume, and registry credential are used as defaults, and any field you also pass explicitly replaces the template value for that field, e.g. passing env replaces the whole env set rather than merging; pass containerRegistryAuthId to override or supply a private-image credential, or an empty string to deploy with none). If the user specifies neither an image nor a template, recommend the "Runpod Pytorch 2.8.0" image (runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404) as the default \u2014 it has the most up-to-date CUDA and PyTorch versions.',
     {
-      name: import_zod7.z.string().optional().describe("Name for the pod"),
+      name: import_zod7.z.string().optional().describe(
+        "Name for the pod. Required on v2 unless deploying from a templateId (the template supplies its name as the default)."
+      ),
       imageName: import_zod7.z.string().optional().describe("Docker image to use. Optional when templateId is provided."),
       templateId: import_zod7.z.string().optional().describe(
         "Deploy from an existing template (see list-templates / get-template). The template supplies name, image, start command, ports, env, disk, volume, and registry credential as defaults; any field you also pass replaces the template value for that field (whole-field, not a merge). Override the registry credential with containerRegistryAuthId. Requires the v2 REST API. Still pass gpuTypeIds or computeType to choose the compute \u2014 a template does not pin the pod compute."
@@ -1745,6 +2122,12 @@ function registerPodTools(server, rt) {
             status: 400
           });
         }
+        if (!wantsCpu && !params.name && !params.templateId) {
+          return jsonReply2({
+            error: "Provide a name for the pod (deploying from a templateId inherits the template name).",
+            status: 400
+          });
+        }
         if (wantsCpu) {
           if (params.templateId) {
             return jsonReply2({
@@ -1922,11 +2305,22 @@ function registerPodTools(server, rt) {
 
 // src/tools/endpoints.ts
 var import_zod8 = require("zod");
+var MIN_QUEUE_DELAY = 0.5;
+var MIN_REQUEST_COUNT = 1;
+var MIN_IDLE_TIMEOUT = 1;
+var MAX_IDLE_TIMEOUT = 3600;
+function scalerValueError(scalerType, scalerValue) {
+  if (scalerType !== "REQUEST_COUNT" || scalerValue === void 0) return;
+  if (!Number.isInteger(scalerValue) || scalerValue < MIN_REQUEST_COUNT) {
+    return `REQUEST_COUNT scales on whole in-flight requests per worker, so scalerValue must be an integer >= ${MIN_REQUEST_COUNT} (got ${scalerValue}). For a fractional target use scalerType QUEUE_DELAY, which takes seconds >= ${MIN_QUEUE_DELAY}.`;
+  }
+  return;
+}
 function registerEndpointTools(server, rt) {
   const { jsonReply: jsonReply2, callRestUrl, backendFor } = rt;
   server.tool(
     "list-endpoints",
-    "List your Serverless endpoints, optionally expanding template and worker details (v1 only). Paginated via limit/cursor.",
+    "List your Serverless endpoints, optionally expanding template and worker details (v1 only). Paginated via limit/cursor. On v2 each endpoint carries its request routing in `type` and the URLs to call it in `requestUrls`.",
     {
       ...listPaginationParams,
       includeTemplate: import_zod8.z.boolean().optional().describe("Include template information (v1 only)"),
@@ -1961,7 +2355,7 @@ function registerEndpointTools(server, rt) {
   );
   server.tool(
     "get-endpoint",
-    "Get one Serverless endpoint by id, optionally expanding template and worker details (v1 only).",
+    "Get one Serverless endpoint by id, optionally expanding template and worker details (v1 only). On v2 the reply carries `type` (queue-based vs load-balancing routing) and `requestUrls` \u2014 the run/runsync/status/... URLs for a queue endpoint, or the base + health URLs for a load-balancing one. Read those rather than constructing endpoint URLs by hand.",
     {
       endpointId: import_zod8.z.string().describe("ID of the endpoint to retrieve"),
       includeTemplate: import_zod8.z.boolean().optional().describe("Include template information (v1 only)"),
@@ -1993,11 +2387,14 @@ function registerEndpointTools(server, rt) {
   );
   server.tool(
     "create-endpoint",
-    "Create a Serverless endpoint. On v2 (default), pass an inline config: imageName + gpuPoolIds (GPU pool names from list-gpu-types \u2014 the `pool` field, e.g. AMPERE_80/ADA_24) plus optional workers/scaling/disk/env. On v1, pass a templateId instead. Worker min/max set autoscaling bounds (min 0 = scale to zero).",
+    "Create a Serverless endpoint. On v2 (default), pass an inline config: imageName + gpuPoolIds (GPU pool names from list-gpu-types \u2014 the `pool` field, e.g. AMPERE_80/ADA_24) plus optional workers/scaling/disk/env. On v1, pass a templateId instead. Worker min/max set autoscaling bounds (min 0 = scale to zero). Use endpointType to pick queue-based (default) or load-balancing request routing; the response `requestUrls` carries the URLs to call the endpoint with.",
     {
       name: import_zod8.z.string().optional().describe("Name for the endpoint"),
       // --- v2 inline-config fields ---
       imageName: import_zod8.z.string().optional().describe("Docker image (v2). Required on v2 instead of a templateId."),
+      endpointType: import_zod8.z.enum(["QUEUE", "LOAD_BALANCER"]).optional().describe(
+        "How requests reach the workers (v2). QUEUE (default) = submit jobs through the managed queue (run/runsync/status/...). LOAD_BALANCER = send HTTP requests straight to worker-defined paths, and forces scalerType REQUEST_COUNT. Fixed at creation \u2014 update-endpoint cannot change it."
+      ),
       gpuPoolIds: import_zod8.z.array(import_zod8.z.string()).optional().describe(
         'GPU pool names (v2, required). The `pool` field from list-gpu-types, e.g. ["AMPERE_80"]. NOT GPU type ids.'
       ),
@@ -2017,9 +2414,15 @@ function registerEndpointTools(server, rt) {
       // --- shared autoscaling fields ---
       workersMin: import_zod8.z.number().optional().describe("Minimum number of workers"),
       workersMax: import_zod8.z.number().optional().describe("Maximum number of workers"),
-      scalerType: import_zod8.z.enum(["QUEUE_DELAY", "REQUEST_COUNT"]).optional().describe("Autoscaler type"),
-      scalerValue: import_zod8.z.number().optional().describe("Autoscaler target value"),
-      idleTimeout: import_zod8.z.number().optional().describe("Idle timeout in seconds before scaling a worker down"),
+      scalerType: import_zod8.z.enum(["QUEUE_DELAY", "REQUEST_COUNT"]).optional().describe(
+        "Autoscaler signal. QUEUE_DELAY scales on how long requests wait in the queue (queue endpoints only); REQUEST_COUNT scales on in-flight requests per worker. Defaults to QUEUE_DELAY for QUEUE endpoints and REQUEST_COUNT for LOAD_BALANCER ones."
+      ),
+      scalerValue: import_zod8.z.number().min(MIN_QUEUE_DELAY).optional().describe(
+        "Autoscaler target for the chosen scalerType \u2014 seconds of queue delay (min 0.5) or in-flight requests per worker (integer, min 1). Defaults to 4."
+      ),
+      idleTimeout: import_zod8.z.number().int().min(MIN_IDLE_TIMEOUT).max(MAX_IDLE_TIMEOUT).optional().describe(
+        "Idle timeout in seconds before scaling a worker down (1-3600). Does not apply to QUEUE endpoints scaling on REQUEST_COUNT."
+      ),
       dataCenterIds: import_zod8.z.array(import_zod8.z.string()).optional().describe("List of preferred data centers")
     },
     { title: "Create endpoint", ...WRITE },
@@ -2044,6 +2447,19 @@ function registerEndpointTools(server, rt) {
             status: 400
           });
         }
+        if (params.endpointType === "LOAD_BALANCER" && params.scalerType === "QUEUE_DELAY") {
+          return jsonReply2({
+            error: "LOAD_BALANCER endpoints have no request queue, so they cannot scale on QUEUE_DELAY. Use scalerType REQUEST_COUNT (the default for this endpoint type), or create a QUEUE endpoint instead.",
+            status: 400
+          });
+        }
+        const scalerError = scalerValueError(
+          params.scalerType ?? (params.endpointType === "LOAD_BALANCER" ? "REQUEST_COUNT" : void 0),
+          params.scalerValue
+        );
+        if (scalerError) {
+          return jsonReply2({ error: scalerError, status: 400 });
+        }
         const body = backend.mapCreate(params);
         const result2 = await callRestUrl(
           `${backend.base}${backend.list}`,
@@ -2081,15 +2497,21 @@ function registerEndpointTools(server, rt) {
   );
   server.tool(
     "update-endpoint",
-    "Update a Serverless endpoint's config. On v2 you can change image/disk/env/ports/registry/workers/scaling/networkVolumes/timeout/flashboot; on v1, scaling fields (worker min/max, idle timeout, scaler type/value, name). Only provided fields change.",
+    "Update a Serverless endpoint's config. On v2 you can change image/disk/env/ports/registry/workers/scaling/networkVolumes/timeout/flashboot; on v1, scaling fields (worker min/max, idle timeout, scaler type/value, name). Only provided fields change. An endpoint's request routing (queue vs load balancer) is fixed at creation and cannot be changed here \u2014 recreate the endpoint instead.",
     {
       endpointId: import_zod8.z.string().describe("ID of the endpoint to update"),
       name: import_zod8.z.string().optional().describe("New name for the endpoint"),
       workersMin: import_zod8.z.number().optional().describe("New minimum number of workers"),
       workersMax: import_zod8.z.number().optional().describe("New maximum number of workers"),
-      idleTimeout: import_zod8.z.number().optional().describe("New idle timeout in seconds"),
-      scalerType: import_zod8.z.enum(["QUEUE_DELAY", "REQUEST_COUNT"]).optional().describe("Scaler type"),
-      scalerValue: import_zod8.z.number().optional().describe("Scaler value"),
+      idleTimeout: import_zod8.z.number().int().min(MIN_IDLE_TIMEOUT).max(MAX_IDLE_TIMEOUT).optional().describe(
+        "New idle timeout in seconds (1-3600). Does not apply to queue endpoints scaling on REQUEST_COUNT."
+      ),
+      scalerType: import_zod8.z.enum(["QUEUE_DELAY", "REQUEST_COUNT"]).optional().describe(
+        "New autoscaler signal. Switchable on queue endpoints; load-balancing endpoints only accept REQUEST_COUNT."
+      ),
+      scalerValue: import_zod8.z.number().min(MIN_QUEUE_DELAY).optional().describe(
+        "New autoscaler target \u2014 seconds of queue delay (min 0.5) or in-flight requests per worker (integer, min 1). Applies to the endpoint's current scalerType unless you also pass a new one."
+      ),
       // --- v2-only inline-config fields ---
       imageName: import_zod8.z.string().optional().describe("New Docker image (v2)"),
       gpuPoolIds: import_zod8.z.array(import_zod8.z.string()).optional().describe('New GPU pool names (v2), e.g. ["AMPERE_80"]'),
@@ -2107,13 +2529,28 @@ function registerEndpointTools(server, rt) {
     async (params) => {
       const { endpointId, ...updateParams } = params;
       const backend = backendFor("endpoints");
-      const body = backend.mapUpdate(updateParams);
-      const result = await callRestUrl(
-        `${backend.base}${backend.get(endpointId)}`,
-        "PATCH",
-        body
+      const url = `${backend.base}${backend.get(endpointId)}`;
+      if (backend.version !== "v2") {
+        const body2 = backend.mapUpdate(updateParams);
+        return jsonReply2(await callRestUrl(url, "PATCH", body2));
+      }
+      let scalerType = updateParams.scalerType;
+      if (scalerType === void 0 && updateParams.scalerValue !== void 0) {
+        const current = await callRestUrl(url);
+        scalerType = current?.scaling?.type === "REQUEST_COUNT" ? "REQUEST_COUNT" : "QUEUE_DELAY";
+      }
+      const scalerError = scalerValueError(
+        scalerType,
+        updateParams.scalerValue
       );
-      return jsonReply2(result);
+      if (scalerError) {
+        return jsonReply2({ error: scalerError, status: 400 });
+      }
+      const body = backend.mapUpdate({
+        ...updateParams,
+        scalerType
+      });
+      return jsonReply2(await callRestUrl(url, "PATCH", body));
     }
   );
   server.tool(
@@ -2161,7 +2598,7 @@ function registerEndpointTools(server, rt) {
   );
   server.tool(
     "list-endpoint-workers",
-    "List the workers backing a Serverless endpoint, with their status and an aggregate summary. v2-only \u2014 returns a 501 notice on the v1 API. Paginated via limit/cursor.",
+    "List the workers backing a Serverless endpoint, with their status and an aggregate summary. v2-only \u2014 returns a 501 notice on the v1 API. An UNHEALTHY worker usually means the container is crash-looping (repeated starts that exit before the handler runs) \u2014 jobs on the endpoint will sit IN_QUEUE even though this is a worker failure, not a capacity shortage; inspect it with stream-worker-logs. Zero workers while jobs queue means the endpoint is waiting for GPU capacity. Paginated via limit/cursor.",
     {
       ...listPaginationParams,
       endpointId: import_zod8.z.string().describe("ID of the Serverless endpoint whose workers to list")
@@ -2187,7 +2624,7 @@ function registerEndpointTools(server, rt) {
   );
   server.tool(
     "stream-worker-logs",
-    "Fetch a bounded snapshot of a serverless worker's live logs (container and/or system) via Server-Sent Events. v2-only \u2014 returns a 501 notice on the v1 API. Get the workerId from list-endpoint-workers. Reads for up to maxWaitMs (default 5s) and returns the collected log lines; use `tail` to backfill recent lines first. Large output is truncated (see the `truncated` flag).",
+    "Fetch a bounded snapshot of a serverless worker's live logs (container and/or system) via Server-Sent Events. v2-only \u2014 returns a 501 notice on the v1 API. Get the workerId from list-endpoint-workers. Use this to diagnose UNHEALTHY workers: repeated `start container` system lines with no container output is the crash-loop signature (the container exits before the handler runs). Reads for up to maxWaitMs (default 5s) and returns the collected log lines; use `tail` to backfill recent lines first. Large output is truncated (see the `truncated` flag).",
     {
       endpointId: import_zod8.z.string().describe("ID of the Serverless endpoint the worker belongs to"),
       workerId: import_zod8.z.string().describe(
@@ -2210,8 +2647,67 @@ function registerEndpointTools(server, rt) {
 
 // src/tools/jobs.ts
 var import_zod9 = require("zod");
+var DIAGNOSIS_TTL_MS = 15e3;
+var MAX_DIAGNOSIS_ENTRIES = 500;
+var diagnosisCache = /* @__PURE__ */ new Map();
 function registerJobTools(server, rt) {
-  const { jsonReply: jsonReply2, serverlessRequest } = rt;
+  const { jsonReply: jsonReply2, serverlessRequest, backendFor, callRestUrl } = rt;
+  async function diagnoseQueuedJob(endpointId) {
+    const cached = diagnosisCache.get(endpointId);
+    if (cached && cached.expiresAt > Date.now()) {
+      return cached.value;
+    }
+    diagnosisCache.delete(endpointId);
+    try {
+      const backend = backendFor("workers");
+      if (backend.version !== "v2") return null;
+      const raw = await callRestUrl(
+        `${backend.base}/serverless/${endpointId}/workers`
+      );
+      const summary = raw?.summary;
+      const workers = raw?.workers ?? [];
+      if (!summary) return null;
+      const remember = (value) => {
+        if (diagnosisCache.size >= MAX_DIAGNOSIS_ENTRIES) {
+          const oldest = diagnosisCache.keys().next().value;
+          if (oldest !== void 0) diagnosisCache.delete(oldest);
+        }
+        diagnosisCache.set(endpointId, {
+          value,
+          expiresAt: Date.now() + DIAGNOSIS_TTL_MS
+        });
+        return value;
+      };
+      if ((summary.unhealthy ?? 0) > 0) {
+        const badIds = workers.filter((w) => w.status === "UNHEALTHY").map((w) => w.id).join(", ");
+        return remember({
+          workerHealth: summary,
+          hint: `${summary.unhealthy} of ${summary.total} worker(s) on this endpoint are UNHEALTHY \u2014 the container is likely crash-looping (repeated starts that exit before the handler runs). The job can stay IN_QUEUE indefinitely; this is a worker failure, NOT a capacity shortage. Inspect the logs with stream-worker-logs${badIds ? ` (workerId: ${badIds})` : ""}.`
+        });
+      }
+      if ((summary.total ?? 0) === 0) {
+        return remember({
+          workerHealth: summary,
+          hint: "No workers are scheduled for this endpoint yet \u2014 it may simply be scaling up from zero (normal for the first seconds of a cold start), or it is waiting for GPU capacity / its GPU-CUDA constraints exclude the currently-available hosts. If this persists, check availability with list-gpu-types or widen the gpuIds/CUDA settings."
+        });
+      }
+      if ((summary.throttled ?? 0) > 0 && (summary.running ?? 0) === 0) {
+        return remember({
+          workerHealth: summary,
+          hint: "Workers exist but are throttled \u2014 the hosts are at capacity right now; the job should start when capacity frees up."
+        });
+      }
+      if ((summary.initializing ?? 0) > 0) {
+        return remember({
+          workerHealth: summary,
+          hint: "A worker is initializing \u2014 likely a cold start (image pull / model load); the job should start soon."
+        });
+      }
+      return remember({ workerHealth: summary, hint: "" });
+    } catch {
+      return null;
+    }
+  }
   const endpointIdSchema = import_zod9.z.string().regex(/^[a-zA-Z0-9_-]+$/, "Invalid endpoint ID format");
   const jobIdSchema = import_zod9.z.string().regex(/^[a-zA-Z0-9_-]+$/, "Invalid job ID format");
   const inputSchema = import_zod9.z.record(import_zod9.z.unknown()).describe(
@@ -2285,7 +2781,7 @@ function registerJobTools(server, rt) {
   );
   server.tool(
     "get-job-status",
-    "Check the status of an asynchronous Serverless job. Returns the current status and output when complete. Job statuses: IN_QUEUE, IN_PROGRESS, COMPLETED, FAILED, CANCELLED, TIMED_OUT.",
+    "Check the status of an asynchronous Serverless job. Returns the current status and output when complete. Job statuses: IN_QUEUE, IN_PROGRESS, COMPLETED, FAILED, CANCELLED, TIMED_OUT. IMPORTANT: a job stuck IN_QUEUE does not necessarily mean a capacity shortage \u2014 a worker may have spun up and crash-looped (the platform marks it UNHEALTHY while the job stays queued). When the job is IN_QUEUE this tool attaches a workerHealth summary and a hint; to dig deeper, call list-endpoint-workers (look for UNHEALTHY) and stream-worker-logs.",
     {
       endpointId: endpointIdSchema.describe(
         "ID of the Serverless endpoint the job belongs to"
@@ -2298,6 +2794,16 @@ function registerJobTools(server, rt) {
         params.endpointId,
         `/status/${params.jobId}`
       );
+      if (result && typeof result === "object" && result.status === "IN_QUEUE") {
+        const diagnosis = await diagnoseQueuedJob(params.endpointId);
+        if (diagnosis) {
+          return jsonReply2({
+            ...result,
+            workerHealth: diagnosis.workerHealth,
+            ...diagnosis.hint ? { hint: diagnosis.hint } : {}
+          });
+        }
+      }
       return jsonReply2(result);
     }
   );
@@ -2399,7 +2905,7 @@ function registerJobTools(server, rt) {
   );
   server.tool(
     "endpoint-health",
-    "Get the health and operational status of a Serverless endpoint, including worker counts and job statistics.",
+    "Get the health and operational status of a Serverless endpoint, including worker counts and job statistics. Use this when jobs are stuck IN_QUEUE: unhealthy workers mean a crash-looping container (a worker failure \u2014 inspect with stream-worker-logs), while zero workers means the endpoint is waiting for GPU capacity.",
     {
       endpointId: endpointIdSchema.describe(
         "ID of the Serverless endpoint to check health for"