Merge branch 'pr-7397' into shaw/toon-all-plugins-build-checks

Author: Shaw

plugins/plugin-elizacloud/models/image.ts

@@ -47,6 +47,29 @@ export async function handleImageDescription(
   runtime: IAgentRuntime,
   params: ImageDescriptionParams | string
 ): Promise<{ title: string; description: string }> {
+  // Honour `DISABLE_IMAGE_DESCRIPTION` (set by the runtime when
+  // `features.vision === false`). The runtime exposes it via getSetting; some
+  // hosts only set it in process.env. Check both before burning a quota slot.
+  // The docs (`docs/runtime/core.md`) already promise this behaviour, but
+  // historically only `plugin-discord` honoured it at the call site, leaving
+  // every other caller (agent-orchestrator's task validator, vision, lifeops,
+  // farcaster, telegram) free to spend the rate-limit budget.
+  const disableSetting = getSetting(runtime, "DISABLE_IMAGE_DESCRIPTION", "");
+  const disabled =
+    disableSetting === "true" ||
+    disableSetting === "1" ||
+    process.env.DISABLE_IMAGE_DESCRIPTION === "true" ||
+    process.env.DISABLE_IMAGE_DESCRIPTION === "1";
+  if (disabled) {
+    logger.debug(
+      "[ELIZAOS_CLOUD] IMAGE_DESCRIPTION skipped — DISABLE_IMAGE_DESCRIPTION is set"
+    );
+    return {
+      title: "Image description disabled",
+      description: "Image description is disabled by configuration.",
+    };
+  }
+
   let imageUrl: string;
   let promptText: string | undefined;
   const modelName = getImageDescriptionModel(runtime);
@@ -84,21 +107,56 @@ export async function handleImageDescription(
       max_tokens: maxTokens,
     };
 
-    // Retry with exponential backoff for transient errors (429 rate limit)
+    // On 429, honour the upstream's `retryAfter` instead of retrying on a
+    // hardcoded backoff. Hardcoded retries inside the rate-limit window add
+    // wasted requests to the same bucket and make the problem worse — see
+    // #7374's billing render-loop fix and S33's dashboard 429-aware UX.
+    // Strategy: only retry once, only if the upstream signals a short wait
+    // (≤5s, i.e. transient burst). Anything longer, bail immediately and let
+    // the caller fail fast.
     let response: Response | null = null;
-    for (let attempt = 0; attempt < 3; attempt++) {
+    let attemptedRetry = false;
+    for (let attempt = 0; attempt < 2; attempt++) {
       response = await client.routes.postApiV1ChatCompletionsRaw({
         json: requestBody,
       });
+      if (response.status !== 429 || attemptedRetry) break;
+
+      // `Number(null) === 0`, so guard against a missing header before
+      // calling `Number(...)` — otherwise the header path always wins with a
+      // bogus `0` and the body fallback becomes unreachable.
+      const headerValue = response.headers.get("retry-after");
+      const headerRetryAfter =
+        headerValue !== null && Number.isFinite(Number(headerValue))
+          ? Number(headerValue)
+          : undefined;
+      let bodyRetryAfter: number | undefined;
+      try {
+        const peek = (await response.clone().json()) as {
+          retryAfter?: unknown;
+        };
+        bodyRetryAfter =
+          typeof peek?.retryAfter === "number" &&
+          Number.isFinite(peek.retryAfter)
+            ? peek.retryAfter
+            : undefined;
+      } catch {
+        // Body wasn't JSON — fall through to header value.
+      }
+      const retryAfter = headerRetryAfter ?? bodyRetryAfter ?? 0;
 
-      if (response.status === 429 && attempt < 2) {
-        const wait = (attempt + 1) * 2000; // 2s, 4s
+      if (retryAfter > 0 && retryAfter <= 5) {
         logger.warn(
-          `[ELIZAOS_CLOUD] Image analysis rate-limited (429), retrying in ${wait / 1000}s...`
+          `[ELIZAOS_CLOUD] Image analysis rate-limited (429), retrying once after ${retryAfter}s...`
         );
-        await new Promise((r) => setTimeout(r, wait));
+        await new Promise((r) => setTimeout(r, retryAfter * 1000));
+        attemptedRetry = true;
         continue;
       }
+      // Long rate-limit window: don't burn another bucket slot retrying inside it.
+      logger.warn(
+        `[ELIZAOS_CLOUD] Image analysis rate-limited (429); upstream retryAfter=${retryAfter || "unknown"}s — failing fast`
+      );
       break;
     }
 
@@ -109,6 +167,11 @@ export async function handleImageDescription(
           "Eliza Cloud credits exhausted — top up at https://www.elizacloud.ai/dashboard/settings?tab=billing"
         );
       }
+      if (status === 429) {
+        throw new Error(
+          "Eliza Cloud rate limit exceeded for image description — try again in a minute"
+        );
+      }
       throw new Error(`ElizaOS Cloud API error: ${status}`);
     }