@ethisyscore/extension-runtime 1.137.0 → 1.139.0

package/dist/mock-host/cli.cjs

@@ -145,6 +145,157 @@ function classifyHostError(err) {
   return "internal";
 }
 
+// src/plugin/pluginStorageUpload.ts
+var PLUGIN_STORAGE_UPLOAD_MAX_BYTES = 30 * 1024 * 1024;
+var PLUGIN_STORAGE_PREFIX_MAX_LENGTH = 84;
+var PLUGIN_STORAGE_PATH_MAX_LENGTH = 128;
+var PluginStorageUploadError = class extends McpToolError {
+  /** What went wrong, in terms a caller branches on. */
+  reason;
+  /** HTTP status from the server, when the host surfaced one. */
+  status;
+  /**
+   * Seconds the server asked the caller to wait (`Retry-After`), on a `rate_limited` failure
+   * when the host forwarded the header. Absent otherwise.
+   */
+  retryAfterSeconds;
+  /** Structural marker for {@link isPluginStorageUploadError}. */
+  isPluginStorageUploadError = true;
+  constructor(message, reason, options = {}) {
+    super(message, options.code ?? codeForReason(reason, options.status));
+    this.name = "PluginStorageUploadError";
+    this.reason = reason;
+    this.status = options.status;
+    if (options.retryAfterSeconds !== void 0) {
+      this.retryAfterSeconds = options.retryAfterSeconds;
+    }
+  }
+};
+function parsePluginStorageRetryAfter(raw, nowMs = Date.now()) {
+  if (typeof raw === "number") {
+    return Number.isFinite(raw) && raw >= 0 ? Math.ceil(raw) : void 0;
+  }
+  if (typeof raw !== "string" || raw.trim().length === 0) {
+    return void 0;
+  }
+  const text = raw.trim();
+  if (/^\d+$/.test(text)) {
+    return Number(text);
+  }
+  const at = /[A-Za-z]/.test(text) ? Date.parse(text) : Number.NaN;
+  return Number.isNaN(at) ? void 0 : Math.max(0, Math.ceil((at - nowMs) / 1e3));
+}
+function validatePluginStoragePrefix(raw) {
+  if (typeof raw !== "string" || raw.trim().length === 0) {
+    return { ok: false, error: "A storage path prefix is required." };
+  }
+  if (raw.length > PLUGIN_STORAGE_PREFIX_MAX_LENGTH) {
+    return {
+      ok: false,
+      error: `The storage path prefix must be at most ${PLUGIN_STORAGE_PREFIX_MAX_LENGTH} characters, so the stored path fits ${PLUGIN_STORAGE_PATH_MAX_LENGTH}.`
+    };
+  }
+  if (!/^[A-Za-z0-9_\-/]+$/.test(raw)) {
+    return {
+      ok: false,
+      error: "The storage path prefix may contain only letters, digits, '-', '_' and '/' separators."
+    };
+  }
+  if (raw.split("/").some((segment) => segment.length === 0)) {
+    return {
+      ok: false,
+      error: "The storage path prefix must not start or end with '/' or contain an empty segment."
+    };
+  }
+  return { ok: true, prefix: raw };
+}
+var PLUGIN_STORAGE_UPLOAD_CONTENT_TYPES = Object.freeze({
+  pdf: ["application/pdf"],
+  png: ["image/png"],
+  jpg: ["image/jpeg", "image/pjpeg", "image/jpg"],
+  jpeg: ["image/jpeg", "image/pjpeg", "image/jpg"],
+  gif: ["image/gif"],
+  webp: ["image/webp"],
+  doc: ["application/msword"],
+  docx: ["application/vnd.openxmlformats-officedocument.wordprocessingml.document"],
+  xls: ["application/vnd.ms-excel"],
+  xlsx: ["application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"],
+  ppt: ["application/vnd.ms-powerpoint"],
+  pptx: ["application/vnd.openxmlformats-officedocument.presentationml.presentation"],
+  odt: ["application/vnd.oasis.opendocument.text"],
+  ods: ["application/vnd.oasis.opendocument.spreadsheet"],
+  odp: ["application/vnd.oasis.opendocument.presentation"],
+  txt: ["text/plain"],
+  csv: ["text/csv", "application/vnd.ms-excel", "application/csv", "text/plain"],
+  zip: ["application/zip", "application/x-zip-compressed", "application/x-zip"],
+  mp3: ["audio/mpeg", "audio/mp3"],
+  m4a: ["audio/mp4", "audio/x-m4a"],
+  mp4: ["video/mp4"]
+});
+var OCTET_STREAM = "application/octet-stream";
+function pluginStorageSafeExtension(fileName) {
+  if (typeof fileName !== "string" || fileName.trim().length === 0) {
+    return "";
+  }
+  const leaf = fileName.split(/[\\/]/).pop() ?? "";
+  const dot = leaf.lastIndexOf(".");
+  if (dot < 0) {
+    return "";
+  }
+  const body = leaf.slice(dot + 1);
+  return /^[A-Za-z0-9]{1,10}$/.test(body) ? `.${body.toLowerCase()}` : "";
+}
+function resolvePluginStorageContentType(fileName, declaredContentType) {
+  const extension = pluginStorageSafeExtension(fileName).slice(1);
+  const allowed = extension.length > 0 && Object.prototype.hasOwnProperty.call(PLUGIN_STORAGE_UPLOAD_CONTENT_TYPES, extension) ? PLUGIN_STORAGE_UPLOAD_CONTENT_TYPES[extension] : void 0;
+  if (allowed === void 0) {
+    return {
+      ok: false,
+      error: "This file type is not allowed. Allowed: " + Object.keys(PLUGIN_STORAGE_UPLOAD_CONTENT_TYPES).sort().join(", ") + "."
+    };
+  }
+  const declared = mediaTypeOf(declaredContentType);
+  if (declared === void 0 || declared === OCTET_STREAM || allowed.includes(declared)) {
+    return { ok: true, contentType: allowed[0] };
+  }
+  return {
+    ok: false,
+    error: `The declared content type '${declared}' does not match the file extension '.${extension}'.`
+  };
+}
+function mediaTypeOf(raw) {
+  if (typeof raw !== "string") {
+    return void 0;
+  }
+  const mediaType = raw.split(";")[0].trim().toLowerCase();
+  return /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/.test(mediaType) ? mediaType : void 0;
+}
+function codeForReason(reason, status) {
+  if (status !== void 0) {
+    return mcpErrorCodeFromHttpStatus(status);
+  }
+  switch (reason) {
+    case "invalid_prefix":
+    case "too_large":
+    case "unsupported_type":
+      return "invalid_request";
+    case "timeout":
+      return "timeout";
+    case "unauthorized":
+      return "unauthorized";
+    case "forbidden":
+      return "forbidden";
+    case "busy":
+      return "unavailable";
+    case "rate_limited":
+      return "rate_limited";
+    case "aborted":
+      return "timeout";
+    default:
+      return "internal";
+  }
+}
+
 // src/host/version-skew.ts
 var EXTENSION_VERSION_HEADER = "x-extension-version";
 var EXTENSION_ACTIVE_VERSION_HEADER = "x-extension-active-version";
@@ -729,7 +880,10 @@ var WorkerRemoteDomTransport = class {
         // The HTTP status, on failure only. A bare number carries no host internals, and it
         // is the only way the plugin can tell 413 (file too large) from 507 (quota) from 503
         // (storage lock busy): the closed MCP code folds all three into `internal`/`unavailable`.
-        ...!result.ok && typeof result.status === "number" ? { status: result.status } : {}
+        ...!result.ok && typeof result.status === "number" ? { status: result.status } : {},
+        // The server's `Retry-After` (429), as whole seconds, so a plugin can show how long
+        // to wait. Never acted on here: an upload is not retried automatically.
+        ...retryAfterField(result)
       });
     } catch (err) {
       this.replyError(message.id, resultType, err, true);
@@ -738,16 +892,26 @@ var WorkerRemoteDomTransport = class {
   replyError(id, type, err, includeStatus = false) {
     const message = err instanceof Error ? err.message : "MCP request failed";
     const status = includeStatus ? statusOf(err) : void 0;
+    const retryAfterSeconds = includeStatus && err !== null && typeof err === "object" ? parsePluginStorageRetryAfter(err.retryAfterSeconds) : void 0;
     this.safePostMessage({
       id,
       type,
       ok: false,
       error: message,
       code: classifyHostError(err),
-      ...status !== void 0 ? { status } : {}
+      ...status !== void 0 ? { status } : {},
+      ...retryAfterSeconds !== void 0 ? { retryAfterSeconds } : {}
     });
   }
 };
+function retryAfterField(result) {
+  if (result.ok || !result.headers) {
+    return {};
+  }
+  const key = Object.keys(result.headers).find((k) => k.toLowerCase() === "retry-after");
+  const seconds = key === void 0 ? void 0 : parsePluginStorageRetryAfter(result.headers[key]);
+  return seconds === void 0 ? {} : { retryAfterSeconds: seconds };
+}
 function statusOf(err) {
   if (err === null || typeof err !== "object") {
     return void 0;
@@ -778,138 +942,20 @@ var CONTRACT_B_PRIMITIVES = [
 ];
 new Set(CONTRACT_B_PRIMITIVES);
 
-// src/plugin/pluginStorageUpload.ts
-var PLUGIN_STORAGE_UPLOAD_MAX_BYTES = 30 * 1024 * 1024;
-var PLUGIN_STORAGE_PREFIX_MAX_LENGTH = 84;
-var PLUGIN_STORAGE_PATH_MAX_LENGTH = 128;
-var PluginStorageUploadError = class extends McpToolError {
-  /** What went wrong, in terms a caller branches on. */
-  reason;
-  /** HTTP status from the server, when the host surfaced one. */
-  status;
-  /** Structural marker for {@link isPluginStorageUploadError}. */
-  isPluginStorageUploadError = true;
-  constructor(message, reason, options = {}) {
-    super(message, options.code ?? codeForReason(reason, options.status));
-    this.name = "PluginStorageUploadError";
-    this.reason = reason;
-    this.status = options.status;
-  }
-};
-function validatePluginStoragePrefix(raw) {
-  if (typeof raw !== "string" || raw.trim().length === 0) {
-    return { ok: false, error: "A storage path prefix is required." };
-  }
-  if (raw.length > PLUGIN_STORAGE_PREFIX_MAX_LENGTH) {
-    return {
-      ok: false,
-      error: `The storage path prefix must be at most ${PLUGIN_STORAGE_PREFIX_MAX_LENGTH} characters, so the stored path fits ${PLUGIN_STORAGE_PATH_MAX_LENGTH}.`
-    };
-  }
-  if (!/^[A-Za-z0-9_\-/]+$/.test(raw)) {
-    return {
-      ok: false,
-      error: "The storage path prefix may contain only letters, digits, '-', '_' and '/' separators."
-    };
-  }
-  if (raw.split("/").some((segment) => segment.length === 0)) {
-    return {
-      ok: false,
-      error: "The storage path prefix must not start or end with '/' or contain an empty segment."
-    };
-  }
-  return { ok: true, prefix: raw };
-}
-var PLUGIN_STORAGE_UPLOAD_CONTENT_TYPES = Object.freeze({
-  pdf: ["application/pdf"],
-  png: ["image/png"],
-  jpg: ["image/jpeg", "image/pjpeg", "image/jpg"],
-  jpeg: ["image/jpeg", "image/pjpeg", "image/jpg"],
-  gif: ["image/gif"],
-  webp: ["image/webp"],
-  doc: ["application/msword"],
-  docx: ["application/vnd.openxmlformats-officedocument.wordprocessingml.document"],
-  xls: ["application/vnd.ms-excel"],
-  xlsx: ["application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"],
-  ppt: ["application/vnd.ms-powerpoint"],
-  pptx: ["application/vnd.openxmlformats-officedocument.presentationml.presentation"],
-  odt: ["application/vnd.oasis.opendocument.text"],
-  ods: ["application/vnd.oasis.opendocument.spreadsheet"],
-  odp: ["application/vnd.oasis.opendocument.presentation"],
-  txt: ["text/plain"],
-  csv: ["text/csv", "application/vnd.ms-excel", "application/csv", "text/plain"],
-  zip: ["application/zip", "application/x-zip-compressed", "application/x-zip"],
-  mp3: ["audio/mpeg", "audio/mp3"],
-  m4a: ["audio/mp4", "audio/x-m4a"],
-  mp4: ["video/mp4"]
-});
-var OCTET_STREAM = "application/octet-stream";
-function pluginStorageSafeExtension(fileName) {
-  if (typeof fileName !== "string" || fileName.trim().length === 0) {
-    return "";
-  }
-  const leaf = fileName.split(/[\\/]/).pop() ?? "";
-  const dot = leaf.lastIndexOf(".");
-  if (dot < 0) {
-    return "";
-  }
-  const body = leaf.slice(dot + 1);
-  return /^[A-Za-z0-9]{1,10}$/.test(body) ? `.${body.toLowerCase()}` : "";
-}
-function resolvePluginStorageContentType(fileName, declaredContentType) {
-  const extension = pluginStorageSafeExtension(fileName).slice(1);
-  const allowed = extension.length > 0 && Object.prototype.hasOwnProperty.call(PLUGIN_STORAGE_UPLOAD_CONTENT_TYPES, extension) ? PLUGIN_STORAGE_UPLOAD_CONTENT_TYPES[extension] : void 0;
-  if (allowed === void 0) {
-    return {
-      ok: false,
-      error: "This file type is not allowed. Allowed: " + Object.keys(PLUGIN_STORAGE_UPLOAD_CONTENT_TYPES).sort().join(", ") + "."
-    };
-  }
-  const declared = mediaTypeOf(declaredContentType);
-  if (declared === void 0 || declared === OCTET_STREAM || allowed.includes(declared)) {
-    return { ok: true, contentType: allowed[0] };
-  }
-  return {
-    ok: false,
-    error: `The declared content type '${declared}' does not match the file extension '.${extension}'.`
-  };
-}
-function mediaTypeOf(raw) {
-  if (typeof raw !== "string") {
-    return void 0;
-  }
-  const mediaType = raw.split(";")[0].trim().toLowerCase();
-  return /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/.test(mediaType) ? mediaType : void 0;
-}
-function codeForReason(reason, status) {
-  if (status !== void 0) {
-    return mcpErrorCodeFromHttpStatus(status);
-  }
-  switch (reason) {
-    case "invalid_prefix":
-    case "too_large":
-    case "unsupported_type":
-      return "invalid_request";
-    case "timeout":
-      return "timeout";
-    case "unauthorized":
-      return "unauthorized";
-    case "forbidden":
-      return "forbidden";
-    case "busy":
-      return "unavailable";
-    case "aborted":
-      return "timeout";
-    default:
-      return "internal";
-  }
-}
-
 // src/mock-host/MockPluginStorage.ts
 var MockPluginStorage = class {
   files = /* @__PURE__ */ new Map();
+  rateLimit;
+  now;
+  windowStartMs = 0;
+  windowCount = 0;
+  constructor(options = {}) {
+    this.rateLimit = options.rateLimit;
+    this.now = options.now ?? Date.now;
+  }
   /** Store `buffer` under a new path below `meta.pathPrefix`. */
   store(meta, buffer) {
+    this.enforceRateLimit();
     const prefix = validatePluginStoragePrefix(meta.pathPrefix);
     if (!prefix.ok) {
       throw new PluginStorageUploadError(prefix.error, "invalid_prefix", { status: 400 });
@@ -931,6 +977,27 @@ var MockPluginStorage = class {
     this.files.set(path2, { path: path2, fileName, contentType: type.contentType, bytes });
     return { path: path2, fileName, contentType: type.contentType, sizeBytes: bytes.byteLength };
   }
+  /** The kernel refuses before the handler runs, so this is checked before anything else. */
+  enforceRateLimit() {
+    if (this.rateLimit === void 0) {
+      return;
+    }
+    const windowMs = (this.rateLimit.windowSeconds ?? 60) * 1e3;
+    const now = this.now();
+    if (this.windowCount === 0 || now - this.windowStartMs >= windowMs) {
+      this.windowStartMs = now;
+      this.windowCount = 0;
+    }
+    this.windowCount += 1;
+    if (this.windowCount > this.rateLimit.maxRequests) {
+      const retryAfterSeconds = Math.max(1, Math.ceil((this.windowStartMs + windowMs - now) / 1e3));
+      throw new PluginStorageUploadError(
+        "Rate limit exceeded. Please try again later.",
+        "rate_limited",
+        { status: 429, retryAfterSeconds }
+      );
+    }
+  }
   /** The stored file at `path`, or `undefined`. */
   get(path2) {
     return this.files.get(path2);