@runpod/mcp-server 4.10.0 → 4.11.0

package/dist/stdio.mjs

@@ -12,7 +12,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 
 // src/server.ts
 var SERVER_NAME = "Runpod API Server";
-var SERVER_VERSION = true ? "4.10.0" : "dev";
+var SERVER_VERSION = true ? "4.11.0" : "dev";
 
 // src/specgen/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -219,6 +219,14 @@ function validateArguments(inputSchema, args) {
   }
   return null;
 }
+function withoutNullOptionals(inputSchema, args) {
+  const required = new Set(inputSchema.required ?? []);
+  return Object.fromEntries(
+    Object.entries(args).filter(
+      ([name, value]) => value !== null || required.has(name)
+    )
+  );
+}
 async function dispatchGeneratedTool(client, tool, args) {
   const rejected = validateArguments(tool.inputSchema, args);
   if (rejected) return rejected;
@@ -236,25 +244,16 @@ async function dispatchGeneratedTool(client, tool, args) {
     const value = args[param.name];
     query[param.name] = param.explode === false && Array.isArray(value) ? value.join(",") : value;
   }
-  let requestBody = args.body;
-  if (tool.hasBody && typeof requestBody === "string") {
-    try {
-      requestBody = JSON.parse(requestBody);
-    } catch {
-      return {
-        ok: false,
-        status: 400,
-        payload: {
-          error: "The body argument arrived as a string that is not valid JSON. Send body as an object."
-        }
-      };
-    }
-  }
-  if (tool.hasBody && requestBody !== void 0) {
-    const properties = tool.inputSchema.properties ?? {};
-    const defs = tool.inputSchema.$defs ?? {};
-    requestBody = coerceScalars(requestBody, properties.body, defs);
-  }
+  const sent = tool.hasBody ? bodyAsSent(tool, args.body) : { body: args.body };
+  if (!sent)
+    return {
+      ok: false,
+      status: 400,
+      payload: {
+        error: "The body argument arrived as a string that is not valid JSON. Send body as an object."
+      }
+    };
+  const requestBody = sent.body;
   const verbs = client;
   const { data, error, response } = await verbs[tool.method](tool.path, {
     params: { path: pathParams, query },
@@ -267,6 +266,32 @@ async function dispatchGeneratedTool(client, tool, args) {
     payload: data ?? { status: response.status }
   };
 }
+function bodyAsSent(tool, body) {
+  let parsed = body;
+  if (typeof parsed === "string") {
+    try {
+      parsed = JSON.parse(parsed);
+    } catch {
+      return null;
+    }
+  }
+  if (parsed === void 0) return { body: parsed };
+  const properties = tool.inputSchema.properties ?? {};
+  const defs = tool.inputSchema.$defs ?? {};
+  return { body: coerceScalars(parsed, properties.body, defs) };
+}
+function argsAsSent(tool, args) {
+  if (!tool.hasBody || args.body === void 0) return args;
+  const sent = bodyAsSent(tool, args.body);
+  return sent ? { ...args, body: sent.body } : null;
+}
+function omittedEmptyQueryArg(tool) {
+  const required = new Set(tool.inputSchema.required ?? []);
+  const query = new Set(
+    tool.params.filter((p) => p.location === "query").map((p) => p.name)
+  );
+  return (name, value) => query.has(name) && !required.has(name) && isEmptyValue(value);
+}
 function isEmptyValue(value) {
   return value === null || value === "" || Array.isArray(value) && !value.length;
 }
@@ -2703,6 +2728,109 @@ var generatedTools = [
       }
     }
   },
+  {
+    name: "exec-pod",
+    title: "Run a command in a Pod",
+    operationId: "execPod",
+    description: `Run one command inside a running Pod's container and get stdout, stderr and the exit code back. No SSH key, public IP or exposed port is needed. command is an argv array run without a shell: pass ["sh", "-c", "..."] for pipes, redirects, globs or &&. One call waits at most timeoutSeconds (1-25, default 20). timedOut true means the call stopped waiting, NOT that the command stopped: it keeps running in the container. For anything longer (model downloads, pip installs, builds), start it in the background and log to a file, e.g. ["sh", "-c", "nohup wget -c -O /workspace/m.safetensors URL > /tmp/dl.log 2>&1 &"], then check progress with later calls (ls -la, du -h, tail /tmp/dl.log). stdout and stderr are each capped at 1 MiB (truncated true). Right after a create, the Pod can answer 404 "Pod not found" for about 10 seconds even with the right id, then 409 while its container starts: retry in about 10 seconds, a few times at most. A Pod that is not running answers 409. A host not yet updated for exec answers 503. Reaches only Pods owned by the API key's own account. Commands can change or delete data in the Pod: run write commands only for what the user asked.`,
+    directoryDescription: "Run one command inside a running Pod's container and return stdout, stderr and the exit code. The command is an argv array run without a shell. One call waits at most timeoutSeconds (1-25, default 20); a command still running then keeps running in the container, and the result says timedOut. stdout and stderr are each capped at 1 MiB. A Pod that is not running answers 409, and a host not yet updated for exec answers 503. Reaches only Pods owned by the caller's own account. The command can change or delete data in the Pod.",
+    method: "POST",
+    path: "/v2/pods/{id}/exec",
+    params: [
+      {
+        name: "id",
+        location: "path"
+      }
+    ],
+    hasBody: true,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          description: "Pod identifier"
+        },
+        body: {
+          $ref: "#/$defs/PodExecRequest",
+          type: "object"
+        }
+      },
+      required: ["id", "body"],
+      $defs: {
+        PodExecRequest: {
+          type: "object",
+          additionalProperties: false,
+          required: ["command"],
+          properties: {
+            command: {
+              type: "array",
+              minItems: 1,
+              maxItems: 256,
+              prefixItems: [
+                {
+                  type: "string",
+                  minLength: 1,
+                  maxLength: 4096,
+                  pattern: "^[^\\x00]*[^\\t-\\r \x85\xA0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000\\x00][^\\x00]*$"
+                }
+              ],
+              items: {
+                type: "string",
+                maxLength: 4096,
+                pattern: "^[^\\x00]*$"
+              },
+              description: 'Command to run, as an argv array of 1-256 arguments of at most 4096 characters each. It is run directly, never through a shell; for pipes, redirects or globbing pass `["sh", "-c", "..."]`.',
+              examples: [
+                ["nvidia-smi", "--query-gpu=name,memory.used", "--format=csv"]
+              ]
+            },
+            timeoutSeconds: {
+              type: "integer",
+              minimum: 1,
+              maximum: 25,
+              default: 20,
+              description: "How long the call waits for the command to finish, in seconds. A command still running at this point returns with `timedOut: true`.",
+              examples: [10]
+            },
+            cwd: {
+              type: "string",
+              pattern: "^/[^\\x00-\\x1f\\x7f]*$",
+              maxLength: 1024,
+              description: "Absolute working directory for the command, at most 1024 characters and without control characters. Defaults to the image's `WORKDIR`.",
+              examples: ["/workspace"]
+            },
+            env: {
+              type: "object",
+              maxProperties: 64,
+              propertyNames: {
+                type: "string",
+                minLength: 1,
+                maxLength: 256,
+                pattern: "^[^=\\x00]+$"
+              },
+              additionalProperties: {
+                type: "string",
+                maxLength: 16384,
+                pattern: "^[^\\x00]*$"
+              },
+              description: "Up to 64 environment variables added to the container's environment for this command only. A name is 1-256 characters and must not contain `=` or a NUL character; a value is at most 16384 characters and must not contain a NUL character.",
+              examples: [
+                {
+                  HF_HOME: "/workspace/hf"
+                }
+              ]
+            }
+          }
+        }
+      }
+    }
+  },
   {
     name: "get-cluster",
     title: "Get cluster",
@@ -6765,6 +6893,122 @@ var generatedTools = [
   }
 ];
 
+// src/specgen/validate.ts
+import { Ajv2020 } from "ajv/dist/2020.js";
+function schemaValidationMode(value = process.env.MCP_SCHEMA_VALIDATION) {
+  const mode = value?.trim().toLowerCase();
+  return mode === "off" || mode === "enforce" ? mode : "shadow";
+}
+var ajv = new Ajv2020({
+  strict: false,
+  allErrors: true,
+  validateFormats: false
+});
+var compiled = /* @__PURE__ */ new WeakMap();
+function validatorFor(schema) {
+  let validate = compiled.get(schema);
+  if (!validate) {
+    validate = ajv.compile(structuredClone(schema));
+    compiled.set(schema, validate);
+  }
+  return validate;
+}
+var MAX_NULL_PASSES = 8;
+function isNullTypeError(error, data) {
+  return error.keyword === "type" && error.instancePath !== "" && valueAt(data, error.instancePath) === null;
+}
+function pointerSegments(pointer) {
+  return pointer.split("/").slice(1).map((s) => s.replace(/~1/g, "/").replace(/~0/g, "~"));
+}
+function valueAt(data, pointer) {
+  let node = data;
+  for (const key of pointerSegments(pointer)) {
+    if (node === null || typeof node !== "object") return void 0;
+    node = node[key];
+  }
+  return node;
+}
+function removeAt(data, pointer) {
+  const segments = pointerSegments(pointer);
+  const last = segments.pop();
+  const parent = valueAt(data, segments.length ? `/${segments.join("/")}` : "");
+  if (last === void 0 || parent === null || typeof parent !== "object")
+    return false;
+  if (Array.isArray(parent)) return false;
+  delete parent[last];
+  return true;
+}
+var WRAPPER_KEYWORDS = /* @__PURE__ */ new Set(["if"]);
+function toViolation(error) {
+  const base = pointerSegments(error.instancePath);
+  let path = base.join(".");
+  let message = error.message ?? "is invalid";
+  const params = error.params;
+  if (error.keyword === "required" && typeof params.missingProperty === "string") {
+    path = [...base, params.missingProperty].join(".");
+    message = "is required";
+  } else if (error.keyword === "additionalProperties" && typeof params.additionalProperty === "string") {
+    path = [...base, params.additionalProperty].join(".");
+    message = "is not an accepted argument here";
+  } else if (error.keyword === "pattern") {
+    message = "is not in an accepted format";
+  }
+  const allowed = error.keyword === "enum" ? params.allowedValues : error.keyword === "const" ? [params.allowedValue] : void 0;
+  return {
+    path,
+    keyword: error.keyword,
+    message,
+    ...allowed ? { allowed } : {},
+    schemaPath: error.schemaPath
+  };
+}
+function schemaViolations(schema, args, omitted = () => false) {
+  const validate = validatorFor(schema);
+  const data = structuredClone(
+    Object.fromEntries(
+      Object.entries(args).filter(([name, value]) => !omitted(name, value))
+    )
+  );
+  for (let pass = 0; ; pass++) {
+    if (validate(data)) return [];
+    const errors = validate.errors ?? [];
+    let removed = false;
+    if (pass < MAX_NULL_PASSES) {
+      for (const error of errors.filter((e) => isNullTypeError(e, data)))
+        removed = removeAt(data, error.instancePath) || removed;
+    }
+    if (!removed) {
+      return errors.filter((e) => !WRAPPER_KEYWORDS.has(e.keyword)).map(toViolation);
+    }
+  }
+}
+var INVALID_ARGUMENTS_HINT = "Fix the listed fields and call again.";
+function invalidArgumentsPayload(violations) {
+  return {
+    error: "Invalid arguments",
+    code: "invalid_arguments",
+    fields: violations.map(({ path, message, allowed }) => ({
+      path,
+      problem: message,
+      ...allowed ? { allowed } : {}
+    })),
+    hint: INVALID_ARGUMENTS_HINT
+  };
+}
+function logSchemaViolations(tool, mode, violations) {
+  console.error(
+    "schema_violation",
+    JSON.stringify({
+      tool,
+      mode,
+      violations: violations.map(({ keyword, schemaPath }) => ({
+        keyword,
+        schemaPath
+      }))
+    })
+  );
+}
+
 // src/specgen/tools/annotations.ts
 var readOnly = {
   readOnlyHint: true,
@@ -6978,6 +7222,8 @@ var DIRECTORY_TOOLS = {
   "deploy-hub-repo": IN,
   "detach-cost-center-resource": IN,
   "endpoint-health": IN,
+  // env can carry tokens (HF_TOKEN for a model download), so the directory omits it.
+  "exec-pod": { include: true, omitInputs: ["body.env"] },
   "get-capacity": IN,
   "get-cluster": IN,
   "get-cost-center": IN,
@@ -7097,6 +7343,21 @@ function directoryOmittedInputs(name) {
   const decision = DIRECTORY_TOOLS[name];
   return decision?.include ? decision.omitInputs ?? [] : [];
 }
+function omittedInputsIn(omit, args) {
+  return omit.filter((key) => {
+    const [parent, child] = key.split(".");
+    if (child === void 0) return parent in args;
+    let value = args[parent];
+    if (typeof value === "string") {
+      try {
+        value = JSON.parse(value);
+      } catch {
+        return false;
+      }
+    }
+    return !!value && typeof value === "object" && child in value;
+  });
+}
 
 // src/specgen/redact.ts
 var REDACTED = "[redacted]";
@@ -9848,23 +10109,40 @@ function createRunpodClient(options = {}) {
 // src/specgen/clients/sse.ts
 var LOG_STREAM_DEFAULT_WAIT_MS = 5e3;
 var LOG_STREAM_MAX_BYTES = 256 * 1024;
+var LOG_STREAM_CONNECT_TIMEOUT_MS = 1e4;
+var LOG_SNAPSHOT_MAX_CHARS = 32e3;
 function createSseReader(options = {}) {
   const apiKey = options.apiKey ?? process.env.RUNPOD_API_KEY;
   const fetchImpl = options.fetchImpl ?? fetch;
+  const connectTimeoutMs = options.connectTimeoutMs ?? LOG_STREAM_CONNECT_TIMEOUT_MS;
   return async (url, opts) => {
     if (!apiKey) throw missingKeyError();
     const chunks = [];
     let bytes = 0;
     let truncated = false;
     let streamEstablished = false;
+    const connect = new AbortController();
+    const connectTimer = setTimeout(
+      () => connect.abort(
+        new DOMException(
+          `Runpod log stream sent no headers within ${connectTimeoutMs}ms`,
+          "TimeoutError"
+        )
+      ),
+      connectTimeoutMs
+    );
     try {
-      const response = await createDeadlineFetch(fetchImpl, opts.maxWaitMs)(url, {
+      const response = await createDeadlineFetch(
+        fetchImpl,
+        connectTimeoutMs + opts.maxWaitMs
+      )(url, {
         method: "GET",
         headers: {
           Authorization: `Bearer ${apiKey}`,
           Accept: "text/event-stream"
-        }
-      });
+        },
+        signal: connect.signal
+      }).finally(() => clearTimeout(connectTimer));
       if (!response.ok) {
         const body = await response.text().catch(() => "");
         throw new HttpError(
@@ -9875,14 +10153,31 @@ function createSseReader(options = {}) {
       }
       streamEstablished = true;
       if (response.body) {
-        for await (const chunk of response.body) {
-          const boundedChunk = chunk.subarray(0, opts.maxBytes - bytes);
-          chunks.push(boundedChunk);
-          bytes += boundedChunk.length;
-          if (bytes >= opts.maxBytes) {
-            truncated = true;
-            break;
+        const reader = response.body.getReader();
+        let timer;
+        const windowClosed = new Promise((resolve) => {
+          timer = setTimeout(() => resolve(null), opts.maxWaitMs);
+        });
+        try {
+          for (; ; ) {
+            const read = reader.read();
+            read.catch(() => {
+            });
+            const next = await Promise.race([read, windowClosed]);
+            if (next === null || next.done) break;
+            const boundedChunk = next.value.subarray(0, opts.maxBytes - bytes);
+            chunks.push(boundedChunk);
+            bytes += boundedChunk.length;
+            if (bytes >= opts.maxBytes) {
+              truncated = true;
+              break;
+            }
           }
+        } finally {
+          clearTimeout(timer);
+          void reader.cancel().catch(() => {
+          });
+          reader.releaseLock();
         }
       }
     } catch (err) {
@@ -9908,7 +10203,80 @@ async function collectLogSnapshot(reader, logsUrl, params) {
   for await (const event of iterateLogEvents(new Response(raw).body)) {
     items.push(event.data);
   }
-  return { items, count: items.length, truncated };
+  return fitSnapshot(items, truncated);
+}
+var serializedLength = (snapshot) => JSON.stringify(snapshot, null, 2).length;
+var LOG_ENTRY_MAX_CHARS = 16e3;
+var CLIPPABLE_KEYS = ["line", "raw"];
+function clipText(text, keep) {
+  const code = text.charCodeAt(keep - 1);
+  if (keep > 0 && code >= 55296 && code <= 56319) keep--;
+  return `${text.slice(0, keep)}\u2026 [clipped ${text.length - keep} chars]`;
+}
+function clipEntry(entry) {
+  let clipped = false;
+  const out = { ...entry };
+  for (const key of CLIPPABLE_KEYS) {
+    const text = out[key];
+    if (typeof text === "string" && text.length > LOG_ENTRY_MAX_CHARS) {
+      out[key] = clipText(text, LOG_ENTRY_MAX_CHARS);
+      clipped = true;
+    }
+  }
+  return { entry: out, clipped };
+}
+function fitEntry(entry, maxChars) {
+  const size = (e) => serializedLength({ items: [e], count: 1, truncated: false });
+  const out = { ...entry };
+  const keys = Object.keys(out).filter((key) => key !== "ts" && typeof out[key] === "string").sort((a, b) => out[b].length - out[a].length);
+  for (const key of keys) {
+    if (size(out) <= maxChars) break;
+    const text = entry[key];
+    let lo = 0;
+    let hi = Math.min(text.length, LOG_ENTRY_MAX_CHARS);
+    while (lo < hi) {
+      const mid = Math.ceil((lo + hi) / 2);
+      if (size({ ...out, [key]: clipText(text, mid) }) <= maxChars)
+        lo = mid;
+      else hi = mid - 1;
+    }
+    out[key] = clipText(text, lo);
+  }
+  return out;
+}
+var entryTs = (entry) => entry?.ts;
+function fitSnapshot(items, truncated, maxChars = LOG_SNAPSHOT_MAX_CHARS) {
+  let cut = truncated;
+  const entries = items.map((item) => {
+    const { entry, clipped } = clipEntry(item);
+    if (clipped) cut = true;
+    return entry;
+  });
+  const snapshot = (n, isCut) => ({
+    items: entries.slice(0, n),
+    count: n,
+    truncated: isCut
+  });
+  const whole = snapshot(entries.length, cut);
+  if (entries.length === 0 || serializedLength(whole) <= maxChars) return whole;
+  if (serializedLength(snapshot(1, true)) > maxChars) {
+    entries[0] = fitEntry(items[0], maxChars);
+    if (entries.length === 1) return snapshot(1, true);
+  }
+  let lo = 1;
+  let hi = entries.length - 1;
+  while (lo < hi) {
+    const mid = Math.ceil((lo + hi) / 2);
+    if (serializedLength(snapshot(mid, true)) <= maxChars) lo = mid;
+    else hi = mid - 1;
+  }
+  let keep = lo;
+  const omittedTs = entryTs(entries[keep]);
+  if (omittedTs !== void 0) {
+    while (keep > 0 && entryTs(entries[keep - 1]) === omittedTs) keep--;
+    if (keep === 0) keep = lo;
+  }
+  return snapshot(keep, true);
 }
 
 // src/specgen/tools/logs.ts
@@ -9926,13 +10294,13 @@ var logStreamProperties = {
   },
   since: {
     type: "string",
-    description: "RFC3339 timestamp to resume from; when set, `tail` is ignored."
+    description: "RFC3339 timestamp to resume after (exclusive). Replays container lines only; system lines stream live from the call. When set, `tail` is ignored."
   },
   maxWaitMs: {
     type: "integer",
     minimum: 500,
     maximum: 3e4,
-    description: "How long to read the stream, in ms (default 5000, max 30000)"
+    description: "How long to read the stream once it opens, in ms (default 5000, max 30000)"
   }
 };
 function baseUrl() {
@@ -9958,7 +10326,7 @@ var streamPodLogs = {
   title: "Stream Pod logs",
   holdsResponse: true,
   annotations: readOnly,
-  description: "Read a bounded snapshot of a Pod's logs (container and/or system source). Holds the live stream open for maxWaitMs and returns the parsed log lines; `truncated: true` means the byte cap cut the output. Use `since` to resume from a timestamp.",
+  description: "Read a bounded snapshot of a Pod's logs (container and/or system source). Holds the live stream open for maxWaitMs and returns the parsed log lines; `truncated: true` means the size cap cut the output. For later container lines, call again with `since` set to the last container line's `ts`; `since` does not replay system lines, so for those request a smaller `tail`.",
   inputSchema: {
     type: "object",
     properties: {
@@ -9980,10 +10348,10 @@ var streamPodLogs = {
 var streamWorkerLogs = {
   name: "stream-worker-logs",
   title: "Stream worker logs",
-  directoryDescription: "Read a bounded snapshot of a Serverless worker's logs (container, system, or both). Holds the live stream open for maxWaitMs and returns the parsed log lines; truncated: true means the byte cap cut the output. A worker whose container keeps failing to start can report RUNNING or THROTTLED while its logs show the failure.",
+  directoryDescription: "Read a bounded snapshot of a Serverless worker's logs (container, system, or both). Holds the live stream open for maxWaitMs and returns the parsed log lines; truncated: true means the size cap cut the output. A worker whose container keeps failing to start can report RUNNING or THROTTLED while its logs show the failure.",
   holdsResponse: true,
   annotations: readOnly,
-  description: "Read a bounded snapshot of a Serverless worker's logs (container and/or system source). Holds the live stream open for maxWaitMs and returns the parsed log lines; `truncated: true` means the byte cap cut the output. Get worker IDs from list-endpoint-workers. Use this whenever a job stays IN_QUEUE while workers exist, whatever status they report \u2014 a crash-looping container often still shows RUNNING or THROTTLED with unhealthy 0, so these logs, not the worker status, are what identify a crash loop.",
+  description: "Read a bounded snapshot of a Serverless worker's logs (container and/or system source). Holds the live stream open for maxWaitMs and returns the parsed log lines; `truncated: true` means the size cap cut the output. For later container lines, call again with `since` set to the last container line's `ts`; `since` does not replay system lines, so for those request a smaller `tail`. Get worker IDs from list-endpoint-workers. Use this whenever a job stays IN_QUEUE while workers exist, whatever status they report \u2014 a crash-looping container often still shows RUNNING or THROTTLED with unhealthy 0, so these logs, not the worker status, are what identify a crash loop.",
   inputSchema: {
     type: "object",
     properties: {
@@ -10129,6 +10497,7 @@ import {
   loadKnowledge
 } from "@runpod/plugin-knowledge";
 var knowledge = loadKnowledge();
+var resolveGuideId = (id) => knowledge.aliases?.[id] ?? id;
 var hiddenRules = new Set(
   (process.env.KNOWLEDGE_HIDDEN_RULES ?? "").split(",").map((id) => id.trim()).filter(Boolean)
 );
@@ -10305,7 +10674,9 @@ var readGuide = {
   title: "Read guide",
   annotations: bundledRead,
   recordedArguments: ["id"],
-  recordedGuideKind: (args) => knowledge.guides.find((guide) => guide.id === String(args.id).trim())?.kind,
+  recordedGuideKind: (args) => knowledge.guides.find(
+    (guide) => guide.id === resolveGuideId(String(args.id).trim())
+  )?.kind,
   description: 'Read one official Runpod guide in full, by the id list-guides returns (for example "runpod-usage/storage" or "golden-path/06-dev-pod").',
   inputSchema: {
     type: "object",
@@ -10317,7 +10688,9 @@ var readGuide = {
   },
   handler: async (_ctx, args) => {
     const id = String(args.id).trim();
-    const guide = knowledge.guides.find((candidate) => candidate.id === id);
+    const guide = knowledge.guides.find(
+      (candidate) => candidate.id === resolveGuideId(id)
+    );
     if (!guide) {
       const close = knowledge.guides.filter(
         (candidate) => candidate.id.includes(id) || id.includes(candidate.id)
@@ -10472,6 +10845,12 @@ var guideResources = knowledge.guides.map((guide) => ({
   mimeType: "text/markdown",
   text: guide.body
 }));
+var findGuideResource = (resources, uri) => {
+  const id = uri.startsWith(GUIDE_URI_PREFIX) ? resolveGuideId(uri.slice(GUIDE_URI_PREFIX.length)) : void 0;
+  return resources.find(
+    (resource) => resource.uri === uri || resource.uri === GUIDE_URI_PREFIX + id
+  );
+};
 
 // src/specgen/prose.ts
 var ABBREVIATIONS = ["e.g.", "i.e.", "etc.", "vs."];
@@ -10547,13 +10926,40 @@ function withoutCredentialExamples(schema) {
   };
   return strip(schema);
 }
-function withoutInputs(schema, omit) {
-  if (!omit.length) return schema;
+function withoutKeys(schema, omit) {
   const properties = { ...schema.properties ?? {} };
   for (const key of omit) delete properties[key];
   const required = Array.isArray(schema.required) ? schema.required.filter((key) => !omit.includes(key)) : schema.required;
   return { ...schema, properties, ...required ? { required } : {} };
 }
+function withoutInputs(schema, omit) {
+  if (!omit.length) return schema;
+  let out = withoutKeys(
+    schema,
+    omit.filter((key) => !key.includes("."))
+  );
+  for (const key of omit.filter((k) => k.includes("."))) {
+    const [parent, child] = key.split(".");
+    const properties = out.properties ?? {};
+    const node = properties[parent];
+    if (!node) continue;
+    const ref = typeof node.$ref === "string" ? node.$ref : void 0;
+    const defName = ref?.startsWith("#/$defs/") ? ref.slice(8) : void 0;
+    const defs = out.$defs ?? {};
+    if (defName && defs[defName]) {
+      out = {
+        ...out,
+        $defs: { ...defs, [defName]: withoutKeys(defs[defName], [child]) }
+      };
+    } else {
+      out = {
+        ...out,
+        properties: { ...properties, [parent]: withoutKeys(node, [child]) }
+      };
+    }
+  }
+  return out;
+}
 function callShape(schema) {
   const defs = schema.$defs ?? {};
   const resolve = (node) => {
@@ -10719,6 +11125,7 @@ function captureToolCall(apiKey, event) {
     server_version: event.serverVersion,
     ...event.clientName ? { client_name: event.clientName } : {},
     ...event.guideKind ? { guide_kind: event.guideKind } : {},
+    ...event.errorClass ? { error_class: event.errorClass } : {},
     ...event.blockedBy ? { blocked_by: event.blockedBy } : {},
     ...event.profile ? { profile: event.profile } : {},
     ...args
@@ -11496,7 +11903,7 @@ These tools manage infrastructure only. They do not do SSH sessions, file transf
 
 OFFICIAL GUIDES AND FACTS. list-guides and read-guide serve the official Runpod plugin's skills, reference docs and live-verified golden paths, so you have them even without the plugin installed. For a multi-step or billable task, look for a matching golden path first. lookup-concept and search-concepts answer exact questions about how Runpod works (what a stopped pod keeps, where a volume lives) with the public source for each fact.
 
-PLAYBOOKS \u2014 READ BEFORE ACTING. Each Runpod task has a journey playbook carrying its procedure, pitfalls and report format. Before the FIRST Runpod tool call of a session, load the plugin's runpod-mcp skill if you have it, otherwise read-guide runpod-mcp (also the runpod://guides/runpod-mcp resource): it routes the request to a journey guide \u2014 deploying an endpoint reads serverless-deploy, diagnosing a broken pod reads pod-doctor, cost questions read cost-audit, and so on \u2014 and states the answer contract. A reply produced without the routed playbook loaded is out of contract.
+PLAYBOOKS \u2014 READ BEFORE ACTING. Each Runpod task has a journey playbook carrying its procedure, pitfalls and report format. Before the FIRST Runpod tool call of a session, load the plugin's runpod-mcp skill if you have it, otherwise read-guide runpod-mcp (also the runpod://guides/runpod-mcp resource): it routes the request to a journey guide \u2014 deploying an endpoint reads runpod-serverless-deploy, diagnosing a broken pod reads runpod-pod-doctor, cost questions read runpod-cost-audit, and so on \u2014 and states the answer contract. A reply produced without the routed playbook loaded is out of contract.
 
 THE OFFICIAL RUNPOD PLUGIN. Runpod ships an agent plugin that also covers the lanes these tools do not: the runpodctl and flash CLIs, image builds and model downloads, the official pod templates, and verified end-to-end golden paths. Check once per session whether skills named runpod, runpod-usage, or runpodctl are available to you \u2014 read what you already have, never shell out to look. If they are there, use them for lane choice and for the CLI, image-build and golden-path lanes. For work done with these tools, the journey playbook is the procedure, wherever it is served from: the plugin's runpod-mcp skill and the journey skills it routes to when you have them, otherwise the same playbooks through read-guide here. If you do not see them, recommend the plugin to the user, and recommend updating to the latest if what they have is missing something you need. Point them at https://github.com/runpod/runpod-plugins-official \u2014 its README carries the install, update, and clone commands for each client, so read it yourself when you need the exact one rather than guessing a command. This is a recommendation, never a prerequisite: make it once, briefly, and get on with the task. Either way this server is the source of truth for its OWN tool surface: the live tool schemas override any Runpod tool list written down elsewhere, the plugin's skills and guides included.
 
@@ -11515,6 +11922,7 @@ function createSpecgenServer(ctx, version = "0.1.0", opts = {}) {
   const caller = callerId(ctx.apiKey);
   const profile = opts.profile ?? "default";
   const directory = profile === "directory";
+  const schemaMode = schemaValidationMode();
   const alp = directory ? void 0 : opts.alp;
   const servedGeneratedTools = directory ? generatedTools.filter((tool) => directoryIncludes(tool.name)) : generatedTools;
   const servedCuratedTools = [
@@ -11557,9 +11965,7 @@ function createSpecgenServer(ctx, version = "0.1.0", opts = {}) {
     resourceTemplates: []
   }));
   server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-    const guide = servedGuides.find(
-      (candidate) => candidate.uri === request.params.uri
-    );
+    const guide = findGuideResource(servedGuides, request.params.uri);
     if (opts.analytics) {
       captureResourceCall(ctx.apiKey, {
         method: "resources/read",
@@ -11596,6 +12002,7 @@ function createSpecgenServer(ctx, version = "0.1.0", opts = {}) {
           ok: false,
           status: 429,
           durationMs: 0,
+          errorClass: "rate_limited",
           ...verdict.reason ? { blockedBy: verdict.reason } : {},
           profile,
           ...opts.analytics
@@ -11621,7 +12028,8 @@ function createSpecgenServer(ctx, version = "0.1.0", opts = {}) {
     const generated = servedGeneratedTools.find(
       (tool) => tool.name === request.params.name
     );
-    const omitted = directory ? directoryOmittedInputs(request.params.name).filter((key) => key in args) : [];
+    const curatedArgs = curated ? withoutNullOptionals(curated.inputSchema, args) : args;
+    const omitted = directory ? omittedInputsIn(directoryOmittedInputs(request.params.name), args) : [];
     const rejected = omitted.length ? {
       ok: false,
       status: 400,
@@ -11630,10 +12038,28 @@ function createSpecgenServer(ctx, version = "0.1.0", opts = {}) {
       }
     } : curated && !curated.lenientArguments ? validateArguments(
       curated.inputSchema,
-      args
-    ) : null;
-    const result = rejected ?? await runTool(
-      () => curated ? curated.handler(ctx, args) : dispatchTool(generated, request.params.name, args)
+      curatedArgs
+    ) : generated ? validateArguments(generated.inputSchema, args) : null;
+    let schemaRejected = null;
+    if (!rejected && schemaMode !== "off") {
+      const sent = generated ? argsAsSent(generated, args) : null;
+      const violations = curated ? curated.lenientArguments ? [] : schemaViolations(curated.inputSchema, curatedArgs) : generated && sent ? schemaViolations(
+        generated.inputSchema,
+        sent,
+        omittedEmptyQueryArg(generated)
+      ) : [];
+      if (violations.length) {
+        logSchemaViolations(request.params.name, schemaMode, violations);
+        if (schemaMode === "enforce")
+          schemaRejected = {
+            ok: false,
+            status: 400,
+            payload: invalidArgumentsPayload(violations)
+          };
+      }
+    }
+    const result = rejected ?? schemaRejected ?? await runTool(
+      () => curated ? curated.handler(ctx, curatedArgs) : dispatchTool(generated, request.params.name, args)
     );
     logToolCall({
       tool: request.params.name,
@@ -11648,6 +12074,7 @@ function createSpecgenServer(ctx, version = "0.1.0", opts = {}) {
         ok: result.ok,
         status: result.status,
         durationMs: Date.now() - startedAt,
+        ...result.ok ? {} : { errorClass: errorClass(result) },
         // The directory profile records which tool ran, never what was asked.
         ...directory ? {} : {
           args: recordedArgumentValues(curated?.recordedArguments, args),
@@ -11687,24 +12114,50 @@ function createSpecgenServer(ctx, version = "0.1.0", opts = {}) {
 var SHAPE_HINT = "Input shape mismatch: check this tool's schema for required fields. For job payloads, the worker's release config defines the expected input object \u2014 fix the payload and retry; don't abandon the task.";
 var DETAIL_HINTS = [
   [
-    /no longer any instances available|not enough free GPUs/i,
-    "Capacity, not input: the request is valid but no machine can take it right now. Don't change the payload shape. Retry with another GPU type, data center, cloud, CUDA version or count, or try again later. For a stopped Pod, its host's GPUs are taken; that Pod can only start once they free up."
+    /no longer any instances available|no instances currently available|not enough free GPUs/i,
+    "Capacity, not input: the request is valid but no machine can take it right now. Don't change the payload shape. Retry with another GPU type, data center, cloud, CUDA version or count, or try again later. For a stopped Pod, its host's GPUs are taken; that Pod can only start once they free up.",
+    "capacity"
   ],
   [
     /at least \$\d|insufficient (?:funds|balance)|\bbalance\b/i,
-    "Account balance, not input: this operation needs funds on the account. Ask the user to add credit in the Runpod console; list-billing shows recent spend."
+    "Account balance, not input: this operation needs funds on the account. Ask the user to add credit in the Runpod console; list-billing shows recent spend.",
+    "balance"
   ],
   [
     /mutually exclusive|cannot be combined with/i,
-    "Two arguments conflict: send only one of them and leave the other out entirely. Do not change anything else."
+    "Two arguments conflict: send only one of them and leave the other out entirely. Do not change anything else.",
+    "conflicting_args"
+  ],
+  // A 400 with a bare "Unauthorized" detail from a write the same key can
+  // otherwise make is upstream's answer for an unfunded account.
+  [
+    /^\s*unauthorized\s*$/i,
+    "Upstream refused this write. With a key that can read, this usually means the account has no balance: ask the user to check their balance in the Runpod console before retrying.",
+    "balance"
   ]
 ];
+function errorClass(result) {
+  const { status } = result;
+  const payload = asRecord(result.payload) ?? { error: result.payload };
+  const detail = detailText(payload);
+  if (status === 400 && detail) {
+    for (const [pattern, , cls] of DETAIL_HINTS)
+      if (pattern.test(detail)) return cls;
+  }
+  if (status === 400 || status === 422) return "validation";
+  if (status === 401) return "auth";
+  if (status === 402) return "balance";
+  if (status === 403) return "permission";
+  if (status === 404) return "not_found";
+  if (status === 429) return "rate_limited";
+  if (status === 504) return "timeout";
+  if (status >= 500) return "server";
+  return "other";
+}
 function errorHint(status, detail) {
   if (status === 400 && detail) {
     for (const [pattern, hint] of DETAIL_HINTS)
       if (pattern.test(detail)) return hint;
-    if (/^unauthorized$/i.test(detail.trim()))
-      return "Upstream refused this write. With a key that can read, this usually means the account has no balance: ask the user to check their balance in the Runpod console before retrying.";
   }
   if (status === 400 || status === 422) return SHAPE_HINT;
   if (status === 401) return "The Runpod API key is missing or invalid.";