@runpod/mcp-server 3.1.0 → 3.3.0

package/dist/tools.cjs

@@ -38,16 +38,177 @@ 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;
   }
 };
+var DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
+var MIN_REQUEST_TIMEOUT_MS = 1e3;
+var RequestTimeoutError = class extends Error {
+  constructor(prefix, timeoutMs, method) {
+    const write = method !== "GET" && method !== "HEAD";
+    super(
+      `${prefix}: no response after ${timeoutMs}ms for ${method} (the API may be overloaded, or still be working on it). ${write ? "This request may have SUCCEEDED upstream \u2014 do not retry blindly. Check with the matching list-/get- tool first and retry only if it did not take effect." : "This was a read and changed nothing, so retrying is safe."}`
+    );
+    this.name = "RequestTimeoutError";
+    this.timeoutMs = timeoutMs;
+    this.method = method;
+  }
+};
+async function withRequestTimeout(errorPrefix, timeoutMs, method, run) {
+  const signal = AbortSignal.timeout(timeoutMs);
+  try {
+    return await run(signal);
+  } catch (error) {
+    if (error instanceof HttpError || !signal.aborted) throw error;
+    throw new RequestTimeoutError(errorPrefix, timeoutMs, method);
+  }
+}
 function isJsonContentType(contentType) {
   if (!contentType) return false;
   const ct = contentType.toLowerCase();
@@ -63,24 +224,49 @@ function buildRequestHeaders(apiKey, tracking) {
     ...tracking()
   };
 }
+function resolveCeiling(ceiling) {
+  if (ceiling === void 0) return Infinity;
+  if (typeof ceiling !== "function") return ceiling;
+  return Math.max(ceiling(), MIN_REQUEST_TIMEOUT_MS);
+}
+function clampTimeout(requestedMs, ceiling, defaultMs = DEFAULT_REQUEST_TIMEOUT_MS) {
+  return Math.min(requestedMs ?? defaultMs, resolveCeiling(ceiling));
+}
 function createHttpClient(deps) {
-  return async function request(url, method = "GET", body) {
-    const init = {
+  const defaultTimeoutMs = deps.defaultTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  return async function request(url, method = "GET", body, options) {
+    const timeoutMs = clampTimeout(
+      options?.timeoutMs,
+      deps.maxTimeoutMs,
+      defaultTimeoutMs
+    );
+    return withRequestTimeout(
+      deps.errorPrefix,
+      timeoutMs,
       method,
-      headers: buildRequestHeaders(deps.apiKey, deps.tracking)
-    };
-    if (body && methodSendsBody(method)) {
-      init.body = JSON.stringify(body);
-    }
-    const response = await deps.fetch(url, init);
-    if (!response.ok) {
-      throw new HttpError(
-        deps.errorPrefix,
-        response.status,
-        await response.text()
-      );
-    }
-    return isJsonContentType(response.headers.get("content-type")) ? response.json() : { success: true, status: response.status };
+      async (signal) => {
+        const init = {
+          method,
+          headers: buildRequestHeaders(deps.apiKey, deps.tracking),
+          signal
+        };
+        if (body && methodSendsBody(method)) {
+          init.body = JSON.stringify(body);
+        }
+        const response = await deps.fetch(url, init);
+        if (!response.ok) {
+          const hint = response.status === 429 ? rateLimitHint(
+            response.headers.get("ratelimit"),
+            response.headers.get("retry-after")
+          ) : response.status === 401 ? EXPIRED_CREDENTIAL_HINT : void 0;
+          const text = await response.text().catch(
+            () => "<body unavailable: the connection closed while reading it>"
+          );
+          throw new HttpError(deps.errorPrefix, response.status, text, hint);
+        }
+        return isJsonContentType(response.headers.get("content-type")) ? response.json() : { success: true, status: response.status };
+      }
+    );
   };
 }
 
@@ -136,7 +322,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 ?? []) {
@@ -225,7 +419,7 @@ function containerConfigToV2(p) {
 function gpuConfigToV2(gpuTypeIds, gpuCount) {
   const id = gpuTypeIds?.[0];
   if (id === void 0) return void 0;
-  return compact({ id, count: gpuCount });
+  return { id, count: gpuCount ?? 1 };
 }
 function mapPodCreateToV2(params) {
   return compact({
@@ -352,6 +546,42 @@ function podBodyFromTemplate(template) {
   }
   return out;
 }
+var SSH_PUBLIC_KEY_LINE = /^(ssh-[a-z0-9-]+|ecdsa-[a-z0-9-]+|sk-[a-z0-9@.-]+)\s+\S+/i;
+var PRIVATE_KEY_MARKER = /private[-\s]?key|PuTTY-User-Key-File/i;
+function normalizeSshPublicKey(input) {
+  if (PRIVATE_KEY_MARKER.test(input))
+    return {
+      ok: false,
+      error: 'sshPublicKey looks like a PRIVATE key. Pass the PUBLIC key instead \u2014 the contents of your ~/.ssh/<key>.pub file (e.g. "ssh-ed25519 AAAA\u2026").'
+    };
+  const lines = input.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0);
+  if (lines.length === 0)
+    return {
+      ok: false,
+      error: "sshPublicKey is empty. Pass the contents of your ~/.ssh/<key>.pub file, or omit the parameter entirely to create the pod without SSH."
+    };
+  if (lines.some((line) => !SSH_PUBLIC_KEY_LINE.test(line)))
+    return {
+      ok: false,
+      error: 'sshPublicKey is not an SSH public key. Expected the CONTENTS of your ~/.ssh/<key>.pub file \u2014 a line like "ssh-ed25519 AAAAC3Nza\u2026 you@host" (ssh-*, ecdsa-*, or sk-* followed by the base64 key) \u2014 not a file path, a SHA256 fingerprint, or a bare base64 blob. Newline-separate multiple keys.'
+    };
+  return { ok: true, key: lines.join("\n") };
+}
+function applySshPublicKey(body, sshPublicKey) {
+  const ports = Array.isArray(body.ports) ? body.ports : [];
+  const hasSshPort = ports.some((p) => /^\s*22\/tcp\s*$/i.test(String(p)));
+  const env = { ...body.env ?? {} };
+  const key = sshPublicKey.trim();
+  if (!env.PUBLIC_KEY) env.PUBLIC_KEY = key;
+  else if (!env.PUBLIC_KEY.includes(key))
+    env.PUBLIC_KEY = `${env.PUBLIC_KEY}
+${key}`;
+  return {
+    ...body,
+    ports: hasSshPort ? ports : [...ports, "22/tcp"],
+    env
+  };
+}
 function mapTemplateUpdateToV2(params) {
   return {
     ...containerConfigToV2(params),
@@ -395,7 +625,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";
@@ -558,7 +788,7 @@ function resolveBackend(opts) {
 }
 
 // src/tools/runtime.ts
-var MCP_SERVER_VERSION = true ? "3.1.0" : "dev";
+var MCP_SERVER_VERSION = true ? "3.3.0" : "dev";
 var SESSION_ID = (0, import_node_crypto.randomUUID)();
 function trackingHeaders(server, ctx) {
   const info = server.server.getClientVersion();
@@ -573,6 +803,11 @@ function trackingHeaders(server, ctx) {
     sessionId: SESSION_ID
   });
 }
+var HTTP_TRANSPORT_BUDGET_MS = 5e4;
+function invocationBudget(totalMs) {
+  const startedAt = Date.now();
+  return () => totalMs - (Date.now() - startedAt);
+}
 var defaultFetch = import_node_fetch.default;
 async function withApiErrorLog(label, call) {
   try {
@@ -596,6 +831,23 @@ var DESTRUCTIVE = {
   openWorldHint: true
 };
 async function graphqlRequest(query, tracking, fetchImpl, url, options) {
+  return withRequestTimeout(
+    "Runpod GraphQL Error",
+    clampTimeout(options?.timeoutMs, options?.maxTimeoutMs),
+    // GraphQL is POST on the wire whatever it carries, but the retry advice keys
+    // off the method, and telling a caller its list-gpu-types "may have
+    // SUCCEEDED upstream — check with the matching list-/get- tool first" points
+    // it back at the tool that just failed. The operation keyword is what
+    // actually says whether anything could have been written.
+    isGraphqlMutation(query) ? "POST" : "GET",
+    (signal) => runGraphql(query, tracking, fetchImpl, url, signal, options)
+  );
+}
+function isGraphqlMutation(query) {
+  const firstMeaningful = query.split("\n").map((line) => line.trim()).find((line) => line.length > 0 && !line.startsWith("#"));
+  return /^mutation\b/.test(firstMeaningful ?? "");
+}
+async function runGraphql(query, tracking, fetchImpl, url, signal, options) {
   const response = await fetchImpl(url, {
     method: "POST",
     headers: {
@@ -606,8 +858,39 @@ async function graphqlRequest(query, tracking, fetchImpl, url, options) {
     body: JSON.stringify({
       query,
       ...options?.variables ? { variables: options.variables } : {}
-    })
+    }),
+    signal
   });
+  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(
@@ -632,39 +915,53 @@ function createToolRuntime(server, ctx, deps = {}) {
   }
   const rawFetch = deps.fetch ?? defaultFetch;
   const httpFetch = observeUnauthorized(rawFetch);
+  const remainingHttpBudgetMs = invocationBudget(HTTP_TRANSPORT_BUDGET_MS);
+  const timeouts = {
+    defaultTimeoutMs: deps.defaultTimeoutMs,
+    maxTimeoutMs: deps.maxTimeoutMs ?? (ctx.transport === "http" ? remainingHttpBudgetMs : void 0)
+  };
   const v1Client = createHttpClient({
     apiKey: ctx.apiKey,
     fetch: httpFetch,
     tracking,
-    errorPrefix: "Runpod API Error"
+    errorPrefix: "Runpod API Error",
+    ...timeouts
   });
-  const runpodRequest = (endpoint, method = "GET", body) => withApiErrorLog(
+  const runpodRequest = (endpoint, method = "GET", body, options) => withApiErrorLog(
     "Error calling Runpod API:",
-    () => v1Client(`${restV1Base(process.env)}${endpoint}`, method, body)
+    () => v1Client(
+      `${restV1Base(process.env)}${endpoint}`,
+      method,
+      body,
+      options
+    )
   );
   const serverlessClient = createHttpClient({
     apiKey: ctx.apiKey,
     fetch: httpFetch,
     tracking,
-    errorPrefix: "Runpod Serverless API Error"
+    errorPrefix: "Runpod Serverless API Error",
+    ...timeouts
   });
-  const serverlessRequest = (endpointId, path, method = "GET", body) => withApiErrorLog(
+  const serverlessRequest = (endpointId, path, method = "GET", body, options) => withApiErrorLog(
     "Error calling Runpod Serverless API:",
     () => serverlessClient(
       `${serverlessBase(process.env)}/${endpointId}${path}`,
       method,
-      body
+      body,
+      options
     )
   );
   const restClient = createHttpClient({
     apiKey: ctx.apiKey,
     fetch: httpFetch,
     tracking,
-    errorPrefix: "Runpod API Error"
+    errorPrefix: "Runpod API Error",
+    ...timeouts
   });
-  const callRestUrl = (url, method = "GET", body) => withApiErrorLog(
+  const callRestUrl = (url, method = "GET", body, options) => withApiErrorLog(
     "Error calling Runpod API:",
-    () => restClient(url, method, body)
+    () => restClient(url, method, body, options)
   );
   const sseFetch = observeUnauthorized(
     deps.sseFetch ?? import_node_fetch.default
@@ -697,12 +994,18 @@ function createToolRuntime(server, ctx, deps = {}) {
   };
   return {
     jsonReply,
+    // No GraphQL caller overrides a deadline, but both are still capped by the
+    // shared budget: deploy-hub-repo spends one of each back to back.
     graphql: (query) => graphqlRequest(
       query,
       tracking,
       // rawFetch, not httpFetch: this call carries no credential (see above).
       rawFetch,
-      publicGraphqlBase(process.env)
+      publicGraphqlBase(process.env),
+      {
+        timeoutMs: deps.defaultTimeoutMs,
+        maxTimeoutMs: timeouts.maxTimeoutMs
+      }
     ),
     graphqlAuthed: (query, variables) => graphqlRequest(
       query,
@@ -710,7 +1013,12 @@ function createToolRuntime(server, ctx, deps = {}) {
       httpFetch,
       // NOT publicGraphqlBase: this call carries the caller's API key.
       authedGraphqlBase(process.env),
-      { variables, apiKey: ctx.apiKey }
+      {
+        variables,
+        apiKey: ctx.apiKey,
+        timeoutMs: deps.defaultTimeoutMs,
+        maxTimeoutMs: timeouts.maxTimeoutMs
+      }
     ),
     runpodRequest,
     serverlessRequest,
@@ -718,7 +1026,8 @@ function createToolRuntime(server, ctx, deps = {}) {
     backendFor,
     streamSse,
     podAction,
-    env: process.env
+    env: process.env,
+    transport: ctx.transport
   };
 }
 
@@ -787,6 +1096,7 @@ function capListResult(result, options, extra) {
 }
 
 // src/tools/catalog.ts
+var GPU_PRODUCTS = /* @__PURE__ */ new Set(["POD", "CLUSTER", "SERVERLESS"]);
 function registerCatalogTools(server, rt) {
   const { jsonReply: jsonReply2, graphql, callRestUrl, backendFor } = rt;
   server.tool(
@@ -805,6 +1115,9 @@ function registerCatalogTools(server, rt) {
       ),
       includeAvailability: import_zod3.z.boolean().optional().describe(
         "Request realtime stock and annotate each GPU with an availability summary (HIGH/MEDIUM/LOW/NONE). Default true. Set false to skip the availability lookup \u2014 then out-of-stock GPUs cannot be filtered."
+      ),
+      product: import_zod3.z.enum(["POD", "CLUSTER", "SERVERLESS"]).optional().describe(
+        "Product context for the availability lookup \u2014 the same GPU can be scarce for Pods and plentiful for Serverless. Default POD. Use SERVERLESS when picking a GPU for an endpoint, CLUSTER for Instant Clusters. Ignored when includeAvailability is false."
       )
     },
     { title: "List GPU types", ...READ_ONLY },
@@ -812,8 +1125,9 @@ function registerCatalogTools(server, rt) {
       const backend = backendFor("gpus");
       if (backend.version === "v2") {
         const wantAvailability = params.includeAvailability !== false;
+        const product = GPU_PRODUCTS.has(String(params.product)) ? String(params.product) : "POD";
         const raw = await callRestUrl(
-          `${backend.base}${backend.list}${wantAvailability ? "?include=AVAILABILITY" : ""}`
+          `${backend.base}${backend.list}${wantAvailability ? `?include=AVAILABILITY&product=${product}` : ""}`
         );
         let gpus = backend.unwrap(raw);
         gpus = gpus.filter((g) => g.id !== "unknown");
@@ -986,6 +1300,9 @@ function registerCatalogTools(server, rt) {
       gpuTypeId: import_zod3.z.string().describe("ID of the GPU type to retrieve"),
       includeAvailability: import_zod3.z.boolean().optional().describe(
         "Include realtime per-datacenter availability (HIGH/MEDIUM/LOW/NONE). Default true."
+      ),
+      product: import_zod3.z.enum(["POD", "CLUSTER", "SERVERLESS"]).optional().describe(
+        "Product context for the availability lookup \u2014 stock differs by product. Default POD. Use SERVERLESS when picking a GPU for an endpoint, CLUSTER for Instant Clusters. Ignored when includeAvailability is false."
       )
     },
     { title: "Get GPU type", ...READ_ONLY },
@@ -998,7 +1315,8 @@ function registerCatalogTools(server, rt) {
         });
       }
       const path = backend.get(encodeURIComponent(params.gpuTypeId));
-      const query = params.includeAvailability === false ? "" : "?include=AVAILABILITY";
+      const product = GPU_PRODUCTS.has(String(params.product)) ? String(params.product) : "POD";
+      const query = params.includeAvailability === false ? "" : `?include=AVAILABILITY&product=${product}`;
       const result = await callRestUrl(`${backend.base}${path}${query}`);
       return jsonReply2(result);
     }
@@ -1024,6 +1342,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).",
@@ -1706,9 +2196,11 @@ function registerPodTools(server, rt) {
   );
   server.tool(
     "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.',
+    '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). For full SSH access (including SCP/SFTP/rsync), pass sshPublicKey \u2014 it sets the PUBLIC_KEY env var and exposes 22/tcp, which official Runpod images turn into a running sshd with the key authorized. 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."
@@ -1718,12 +2210,18 @@ function registerPodTools(server, rt) {
       ),
       cloudType: import_zod7.z.enum(["SECURE", "COMMUNITY"]).optional().describe("SECURE or COMMUNITY cloud"),
       gpuTypeIds: import_zod7.z.array(import_zod7.z.string()).optional().describe("List of acceptable GPU types"),
-      gpuCount: import_zod7.z.number().optional().describe("Number of GPUs"),
+      // v2 GpuConfig.count is `integer, minimum: 1`. Without these bounds a 0,
+      // a negative, or a fractional count reached the wire as-is and came back
+      // as a raw 422; reject it here with a message that names the field.
+      gpuCount: import_zod7.z.number().int().min(1).optional().describe("Number of GPUs (minimum 1)"),
       containerDiskInGb: import_zod7.z.number().optional().describe("Container disk size in GB"),
       volumeInGb: import_zod7.z.number().optional().describe("Volume size in GB"),
       volumeMountPath: import_zod7.z.string().optional().describe("Path to mount the volume"),
       ports: import_zod7.z.array(import_zod7.z.string()).optional().describe("Ports to expose (e.g., '8888/http', '22/tcp')"),
       env: import_zod7.z.record(import_zod7.z.string()).optional().describe("Environment variables"),
+      sshPublicKey: import_zod7.z.string().optional().describe(
+        'SSH PUBLIC key(s) to authorize on the pod \u2014 the CONTENTS of your ~/.ssh/<key>.pub file, i.e. a literal "ssh-ed25519 AAAAC3Nza\u2026 you@host" line, NOT a path to the file, a fingerprint, or the private key; newline-separate multiple keys. Merges the key into the PUBLIC_KEY env var and ensures 22/tcp is exposed, enabling full SSH (SCP/SFTP/rsync) on any image that honors the PUBLIC_KEY convention \u2014 all runpod/* official images do. Extends template ports/env rather than replacing them.'
+      ),
       containerRegistryAuthId: import_zod7.z.string().optional().describe(
         "Container registry credential ID for pulling a private image (see list-container-registry-auths). When deploying from a templateId, this overrides the credential the template carries; pass an empty string to deploy with NO credential (clears a template\u2019s inherited registry)."
       ),
@@ -1732,6 +2230,15 @@ function registerPodTools(server, rt) {
     { title: "Create pod", ...WRITE },
     async (params) => {
       const backend = backendFor("pods");
+      const { sshPublicKey, ...podParams } = params;
+      let sshKey;
+      if (sshPublicKey !== void 0) {
+        const validated = normalizeSshPublicKey(sshPublicKey);
+        if (!validated.ok)
+          return jsonReply2({ error: validated.error, status: 400 });
+        sshKey = validated.key;
+      }
+      const sshNote = "sshPublicKey applied: PUBLIC_KEY env set and 22/tcp exposed. Full SSH (incl. SCP/SFTP/rsync) also requires an image that installs PUBLIC_KEY into authorized_keys and starts sshd (all runpod/* official images do) and a machine with a public IP \u2014 read the pod\u2019s portMappings for port 22 once it is running.";
       if (params.templateId && backend.version !== "v2") {
         return jsonReply2({
           error: "Deploying a pod from a templateId is only supported on the v2 REST API. Set RUNPOD_REST_VERSION=v2, or pass imageName instead.",
@@ -1767,6 +2274,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({
@@ -1775,13 +2288,15 @@ function registerPodTools(server, rt) {
             });
           }
           try {
+            const cpuBody = sshKey ? applySshPublicKey(podParams, sshKey) : podParams;
             const result = await callRestUrl(
               `${restV1Base(env)}/pods`,
               "POST",
-              params
+              cpuBody
             );
             return jsonReply2({
               ...result,
+              ...sshKey ? { _ssh: sshNote } : {},
               _servedBy: "v1",
               _note: "CPU pod: created on the v1 API, because the v2 REST API does not support CPU pods yet."
             });
@@ -1798,7 +2313,7 @@ function registerPodTools(server, rt) {
           }
         }
       }
-      let body = backend.mapCreate(params);
+      let body = backend.mapCreate(podParams);
       if (params.templateId) {
         let template;
         try {
@@ -1816,19 +2331,21 @@ function registerPodTools(server, rt) {
         }
         body = { ...podBodyFromTemplate(template), ...body };
       }
+      if (sshKey) body = applySshPublicKey(body, sshKey);
       try {
         const result = await callRestUrl(
           `${backend.base}${backend.list}`,
           "POST",
           body
         );
+        const extras = {};
+        if (sshKey) extras._ssh = sshNote;
         if (backend.version === "v2" && (params.gpuTypeIds?.length ?? 0) > 1) {
-          return jsonReply2({
-            ...result,
-            _warning: `v2 accepts one GPU type per pod; used "${params.gpuTypeIds[0]}" and ignored ${params.gpuTypeIds.length - 1} other(s): ${params.gpuTypeIds.slice(1).join(", ")}.`
-          });
+          extras._warning = `v2 accepts one GPU type per pod; used "${params.gpuTypeIds[0]}" and ignored ${params.gpuTypeIds.length - 1} other(s): ${params.gpuTypeIds.slice(1).join(", ")}.`;
         }
-        return jsonReply2(result);
+        return jsonReply2(
+          Object.keys(extras).length ? { ...result, ...extras } : result
+        );
       } catch (error) {
         if (error instanceof HttpError) {
           return jsonReply2({ error: error.message, status: error.status });
@@ -2289,8 +2806,108 @@ var import_zod9 = require("zod");
 var DIAGNOSIS_TTL_MS = 15e3;
 var MAX_DIAGNOSIS_ENTRIES = 500;
 var diagnosisCache = /* @__PURE__ */ new Map();
+var HTTP_LONG_POLL_BUDGET_MS = 45e3;
+var STDIO_STREAM_BUDGET_MS = 5 * 60 * 1e3;
+var RUNSYNC_UPSTREAM_DEFAULT_WAIT_MS = 9e4;
+var STREAM_UPSTREAM_DEFAULT_WAIT_MS = 1e4;
+var HTTP_STREAM_POLL_WAIT_MS = 1e3;
+var STREAM_JOB_POLL_INTERVAL_MS = 1e3;
+var MAX_CONSECUTIVE_STREAM_ERRORS = 5;
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+  "COMPLETED",
+  "FAILED",
+  "CANCELLED",
+  "TIMED_OUT"
+]);
+function isUnfinishedJobReply(result) {
+  return result !== null && typeof result === "object" && !Array.isArray(result) && !("waitClamped" in result) && !TERMINAL_STATUSES.has(result.status ?? "");
+}
+function formatBudget(ms) {
+  return ms >= 12e4 ? `${Math.round(ms / 6e4)} minutes` : `${Math.round(ms / 1e3)} seconds`;
+}
+var UPSTREAM_HOLD_SLACK_MS = 5e3;
+var MIN_STREAM_POLL_TIMEOUT_MS = 2e3;
+var QUEUED_DIAGNOSIS_TIMEOUT_MS = 5e3;
+function streamPollTimeoutMs(remainingMs, holdMs) {
+  return Math.max(
+    Math.min(remainingMs, holdMs + UPSTREAM_HOLD_SLACK_MS),
+    MIN_STREAM_POLL_TIMEOUT_MS
+  );
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function streamPollPlan(hosted) {
+  return hosted ? {
+    budgetMs: HTTP_LONG_POLL_BUDGET_MS,
+    holdMs: HTTP_STREAM_POLL_WAIT_MS,
+    query: `?wait=${HTTP_STREAM_POLL_WAIT_MS}`
+  } : {
+    budgetMs: STDIO_STREAM_BUDGET_MS,
+    holdMs: STREAM_UPSTREAM_DEFAULT_WAIT_MS,
+    query: ""
+  };
+}
+var RESUME_ADVICE = "Call stream-job again to continue collecting output, get-job-status to check the job without streaming, or stream without a budget by calling the runtime API directly (GET https://api.runpod.ai/v2/{endpointId}/stream/{jobId} with a Bearer API key).";
+function budgetExhaustedNote(budgetMs, lastError) {
+  return {
+    pollingTimedOut: true,
+    note: `Polling stopped after ${formatBudget(
+      budgetMs
+    )} with the job possibly still running. ${RESUME_ADVICE}`,
+    // Surface the trailing error (if any) instead of discarding it — the last
+    // polls may have been failing (e.g. job expired) even though earlier ones
+    // succeeded. Cleared on success, so this is never a stale error from
+    // minutes of healthy streaming ago.
+    ...lastError ? { lastError } : {}
+  };
+}
+function errorCapNote(lastError) {
+  return {
+    error: `Polling aborted after ${MAX_CONSECUTIVE_STREAM_ERRORS} consecutive errors: ${lastError}`,
+    note: `Polling stopped after ${MAX_CONSECUTIVE_STREAM_ERRORS} consecutive errors with the job possibly still running. ${RESUME_ADVICE}`
+  };
+}
+async function collectJobStream(deps) {
+  const { poll, budgetMs, holdMs } = deps;
+  const startedAt = Date.now();
+  const elapsed = () => Date.now() - startedAt;
+  const chunks = [];
+  let result = {};
+  let consecutiveErrors = 0;
+  let lastError;
+  while (true) {
+    try {
+      const reply = await poll(
+        streamPollTimeoutMs(budgetMs - elapsed(), holdMs)
+      );
+      consecutiveErrors = 0;
+      lastError = void 0;
+      if (Array.isArray(reply.stream)) chunks.push(...reply.stream);
+      result = reply;
+      if (TERMINAL_STATUSES.has(reply.status)) break;
+    } catch (error) {
+      consecutiveErrors++;
+      lastError = error instanceof Error ? error.message : String(error);
+      if (consecutiveErrors >= MAX_CONSECUTIVE_STREAM_ERRORS) {
+        result = { ...result, ...errorCapNote(lastError) };
+        break;
+      }
+    }
+    if (elapsed() > budgetMs) {
+      result = { ...result, ...budgetExhaustedNote(budgetMs, lastError) };
+      break;
+    }
+    await sleep(STREAM_JOB_POLL_INTERVAL_MS);
+  }
+  return { result, chunks };
+}
 function registerJobTools(server, rt) {
   const { jsonReply: jsonReply2, serverlessRequest, backendFor, callRestUrl } = rt;
+  const hosted = rt.transport === "http";
+  const streamBudget = formatBudget(
+    hosted ? HTTP_LONG_POLL_BUDGET_MS : STDIO_STREAM_BUDGET_MS
+  );
   async function diagnoseQueuedJob(endpointId) {
     const cached = diagnosisCache.get(endpointId);
     if (cached && cached.expiresAt > Date.now()) {
@@ -2301,7 +2918,10 @@ function registerJobTools(server, rt) {
       const backend = backendFor("workers");
       if (backend.version !== "v2") return null;
       const raw = await callRestUrl(
-        `${backend.base}/serverless/${endpointId}/workers`
+        `${backend.base}/serverless/${endpointId}/workers`,
+        "GET",
+        void 0,
+        { timeoutMs: QUEUED_DIAGNOSIS_TIMEOUT_MS }
       );
       const summary = raw?.summary;
       const workers = raw?.workers ?? [];
@@ -2392,14 +3012,14 @@ function registerJobTools(server, rt) {
   );
   server.tool(
     "runsync-endpoint",
-    "Submit a synchronous job to a Serverless endpoint and wait for the result. Best for tasks completing within 90 seconds. If processing exceeds 90 seconds, the response returns a job ID to poll with get-job-status. Max payload: 20 MB. Results expire after 1 minute. Use the wait parameter to extend the server-side wait up to 5 minutes (300000 ms).",
+    `Submit a synchronous job to a Serverless endpoint and wait for the result. Best for fast tasks: if the job outlives the wait, the response returns a job ID and a non-terminal status (IN_QUEUE or IN_PROGRESS) to poll with get-job-status. Max payload 20 MB; results expire after 1 minute. ${hosted ? `This server waits up to ${HTTP_LONG_POLL_BUDGET_MS} ms \u2014 it runs behind a 60-second gateway deadline, so that is both the default and the ceiling for the wait parameter. For longer jobs use run-endpoint + get-job-status, or POST https://api.runpod.ai/v2/{endpointId}/runsync?wait=300000 directly with a Bearer API key.` : "The wait parameter extends the server-side wait to up to 5 minutes (300000 ms); it defaults to 90000 (90 seconds)."}`,
     {
       endpointId: endpointIdSchema.describe(
         "ID of the Serverless endpoint to run synchronously"
       ),
       input: inputSchema,
       wait: import_zod9.z.number().min(1e3).max(3e5).optional().describe(
-        "How long in milliseconds the server should wait for a result before returning a job ID to poll (1000\u2013300000). Defaults to 90000 (90 seconds)."
+        hosted ? `How long in milliseconds the server should wait for a result before returning a job ID to poll. Accepted range 1000\u2013300000, but this server clamps anything above ${HTTP_LONG_POLL_BUDGET_MS} down to ${HTTP_LONG_POLL_BUDGET_MS}, which is also the effective default.` : "How long in milliseconds the server should wait for a result before returning a job ID to poll (1000\u2013300000). Defaults to 90000 (90 seconds)."
       ),
       webhook: webhookSchema,
       policy: policySchema,
@@ -2408,13 +3028,36 @@ function registerJobTools(server, rt) {
     { title: "Run endpoint (sync)", ...WRITE },
     async (params) => {
       const { endpointId, wait, ...body } = params;
-      const path = wait ? `/runsync?wait=${wait}` : "/runsync";
+      const effectiveWait = hosted ? Math.min(
+        wait ?? RUNSYNC_UPSTREAM_DEFAULT_WAIT_MS,
+        HTTP_LONG_POLL_BUDGET_MS
+      ) : wait;
+      const waitQuery = effectiveWait === void 0 ? "" : `?wait=${effectiveWait}`;
+      const path = `/runsync${waitQuery}`;
       const result = await serverlessRequest(
         endpointId,
         path,
         "POST",
-        body
+        body,
+        {
+          // From the wait actually sent — on http the clamped 45s, not the
+          // 300s the caller may have asked for.
+          timeoutMs: (effectiveWait ?? RUNSYNC_UPSTREAM_DEFAULT_WAIT_MS) + UPSTREAM_HOLD_SLACK_MS
+        }
       );
+      const requestedWait = wait ?? RUNSYNC_UPSTREAM_DEFAULT_WAIT_MS;
+      if (hosted && requestedWait > HTTP_LONG_POLL_BUDGET_MS && isUnfinishedJobReply(result)) {
+        return jsonReply2({
+          ...result,
+          waitClamped: {
+            requestedMs: requestedWait,
+            effectiveMs: effectiveWait,
+            reason: `This server runs behind a 60-second gateway deadline, so a non-terminal status here means the job outlived ${formatBudget(
+              HTTP_LONG_POLL_BUDGET_MS
+            )}, not the requested wait \u2014 poll get-job-status rather than treating it as stuck.`
+          }
+        });
+      }
       return jsonReply2(result);
     }
   );
@@ -2448,7 +3091,7 @@ function registerJobTools(server, rt) {
   );
   server.tool(
     "stream-job",
-    "Retrieve all streaming output from a Serverless job by polling until the job reaches a terminal state. The worker must support streaming output. Polls /stream/{jobId} repeatedly and collects every chunk until status is COMPLETED, FAILED, CANCELLED, or TIMED_OUT.",
+    `Retrieve streaming output from a Serverless job. The worker must support streaming output. Polls /stream/{jobId} and collects chunks until the status is COMPLETED, FAILED, CANCELLED, or TIMED_OUT, for up to ${streamBudget}${hosted ? " (this server runs behind a 60-second gateway deadline)" : ""}. If the budget expires first, returns the chunks collected so far with pollingTimedOut: true \u2014 call stream-job again to resume where it left off, or get-job-status to check without streaming.${hosted ? " To collect with no budget, poll GET https://api.runpod.ai/v2/{endpointId}/stream/{jobId} yourself with a Bearer API key until the status is terminal \u2014 each request drains only the chunks buffered so far, so a single request is not the whole output." : ""}`,
     {
       endpointId: endpointIdSchema.describe(
         "ID of the Serverless endpoint the job belongs to"
@@ -2457,51 +3100,16 @@ function registerJobTools(server, rt) {
     },
     { title: "Stream job", ...READ_ONLY },
     async (params) => {
-      const TERMINAL_STATUSES = /* @__PURE__ */ new Set([
-        "COMPLETED",
-        "FAILED",
-        "CANCELLED",
-        "TIMED_OUT"
-      ]);
-      const MAX_POLL_TIME_MS = 5 * 60 * 1e3;
-      const POLL_INTERVAL_MS = 1e3;
-      const MAX_CONSECUTIVE_ERRORS = 5;
-      const allChunks = [];
-      let finalResult = {};
-      let consecutiveErrors = 0;
-      let lastError;
-      const startTime = Date.now();
-      while (true) {
-        try {
-          const result = await serverlessRequest(
-            params.endpointId,
-            `/stream/${params.jobId}`
-          );
-          consecutiveErrors = 0;
-          if (Array.isArray(result.stream)) {
-            allChunks.push(...result.stream);
-          }
-          finalResult = result;
-          if (TERMINAL_STATUSES.has(result.status)) {
-            break;
-          }
-        } catch (error) {
-          consecutiveErrors++;
-          lastError = error instanceof Error ? error.message : String(error);
-          if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
-            finalResult.error = `Polling aborted after ${MAX_CONSECUTIVE_ERRORS} consecutive errors: ${lastError}`;
-            break;
-          }
-        }
-        if (Date.now() - startTime > MAX_POLL_TIME_MS) {
-          finalResult.pollingTimedOut = true;
-          finalResult.note = "Polling timed out after 5 minutes. Use get-job-status to check the job later.";
-          if (lastError) finalResult.lastError = lastError;
-          break;
-        }
-        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
-      }
-      return jsonReply2({ ...finalResult, stream: allChunks });
+      const plan = streamPollPlan(hosted);
+      const streamPath = `/stream/${params.jobId}${plan.query}`;
+      const { result, chunks } = await collectJobStream({
+        budgetMs: plan.budgetMs,
+        holdMs: plan.holdMs,
+        poll: (timeoutMs) => serverlessRequest(params.endpointId, streamPath, "GET", void 0, {
+          timeoutMs
+        })
+      });
+      return jsonReply2({ ...result, stream: chunks });
     }
   );
   server.tool(