@ethisyscore/extension-runtime 1.137.0 → 1.138.0

package/dist/plugin/index.d.cts

@@ -47,13 +47,18 @@ declare const PLUGIN_STORAGE_PATH_MAX_LENGTH = 128;
  * - `unsupported_type`: the file's extension is not on the allow-list, or the declared type does
  *   not match it (client-side check, or a server 415).
  * - `timeout`: the upload was too slow or missed the server's deadline (408). Retryable.
- * - `busy`: the app's storage lock is held, or the server's upload slots are full (503). Retryable.
+ * - `busy`: the server refused the upload for capacity (503). The message says which limit: too
+ *   many uploads in progress for this user or organisation, all of the server's upload slots taken,
+ *   or another upload for this app holding the storage lock. NOT retried automatically.
+ * - `rate_limited`: the user is over the route's request rate (429, default 60 a minute).
+ *   {@link PluginStorageUploadError.retryAfterSeconds} carries the server's `Retry-After` when sent.
+ *   NOT retried automatically.
  * - `storage_failed`: the store refused the write (500).
  * - `unsupported`: the active transport has no `uploadToStorage`, i.e. the host predates it.
  * - `aborted`: the caller's signal fired.
  * - `unknown`: anything else.
  */
-type PluginStorageUploadErrorReason = "invalid_prefix" | "too_large" | "quota_exceeded" | "unauthorized" | "forbidden" | "unsupported_type" | "timeout" | "busy" | "storage_failed" | "unsupported" | "aborted" | "unknown";
+type PluginStorageUploadErrorReason = "invalid_prefix" | "too_large" | "quota_exceeded" | "unauthorized" | "forbidden" | "unsupported_type" | "timeout" | "busy" | "rate_limited" | "storage_failed" | "unsupported" | "aborted" | "unknown";
 /**
  * A failed plugin-storage upload. `message` is the server's own `{ error }` text when the server
  * answered, otherwise the client-side reason.
@@ -67,11 +72,17 @@ declare class PluginStorageUploadError extends McpToolError {
     readonly reason: PluginStorageUploadErrorReason;
     /** HTTP status from the server, when the host surfaced one. */
     readonly status?: number;
+    /**
+     * Seconds the server asked the caller to wait (`Retry-After`), on a `rate_limited` failure
+     * when the host forwarded the header. Absent otherwise.
+     */
+    readonly retryAfterSeconds?: number;
     /** Structural marker for {@link isPluginStorageUploadError}. */
     readonly isPluginStorageUploadError: true;
     constructor(message: string, reason: PluginStorageUploadErrorReason, options?: {
         status?: number;
         code?: McpErrorCode;
+        retryAfterSeconds?: number;
     });
 }
 /** True when `value` is a {@link PluginStorageUploadError}, including one from another bundle. */
@@ -170,6 +181,10 @@ interface UploadToStorageOptions {
  * {@link PluginStorageUploadError} whose `reason` is safe to branch on and whose `message` is the
  * server's when the server answered.
  *
+ * An upload is NEVER retried here, on 429, 503 or anything else: it is not idempotent (a retry
+ * after a lost response could store the file twice), and a busy or rate-limited server is only
+ * made worse by it. The caller decides, using `reason` and `retryAfterSeconds`.
+ *
  * An `ArrayBuffer` argument is transferred to the host and detached; pass a copy to keep it.
  */
 declare function uploadFileToPluginStorage(transport: McpTransport, file: File | Blob | ArrayBuffer, options: UploadToStorageOptions): Promise<UploadToStorageResult>;

package/dist/plugin/index.d.ts

@@ -47,13 +47,18 @@ declare const PLUGIN_STORAGE_PATH_MAX_LENGTH = 128;
  * - `unsupported_type`: the file's extension is not on the allow-list, or the declared type does
  *   not match it (client-side check, or a server 415).
  * - `timeout`: the upload was too slow or missed the server's deadline (408). Retryable.
- * - `busy`: the app's storage lock is held, or the server's upload slots are full (503). Retryable.
+ * - `busy`: the server refused the upload for capacity (503). The message says which limit: too
+ *   many uploads in progress for this user or organisation, all of the server's upload slots taken,
+ *   or another upload for this app holding the storage lock. NOT retried automatically.
+ * - `rate_limited`: the user is over the route's request rate (429, default 60 a minute).
+ *   {@link PluginStorageUploadError.retryAfterSeconds} carries the server's `Retry-After` when sent.
+ *   NOT retried automatically.
  * - `storage_failed`: the store refused the write (500).
  * - `unsupported`: the active transport has no `uploadToStorage`, i.e. the host predates it.
  * - `aborted`: the caller's signal fired.
  * - `unknown`: anything else.
  */
-type PluginStorageUploadErrorReason = "invalid_prefix" | "too_large" | "quota_exceeded" | "unauthorized" | "forbidden" | "unsupported_type" | "timeout" | "busy" | "storage_failed" | "unsupported" | "aborted" | "unknown";
+type PluginStorageUploadErrorReason = "invalid_prefix" | "too_large" | "quota_exceeded" | "unauthorized" | "forbidden" | "unsupported_type" | "timeout" | "busy" | "rate_limited" | "storage_failed" | "unsupported" | "aborted" | "unknown";
 /**
  * A failed plugin-storage upload. `message` is the server's own `{ error }` text when the server
  * answered, otherwise the client-side reason.
@@ -67,11 +72,17 @@ declare class PluginStorageUploadError extends McpToolError {
     readonly reason: PluginStorageUploadErrorReason;
     /** HTTP status from the server, when the host surfaced one. */
     readonly status?: number;
+    /**
+     * Seconds the server asked the caller to wait (`Retry-After`), on a `rate_limited` failure
+     * when the host forwarded the header. Absent otherwise.
+     */
+    readonly retryAfterSeconds?: number;
     /** Structural marker for {@link isPluginStorageUploadError}. */
     readonly isPluginStorageUploadError: true;
     constructor(message: string, reason: PluginStorageUploadErrorReason, options?: {
         status?: number;
         code?: McpErrorCode;
+        retryAfterSeconds?: number;
     });
 }
 /** True when `value` is a {@link PluginStorageUploadError}, including one from another bundle. */
@@ -170,6 +181,10 @@ interface UploadToStorageOptions {
  * {@link PluginStorageUploadError} whose `reason` is safe to branch on and whose `message` is the
  * server's when the server answered.
  *
+ * An upload is NEVER retried here, on 429, 503 or anything else: it is not idempotent (a retry
+ * after a lost response could store the file twice), and a busy or rate-limited server is only
+ * made worse by it. The caller decides, using `reason` and `retryAfterSeconds`.
+ *
  * An `ArrayBuffer` argument is transferred to the host and detached; pass a copy to keep it.
  */
 declare function uploadFileToPluginStorage(transport: McpTransport, file: File | Blob | ArrayBuffer, options: UploadToStorageOptions): Promise<UploadToStorageResult>;

package/dist/plugin/index.js

@@ -108,6 +108,11 @@ var PluginStorageUploadError = class extends McpToolError {
   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 = {}) {
@@ -115,6 +120,9 @@ var PluginStorageUploadError = class extends McpToolError {
     this.name = "PluginStorageUploadError";
     this.reason = reason;
     this.status = options.status;
+    if (options.retryAfterSeconds !== void 0) {
+      this.retryAfterSeconds = options.retryAfterSeconds;
+    }
   }
 };
 function isPluginStorageUploadError(value) {
@@ -134,6 +142,8 @@ function pluginStorageUploadReasonFromStatus(status) {
       return "timeout";
     case 415:
       return "unsupported_type";
+    case 429:
+      return "rate_limited";
     case 503:
       return "busy";
     case 507:
@@ -144,6 +154,20 @@ function pluginStorageUploadReasonFromStatus(status) {
       return "unknown";
   }
 }
+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 toPluginStorageUploadError(err) {
   if (isPluginStorageUploadError(err)) {
     return err;
@@ -152,7 +176,10 @@ function toPluginStorageUploadError(err) {
   const candidate = err !== null && typeof err === "object" ? err : {};
   const status = typeof candidate.status === "number" ? candidate.status : typeof candidate.statusCode === "number" ? candidate.statusCode : void 0;
   if (status !== void 0) {
-    return new PluginStorageUploadError(message, pluginStorageUploadReasonFromStatus(status), { status });
+    return new PluginStorageUploadError(message, pluginStorageUploadReasonFromStatus(status), {
+      status,
+      retryAfterSeconds: parsePluginStorageRetryAfter(candidate.retryAfterSeconds)
+    });
   }
   if (candidate.name === "AbortError") {
     return new PluginStorageUploadError(message, "aborted", { code: "timeout" });
@@ -328,6 +355,8 @@ function codeForReason(reason, status) {
       return "forbidden";
     case "busy":
       return "unavailable";
+    case "rate_limited":
+      return "rate_limited";
     case "aborted":
       return "timeout";
     default:
@@ -950,7 +979,7 @@ function createPortMcpTransport(port, options = {}) {
         resolver.reject(new PluginStorageUploadError(
           message,
           status !== void 0 ? pluginStorageUploadReasonFromStatus(status) : "unknown",
-          { status, code }
+          { status, code, retryAfterSeconds: parsePluginStorageRetryAfter(reply.retryAfterSeconds) }
         ));
         return;
       }