cascade-ai 0.55.0 → 0.63.0

package/dist/index.js

@@ -1,6 +1,6 @@
 import Database from 'better-sqlite3';
-import path24 from 'path';
-import fs23 from 'fs';
+import path24, { dirname } from 'path';
+import fs23, { mkdirSync, writeFileSync, existsSync, readFileSync } from 'fs';
 import os6 from 'os';
 import crypto4, { randomUUID, randomBytes, createHash, timingSafeEqual, webcrypto } from 'crypto';
 import EventEmitter, { setMaxListeners } from 'events';
@@ -41,12 +41,6 @@ import cron from 'node-cron';
 // Cascade AI — Multi-tier AI Orchestration System
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
 var __esm = (fn, res) => function __init() {
   return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
 };
@@ -1597,6 +1591,23 @@ var pricing_data_default = {
       ],
       notes: "Google bills image output per output-token ($120 per 1M image output tokens); $0.134/image is that rate applied to one default-resolution image. Cost per image therefore varies with resolution."
     },
+    {
+      model: "gemini-2.5-flash-image",
+      provider: "gemini",
+      modality: "image",
+      currency: "USD",
+      asOf: "2026-07-27",
+      source: "https://ai.google.dev/gemini-api/docs/pricing#gemini-2.5-flash-image",
+      provenance: "litellm-catalog",
+      rates: [
+        {
+          unit: "per_image",
+          amount: 0.039,
+          variant: "default 1024px output"
+        }
+      ],
+      notes: "Google bills image output per output-token ($30 per 1M image output tokens); a default 1024px image is 1290 output tokens, i.e. $0.039. Cost per image therefore varies with resolution."
+    },
     {
       model: "imagen-4.0-generate-001",
       provider: "vertex",
@@ -1851,7 +1862,7 @@ function reconcilePrice(model, live) {
 }
 
 // src/constants.ts
-var CASCADE_VERSION = "0.55.0";
+var CASCADE_VERSION = "0.63.0";
 var CASCADE_CONFIG_DIR = ".cascade";
 var CASCADE_MD_FILE = "CASCADE.md";
 var CASCADE_IGNORE_FILE = ".cascadeignore";
@@ -4084,8 +4095,6 @@ var LocalRequestQueue = class {
     };
   }
 };
-
-// src/core/router/dead-models.ts
 var DEAD_MODEL_TTL_MS = 7 * 24 * 60 * 60 * 1e3;
 function deadModelKey(provider, modelId) {
   return `${provider}:${modelId}`;
@@ -4186,16 +4195,13 @@ var DeadModelStore = class {
 function fileDeadModelPersistence(filePath) {
   return {
     load() {
-      const fs25 = __require("fs");
-      if (!fs25.existsSync(filePath)) return [];
-      const raw = JSON.parse(fs25.readFileSync(filePath, "utf-8"));
+      if (!existsSync(filePath)) return [];
+      const raw = JSON.parse(readFileSync(filePath, "utf-8"));
       return Array.isArray(raw) ? raw : [];
     },
     save(records) {
-      const fs25 = __require("fs");
-      const path26 = __require("path");
-      fs25.mkdirSync(path26.dirname(filePath), { recursive: true });
-      fs25.writeFileSync(filePath, JSON.stringify(records, null, 2));
+      mkdirSync(dirname(filePath), { recursive: true });
+      writeFileSync(filePath, JSON.stringify(records, null, 2));
     }
   };
 }
@@ -4629,6 +4635,12 @@ var FAMILY_BENCHMARKS = {
   // Google — strongest at analysis/data and long-context.
   "gemini-2.5-pro": { code: 90, analysis: 93, creative: 86, data: 92 },
   "gemini-2.5-flash": { code: 82, analysis: 83, creative: 80, data: 82 },
+  // The 2.5-lite tier scores below full 2.5-flash but above the older 2.0
+  // lite tier — it exists because a naive `gemini-?2\.5-flash` regex swallows
+  // "gemini-2.5-flash-lite" as a substring match (no lite variant of its own
+  // to fall into), so the weaker lite model got credited with the full
+  // flash's benchmark score and kept winning Cascade Auto's "best value" pick.
+  "gemini-2.5-flash-lite": { code: 72, analysis: 72, creative: 74, data: 72 },
   "gemini-1.5-pro": { code: 82, analysis: 84, creative: 82, data: 85 },
   "gemini-2.0-flash": { code: 79, analysis: 80, creative: 79, data: 80 },
   "gemini-flash-lite": { code: 68, analysis: 68, creative: 70, data: 68 },
@@ -4661,6 +4673,11 @@ var FAMILY_MATCHERS = [
   [/gpt-?4o-mini/i, "gpt-4o-mini"],
   [/gpt-?4o/i, "gpt-4o"],
   [/gemini-?2\.5-pro/i, "gemini-2.5-pro"],
+  // Must precede the bare `2\.5-flash` rule below: that pattern has no word
+  // boundary after "flash" and matches "gemini-2.5-flash-lite" as a plain
+  // substring, so the lite variant would otherwise be scored as the full
+  // flash model (see the FAMILY_BENCHMARKS comment above).
+  [/gemini-?2\.5-flash-lite/i, "gemini-2.5-flash-lite"],
   [/gemini-?2\.5-flash/i, "gemini-2.5-flash"],
   [/gemini-?1\.5-pro/i, "gemini-1.5-pro"],
   [/gemini-?2\.0-flash-lite/i, "gemini-flash-lite"],
@@ -6167,6 +6184,92 @@ function truncateForContext(text, maxChars = 12e3) {
 ${tail}`;
 }
 
+// src/core/router/provider-errors.ts
+var SYSTEMIC = /* @__PURE__ */ new Set([
+  "rate_limit",
+  "quota_exhausted",
+  "auth",
+  "model_unavailable"
+]);
+function isSystemicKind(kind) {
+  return SYSTEMIC.has(kind);
+}
+function statusOf(err) {
+  if (!err || typeof err !== "object") return void 0;
+  const e = err;
+  for (const key of ["status", "statusCode", "code"]) {
+    const v = e[key];
+    if (typeof v === "number" && v >= 100 && v < 600) return v;
+  }
+  const resp = e["response"];
+  if (resp && typeof resp["status"] === "number") return resp["status"];
+  const inner = e["error"];
+  if (inner && typeof inner["code"] === "number") return inner["code"];
+  return void 0;
+}
+function messageOf(err) {
+  if (err instanceof Error) return err.message;
+  if (typeof err === "string") return err;
+  if (err && typeof err === "object") {
+    const e = err;
+    if (typeof e["message"] === "string") return e["message"];
+    const inner = e["error"];
+    if (inner && typeof inner["message"] === "string") return inner["message"];
+    try {
+      return JSON.stringify(err);
+    } catch {
+    }
+  }
+  return String(err);
+}
+function classifyProviderError(err) {
+  const raw = messageOf(err).trim();
+  const status = statusOf(err);
+  const m = raw.toLowerCase();
+  const kind = (() => {
+    if (status === 429) {
+      return /quota|billing|credit|exceeded your current quota|insufficient/.test(m) ? "quota_exhausted" : "rate_limit";
+    }
+    if (status === 401 || status === 403) return "auth";
+    if (status === 404) return "model_unavailable";
+    if (/rate limit|too many requests|resource_exhausted/.test(m)) {
+      return /quota|billing|credit|insufficient/.test(m) ? "quota_exhausted" : "rate_limit";
+    }
+    if (/quota|billing|insufficient_quota|insufficient credit|payment required/.test(m)) return "quota_exhausted";
+    if (/api key|unauthorized|authentication|permission denied|invalid[_ ]api/.test(m)) return "auth";
+    if (/model .*(not found|does not exist|unavailable)|no such model|unknown model|not supported for/.test(m)) {
+      return "model_unavailable";
+    }
+    if (/context length|too many tokens|maximum context|prompt is too long|input too long/.test(m)) return "context_length";
+    if (/safety|content filter|blocked|recitation|prohibited/.test(m)) return "content_filter";
+    if (/econnreset|etimedout|enotfound|socket hang up|network|fetch failed|aborted/.test(m)) return "network";
+    return "unknown";
+  })();
+  return { kind, systemic: isSystemicKind(kind), status, raw };
+}
+function describeProviderError(c, modelId) {
+  const on = modelId ? ` on ${modelId}` : "";
+  const detail = c.raw ? ` Provider said: ${c.raw}` : "";
+  switch (c.kind) {
+    case "rate_limit":
+      return `Rate limit hit${on}. The provider is throttling requests \u2014 lower the number of parallel workers, or use a model with a higher requests-per-minute allowance.${detail}`;
+    case "quota_exhausted":
+      return `Quota or billing limit reached${on}. This will not recover on its own \u2014 check the provider's billing page, or switch this tier to a different provider.${detail}`;
+    case "auth":
+      return `Authentication failed${on}. The API key is missing, expired, or lacks access to this model \u2014 re-check the key in Settings > Providers.${detail}`;
+    case "model_unavailable":
+      return `Model unavailable${on}. The id may be wrong, retired, or not enabled for this API key \u2014 pick a different model for this tier.${detail}`;
+    case "context_length":
+      return `The prompt was too long${on}. Reduce the attached context, or use a model with a larger context window for this tier.${detail}`;
+    case "content_filter":
+      return `The provider's safety filter refused this request${on}.${detail}`;
+    case "network":
+      return `Network error reaching the provider${on}. This is usually transient.${detail}`;
+    default:
+      return `The model call failed${on}.${detail}`;
+  }
+}
+
 // src/core/tiers/t3-worker.ts
 var CriticalToolError = class extends Error {
   constructor(message, toolName) {
@@ -6200,8 +6303,15 @@ var KNOWN_TOOLS = [
   "web_search",
   "glob",
   "grep",
-  "web_fetch"
+  "web_fetch",
+  "generate_image"
 ];
+var PROVIDER_BACKED_TOOLS = /* @__PURE__ */ new Set([
+  "generate_image",
+  "generate_speech",
+  "generate_video",
+  "transcribe_audio"
+]);
 function buildWorkerRules(has) {
   const canWriteFiles = has("file_write") || has("file_edit") || has("run_code");
   const hasAnyTool = KNOWN_TOOLS.some(has);
@@ -6211,9 +6321,22 @@ function buildWorkerRules(has) {
     canWriteFiles && "- If the task asks for a file or artifact, you must actually create it in the workspace, verify that it exists, and inspect it before claiming success.",
     has("web_search") && '- Use the "web_search" tool to find current information, documentation, news, or general web data.',
     has("pdf_create") && '- Use the "pdf_create" tool for PDF requests.',
+    // Without this the model "writes the image" as prose — a bracketed
+    // description sitting in the deck where the picture should be — even with a
+    // working image model registered. Naming the reference syntax matters as
+    // much as naming the tool: a generated image nobody embeds is still a
+    // missing image.
+    //
+    // Scoped to PowerPoint/Word specifically: those are the only exporters
+    // that actually embed a Markdown image reference (cloud/web/exporters.ts
+    // toPptx/toDocx). PDF and plain-text/Markdown deliverables flatten a
+    // reference straight to caption text — telling the model to call
+    // generate_image for THOSE just pays for an image nobody ever sees.
+    has("generate_image") && '- When a slide deck (PowerPoint) or Word document deliverable calls for a decorative image or illustration, you MUST call the "generate_image" tool and then reference its result using Markdown image syntax: ![description](location), where "location" is exactly the string the tool reported back. NEVER write a text placeholder or a bracketed description such as [image: a cat] in its place. Do NOT use "generate_image" for a chart, graph, or diagram that must show exact data (numbers, axes, labels) \u2014 an image model cannot guarantee those values are correct, so render that data as a Markdown table instead. For any OTHER deliverable format (PDF, plain text, code, etc.) do NOT call "generate_image" \u2014 those cannot embed the result, so describe the visual in words instead.',
     has("run_code") && '- Use the "run_code" tool for any file types (Excel, Zip, csv, etc.) or complex processing not covered by other tools. Always cleanup after code execution.',
     "- If you are not making meaningful progress, stop and escalate rather than looping or padding the response.",
     has("peer_message") && '- Use the "peer_message" tool to communicate with other T3 workers if your tasks have dependencies or shared state. You can send updates or wait for signals.',
+    hasAnyTool && "- Only use tools directly relevant to THIS subtask. Do not reach for an unrelated connected-service action (e.g. creating, deleting, or modifying a repository, issue, or PR; sending a message) unless the subtask explicitly calls for it.",
     "- Return structured output that directly addresses the expected output specification."
   ];
   return `You are a T3 Worker agent in the Cascade AI system. Your job is to execute a specific subtask completely and accurately.
@@ -6747,7 +6870,9 @@ HIERARCHY CONTEXT: ${this.hierarchyContext}` : "") + textToolSuffix,
       const durationMs = Date.now() - toolStartMs;
       const errMsg = err instanceof Error ? err.message : String(err);
       this.emit("tool:result", { id: tc.id, tierId: this.id, toolName: tc.name, error: errMsg, durationMs });
-      if (/\b(429|rate.?limit|authentication|api.?key|forbidden|401|403)\b/i.test(errMsg)) {
+      const isTaggedSystemic = err instanceof Error && err.systemic === true;
+      const isProviderBacked = PROVIDER_BACKED_TOOLS.has(tc.name);
+      if (isTaggedSystemic || isProviderBacked && classifyProviderError(err).systemic) {
         throw new CriticalToolError(errMsg, tc.name);
       }
       return await this.adaptiveFallback(tc, `Tool error: ${errMsg}`);
@@ -7035,8 +7160,8 @@ HIERARCHY CONTEXT: ${this.hierarchyContext}` : ""),
     } catch {
       return {
         checksRun: ["completeness", "correctness", "compliance"],
-        passed: ["completeness", "correctness", "compliance"],
-        failed: []
+        passed: [],
+        failed: ["completeness"]
       };
     }
   }
@@ -7826,7 +7951,7 @@ HIERARCHY CONTEXT: ${this.hierarchyContext}` : ""),
       const jsonMatch = /\[[\s\S]*\]/.exec(result.content);
       if (!jsonMatch) throw new Error("No JSON array found");
       const parsed = JSON.parse(jsonMatch[0]);
-      return parsed.map((a) => ({ ...a, sectionTitle: assignment.sectionTitle }));
+      return parsed.map((a) => ({ ...a, sectionTitle: assignment.sectionTitle, constraints: a.constraints ?? [] }));
     } catch {
       return [{
         subtaskId: randomUUID(),
@@ -8784,6 +8909,12 @@ SPEC RULES \u2014 each subtask is a self-contained spec slice (workers execute f
     if (!plan.sections || !Array.isArray(plan.sections) || plan.sections.length === 0) {
       throw new Error("Invalid plan: no sections");
     }
+    for (const section of plan.sections) {
+      section.constraints ??= [];
+      for (const subtask of section.t3Subtasks ?? []) {
+        subtask.constraints ??= [];
+      }
+    }
     const [min, max] = COMPLEXITY_T2_COUNT[plan.complexity] ?? [1, 8];
     if (plan.sections.length < min) ;
   }
@@ -9099,17 +9230,17 @@ var CAPABILITIES = [
     api: "openai-images"
   },
   {
-    // Imagen, not `gemini-3-pro-image`. That id appears on Google's PRICING
-    // page but 404s on `:predict` ("not found for API version v1beta, or is not
-    // supported for predict") — the Gemini image models are called through
-    // generateContent with an image response modality, while `:predict` is the
-    // Imagen shape this executor implements. A billing line item is not proof
-    // of a callable endpoint, which is the assumption that put the wrong id
-    // here in the first place.
+    // Was `imagen-4.0-generate-001` on `:predict`, which now 404s for new keys
+    // ("no longer available to new users") — Imagen's :predict API is deprecated
+    // and shuts down 2026-08-17. Google's own migration path is this model on
+    // the ordinary generateContent endpoint, so the fix was never another Imagen
+    // id: the whole request/response SHAPE changes, which is why `api` moved to
+    // 'gemini-generate-content' rather than just the modelId moving.
+    // https://ai.google.dev/gemini-api/docs/imagen
     modality: "image",
     provider: "gemini",
-    modelId: "imagen-4.0-generate-001",
-    api: "gemini-predict"
+    modelId: "gemini-2.5-flash-image",
+    api: "gemini-generate-content"
   },
   // ── Speech (text → audio) ──
   {
@@ -9164,6 +9295,14 @@ function capabilityCost(cap) {
   const shown = amount < 1e-3 ? amount.toExponential(2) : amount.toFixed(4);
   return { label: `$${shown} ${unit}`, amount, unit };
 }
+function explainChoice(c, cost, modality, isBest) {
+  const priced = cost ? ` ${cost.label}.` : "";
+  if (c.quality !== void 0) {
+    return isBest ? `${c.modelId} (${c.provider}) \u2014 ranked highest for ${modality}: ${c.qualityBasis}.${priced}` : `${c.modelId} (${c.provider}) \u2014 ranked alternative for ${modality}: ${c.qualityBasis}.${priced}`;
+  }
+  const noRanking = ". No published quality ranking is applied for this modality, so this is a cost choice, not a quality one.";
+  return isBest ? `${c.modelId} (${c.provider}) \u2014 cheapest usable ${modality} model` + (cost ? ` at ${cost.label}` : "") + noRanking : `${c.modelId} (${c.provider}) \u2014 alternative usable ${modality} model` + (cost ? ` at ${cost.label}` : "") + noRanking;
+}
 var MultimodalRegistry = class {
   /** Provider types the user has actually configured a key for. */
   available;
@@ -9181,22 +9320,20 @@ var MultimodalRegistry = class {
     return [...new Set(this.usable().map((c) => c.modality))];
   }
   /**
-   * Pick a model for a modality.
+   * Every usable capability for a modality, best first.
    *
    * Ranked models beat unranked ones, then higher quality, then lower unit
-   * price. An explicit `preferModel` wins outright when it is usable — the user
-   * naming a model is a stronger signal than any prior.
+   * price. An explicit `preferModel` is moved to the head when it is usable —
+   * the user naming a model is a stronger signal than any prior.
+   *
+   * `select()` is just the head of this list. The TAIL is the point: a systemic
+   * provider failure (dead key, 404, exhausted quota) is scoped to one
+   * provider+model, so "this model cannot draw" is not the same fact as "this
+   * account cannot draw". A caller holding the ordered alternatives can try the
+   * next provider instead of aborting the whole run — see generate-media.ts.
    */
-  select(modality, opts = {}) {
-    const pool = this.usable(modality);
-    if (!pool.length) return null;
-    if (opts.preferModel) {
-      const wanted = pool.find((c) => c.modelId === opts.preferModel);
-      if (wanted) {
-        return { capability: wanted, cost: capabilityCost(wanted), reason: `Requested explicitly: ${wanted.modelId}.` };
-      }
-    }
-    const scored = pool.map((c) => ({ c, cost: capabilityCost(c) })).sort((a, b) => {
+  rank(modality, opts = {}) {
+    const scored = this.usable(modality).map((c) => ({ c, cost: capabilityCost(c) })).sort((a, b) => {
       const qa = a.c.quality ?? -1;
       const qb = b.c.quality ?? -1;
       if (qa !== qb) return qb - qa;
@@ -9204,10 +9341,25 @@ var MultimodalRegistry = class {
       const pb = b.cost?.amount ?? Number.POSITIVE_INFINITY;
       return pa - pb;
     });
-    const best = scored[0];
-    const ranked = best.c.quality !== void 0;
-    const reason = ranked ? `${best.c.modelId} (${best.c.provider}) \u2014 ranked highest for ${modality}: ${best.c.qualityBasis}.` + (best.cost ? ` ${best.cost.label}.` : "") : `${best.c.modelId} (${best.c.provider}) \u2014 cheapest usable ${modality} model` + (best.cost ? ` at ${best.cost.label}` : "") + ". No published quality ranking is applied for this modality, so this is a cost choice, not a quality one.";
-    return { capability: best.c, cost: best.cost, reason };
+    const results = scored.map(({ c, cost }, i) => ({
+      capability: c,
+      cost,
+      reason: explainChoice(c, cost, modality, i === 0)
+    }));
+    if (opts.preferModel) {
+      const i = results.findIndex((r) => r.capability.modelId === opts.preferModel);
+      if (i > -1) {
+        const [wanted] = results.splice(i, 1);
+        results.unshift({ ...wanted, reason: `Requested explicitly: ${wanted.capability.modelId}.` });
+      }
+    }
+    return results;
+  }
+  /**
+   * Pick a model for a modality — the best usable one, or null if there is none.
+   */
+  select(modality, opts = {}) {
+    return this.rank(modality, opts)[0] ?? null;
   }
   /**
    * A plain-language account of what this account can and cannot generate —
@@ -9260,92 +9412,6 @@ var BaseTool = class {
   }
 };
 
-// src/core/router/provider-errors.ts
-var SYSTEMIC = /* @__PURE__ */ new Set([
-  "rate_limit",
-  "quota_exhausted",
-  "auth",
-  "model_unavailable"
-]);
-function isSystemicKind(kind) {
-  return SYSTEMIC.has(kind);
-}
-function statusOf(err) {
-  if (!err || typeof err !== "object") return void 0;
-  const e = err;
-  for (const key of ["status", "statusCode", "code"]) {
-    const v = e[key];
-    if (typeof v === "number" && v >= 100 && v < 600) return v;
-  }
-  const resp = e["response"];
-  if (resp && typeof resp["status"] === "number") return resp["status"];
-  const inner = e["error"];
-  if (inner && typeof inner["code"] === "number") return inner["code"];
-  return void 0;
-}
-function messageOf(err) {
-  if (err instanceof Error) return err.message;
-  if (typeof err === "string") return err;
-  if (err && typeof err === "object") {
-    const e = err;
-    if (typeof e["message"] === "string") return e["message"];
-    const inner = e["error"];
-    if (inner && typeof inner["message"] === "string") return inner["message"];
-    try {
-      return JSON.stringify(err);
-    } catch {
-    }
-  }
-  return String(err);
-}
-function classifyProviderError(err) {
-  const raw = messageOf(err).trim();
-  const status = statusOf(err);
-  const m = raw.toLowerCase();
-  const kind = (() => {
-    if (status === 429) {
-      return /quota|billing|credit|exceeded your current quota|insufficient/.test(m) ? "quota_exhausted" : "rate_limit";
-    }
-    if (status === 401 || status === 403) return "auth";
-    if (status === 404) return "model_unavailable";
-    if (/rate limit|too many requests|resource_exhausted/.test(m)) {
-      return /quota|billing|credit|insufficient/.test(m) ? "quota_exhausted" : "rate_limit";
-    }
-    if (/quota|billing|insufficient_quota|insufficient credit|payment required/.test(m)) return "quota_exhausted";
-    if (/api key|unauthorized|authentication|permission denied|invalid[_ ]api/.test(m)) return "auth";
-    if (/model .*(not found|does not exist|unavailable)|no such model|unknown model|not supported for/.test(m)) {
-      return "model_unavailable";
-    }
-    if (/context length|too many tokens|maximum context|prompt is too long|input too long/.test(m)) return "context_length";
-    if (/safety|content filter|blocked|recitation|prohibited/.test(m)) return "content_filter";
-    if (/econnreset|etimedout|enotfound|socket hang up|network|fetch failed|aborted/.test(m)) return "network";
-    return "unknown";
-  })();
-  return { kind, systemic: isSystemicKind(kind), status, raw };
-}
-function describeProviderError(c, modelId) {
-  const on = modelId ? ` on ${modelId}` : "";
-  const detail = c.raw ? ` Provider said: ${c.raw}` : "";
-  switch (c.kind) {
-    case "rate_limit":
-      return `Rate limit hit${on}. The provider is throttling requests \u2014 lower the number of parallel workers, or use a model with a higher requests-per-minute allowance.${detail}`;
-    case "quota_exhausted":
-      return `Quota or billing limit reached${on}. This will not recover on its own \u2014 check the provider's billing page, or switch this tier to a different provider.${detail}`;
-    case "auth":
-      return `Authentication failed${on}. The API key is missing, expired, or lacks access to this model \u2014 re-check the key in Settings > Providers.${detail}`;
-    case "model_unavailable":
-      return `Model unavailable${on}. The id may be wrong, retired, or not enabled for this API key \u2014 pick a different model for this tier.${detail}`;
-    case "context_length":
-      return `The prompt was too long${on}. Reduce the attached context, or use a model with a larger context window for this tier.${detail}`;
-    case "content_filter":
-      return `The provider's safety filter refused this request${on}.${detail}`;
-    case "network":
-      return `Network error reaching the provider${on}. This is usually transient.${detail}`;
-    default:
-      return `The model call failed${on}.${detail}`;
-  }
-}
-
 // src/core/multimodal/generate.ts
 var DEFAULT_TIMEOUT_MS = 12e4;
 async function callProvider(fn, modelId) {
@@ -9384,6 +9450,29 @@ function baseUrlFor(cfg, fallback) {
 function stamp(ext) {
   return `cascade-${Date.now()}.${ext}`;
 }
+var GEMINI_ASPECT_RATIOS = [
+  ["1:1", 1 / 1],
+  ["3:2", 3 / 2],
+  ["2:3", 2 / 3],
+  ["3:4", 3 / 4],
+  ["4:3", 4 / 3],
+  ["4:5", 4 / 5],
+  ["5:4", 5 / 4],
+  ["9:16", 9 / 16],
+  ["16:9", 16 / 9],
+  ["21:9", 21 / 9]
+];
+function closestGeminiAspectRatio(size) {
+  const m = size.match(/^(\d+)\s*[x×]\s*(\d+)$/i);
+  if (!m) return void 0;
+  const w = Number(m[1]);
+  const h = Number(m[2]);
+  if (!w || !h) return void 0;
+  const ratio = w / h;
+  return GEMINI_ASPECT_RATIOS.reduce(
+    (best, cand) => Math.abs(cand[1] - ratio) < Math.abs(best[1] - ratio) ? cand : best
+  )[0];
+}
 async function generateImage(cap, cfg, req, signal) {
   return callProvider(async () => {
     if (cap.api === "openai-images") {
@@ -9408,19 +9497,37 @@ async function generateImage(cap, cfg, req, signal) {
         ...first.revised_prompt ? { revisedPrompt: first.revised_prompt } : {}
       };
     }
-    if (cap.api === "gemini-predict") {
+    if (cap.api === "gemini-generate-content") {
       const base = baseUrlFor(cfg, "https://generativelanguage.googleapis.com/v1beta");
-      const url = `${base}/models/${encodeURIComponent(cap.modelId)}:predict`;
+      const url = `${base}/models/${encodeURIComponent(cap.modelId)}:generateContent`;
+      const aspectRatio = req.size ? closestGeminiAspectRatio(req.size) : void 0;
       const res = await postJson(url, {
-        instances: [{ prompt: req.prompt }],
-        parameters: { sampleCount: 1 }
+        contents: [{ parts: [{ text: req.prompt }] }],
+        generationConfig: {
+          // Asked for explicitly: these models can answer with text only, and a
+          // text-only reply to "draw me a cat" is a failed image generation.
+          responseModalities: ["IMAGE", "TEXT"],
+          // Gemini has no free-form pixel size — only a named aspect ratio (see
+          // closestGeminiAspectRatio). Omitted entirely when there's no
+          // requested size, or no supported ratio close enough to bother with.
+          ...aspectRatio ? { imageConfig: { aspectRatio } } : {}
+        }
       }, { "x-goog-api-key": cfg.apiKey ?? "" }, signal);
       const body = await res.json();
-      const first = body.predictions?.[0];
-      if (!first?.bytesBase64Encoded) throw new Error("Image response contained no image data.");
-      const mimeType = first.mimeType ?? "image/png";
+      const candidate = body.candidates?.[0];
+      const parts = candidate?.content?.parts ?? [];
+      const image = parts.find((p) => p.inlineData?.data)?.inlineData;
+      if (!image?.data) {
+        const blocked = body.promptFeedback?.blockReason ?? (candidate?.finishReason && candidate.finishReason !== "STOP" ? candidate.finishReason : void 0);
+        if (blocked) throw new Error(`Image request was blocked by the provider (${blocked}).`);
+        const said = parts.find((p) => p.text)?.text?.trim();
+        throw new Error(
+          "Image response contained no image data." + (said ? ` The model replied with text instead: ${said}` : "")
+        );
+      }
+      const mimeType = image.mimeType ?? "image/png";
       return {
-        data: Buffer.from(first.bytesBase64Encoded, "base64"),
+        data: Buffer.from(image.data, "base64"),
         mimeType,
         filename: stamp(mimeType.includes("jpeg") ? "jpg" : "png"),
         modelId: cap.modelId,
@@ -9573,6 +9680,49 @@ function resolve(deps, modality, preferModel) {
   }
   return { ok: true, selected, cfg };
 }
+function messageOf2(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+async function runWithProviderFallback(deps, modality, first, run, signal) {
+  const failed = first.selected.capability;
+  try {
+    return { value: await run(failed, first.cfg), selected: first.selected };
+  } catch (err) {
+    if (signal?.aborted || !classifyProviderError(err).systemic) throw err;
+    const tried = [`${failed.modelId} (${failed.provider}): ${messageOf2(err)}`];
+    let allSystemic = true;
+    let lastNonSystemic;
+    const seen = /* @__PURE__ */ new Set([failed.provider]);
+    for (const alt of deps.registry.rank(modality)) {
+      if (seen.has(alt.capability.provider)) continue;
+      const cfg = deps.lookupProvider(alt.capability.provider);
+      if (!cfg) continue;
+      seen.add(alt.capability.provider);
+      try {
+        return {
+          value: await run(alt.capability, cfg),
+          selected: alt,
+          fellBackFrom: { capability: failed, error: messageOf2(err) }
+        };
+      } catch (retryErr) {
+        if (signal?.aborted) throw retryErr;
+        tried.push(`${alt.capability.modelId} (${alt.capability.provider}): ${messageOf2(retryErr)}`);
+        if (classifyProviderError(retryErr).systemic) {
+          continue;
+        }
+        allSystemic = false;
+        lastNonSystemic = retryErr;
+      }
+    }
+    if (tried.length === 1) throw err;
+    if (!allSystemic) throw lastNonSystemic;
+    const exhausted = new Error(
+      `${modality} generation failed on every configured provider (${seen.size} tried). ${tried.join(" ")}`
+    );
+    Object.assign(exhausted, { systemic: true });
+    throw exhausted;
+  }
+}
 var GenerateImageTool = class extends BaseTool {
   constructor(deps) {
     super();
@@ -9596,16 +9746,32 @@ var GenerateImageTool = class extends BaseTool {
     const r = resolve(this.deps, "image", input["model"] ? String(input["model"]) : void 0);
     if (!r.ok) return r.error;
     const size = input["size"] ? String(input["size"]) : void 0;
-    const asset = await generateImage(
-      r.selected.capability,
-      r.cfg,
-      { prompt, ...size ? { size } : {} },
+    const attempt = await runWithProviderFallback(
+      this.deps,
+      "image",
+      r,
+      (cap, cfg) => generateImage(cap, cfg, { prompt, ...size ? { size } : {} }, options.signal),
       options.signal
     );
+    const asset = attempt.value;
+    const fell = attempt.fellBackFrom;
     const location = await this.deps.sink(asset);
     return [
       `Image generated and saved to ${location}.`,
-      `Model: ${asset.modelId} \u2014 ${r.selected.reason}`,
+      // Knowing WHERE the image is isn't the same as knowing how to use it: a
+      // model told only "saved to X" tends to describe the picture in prose
+      // instead of embedding it. Spelling out the reference syntax here makes
+      // the worker's "never write a placeholder" rule concretely actionable,
+      // and it works for every host because `location` is whatever that host's
+      // sink returned — a workspace path on desktop/CLI, a URL in the cloud.
+      `To include this image in your output, reference it as: ![description](${location})`,
+      // The reported model has to be the one that actually drew the picture, not
+      // the one that was picked and then failed.
+      `Model: ${asset.modelId} \u2014 ${fell ? `used as a fallback after ${fell.capability.modelId} (${fell.capability.provider}) failed with a systemic error.` : attempt.selected.reason}`,
+      // Worth one line: the run succeeded, so nothing else will report that a
+      // configured provider is broken, and "your Gemini key is dead" is exactly
+      // the kind of thing the user wants to hear once rather than never.
+      fell ? `Note: ${fell.capability.provider} failed first \u2014 ${fell.error}` : "",
       // DALL·E rewrites the prompt before drawing; the model needs to know what
       // was actually rendered, not what it asked for, or its description of the
       // result will not match the image.
@@ -9848,6 +10014,87 @@ function mcpToolName(serverName, toolName) {
 function isMcpToolName(name) {
   return name.startsWith(MCP_TOOL_PREFIX);
 }
+var READ_ONLY_MCP_VERBS = ["list", "get", "search", "read", "describe", "find", "query", "fetch", "show", "view"];
+var MUTATING_MCP_TOKENS = /* @__PURE__ */ new Set([
+  "create",
+  "delete",
+  "remove",
+  "update",
+  "write",
+  "modify",
+  "set",
+  "put",
+  "post",
+  "patch",
+  "push",
+  "merge",
+  "send",
+  "execute",
+  "exec",
+  "run",
+  "deploy",
+  "install",
+  "uninstall",
+  "upload",
+  "publish",
+  "revoke",
+  "grant",
+  "approve",
+  "reject",
+  "cancel",
+  "enable",
+  "disable",
+  "add",
+  "insert",
+  "drop",
+  "truncate",
+  "clear",
+  "reset",
+  "restart",
+  "stop",
+  "kill",
+  "terminate",
+  "rename",
+  "move",
+  "fork",
+  "sync",
+  "replace",
+  "overwrite",
+  "invite",
+  "ban",
+  "block",
+  "assign",
+  "lock",
+  "unlock",
+  "archive",
+  "star",
+  "comment",
+  "reply",
+  "submit",
+  "apply",
+  "trigger",
+  "invoke",
+  "purge",
+  "migrate",
+  "edit",
+  "save",
+  "commit"
+]);
+function mcpTokens(rawToolName) {
+  return rawToolName.split(/[_-]+/).flatMap((segment) => segment.split(/(?<=[a-z0-9])(?=[A-Z])/)).map((t) => t.toLowerCase()).filter(Boolean);
+}
+function isReadOnlyMcpToolName(rawToolName) {
+  if (mcpTokens(rawToolName).some((t) => MUTATING_MCP_TOKENS.has(t))) return false;
+  const lower = rawToolName.toLowerCase();
+  for (const verb of READ_ONLY_MCP_VERBS) {
+    if (!lower.startsWith(verb)) continue;
+    const boundary = rawToolName[verb.length];
+    if (boundary === void 0 || boundary === "_" || boundary === "-" || boundary >= "A" && boundary <= "Z") {
+      return true;
+    }
+  }
+  return false;
+}
 function uniqueMcpServerName(desired, existingNames) {
   const taken = new Set(existingNames.map(mcpServerPrefix));
   if (!taken.has(mcpServerPrefix(desired))) return desired;
@@ -10941,9 +11188,11 @@ var WebSearchTool = class extends BaseTool {
     );
     const errors = [];
     let results = [];
+    let anyBackendReachable = false;
     if (this.config.searxngUrl) {
       try {
         results = await searchSearXNG(query, this.config.searxngUrl, maxResults);
+        anyBackendReachable = true;
         if (results.length > 0) return this.formatResults(query, results);
         errors.push("SearXNG: returned 0 results");
       } catch (err) {
@@ -10953,6 +11202,7 @@ var WebSearchTool = class extends BaseTool {
     if (this.config.braveApiKey) {
       try {
         results = await searchBrave(query, this.config.braveApiKey, maxResults);
+        anyBackendReachable = true;
         if (results.length > 0) return this.formatResults(query, results);
         errors.push("Brave: returned 0 results");
       } catch (err) {
@@ -10962,6 +11212,7 @@ var WebSearchTool = class extends BaseTool {
     if (this.config.tavilyApiKey) {
       try {
         results = await searchTavily(query, this.config.tavilyApiKey, maxResults);
+        anyBackendReachable = true;
         if (results.length > 0) return this.formatResults(query, results);
         errors.push("Tavily: returned 0 results");
       } catch (err) {
@@ -10971,6 +11222,7 @@ var WebSearchTool = class extends BaseTool {
     for (const variant of ["html", "lite"]) {
       try {
         results = await searchDuckDuckGo(query, maxResults, variant);
+        anyBackendReachable = true;
         if (results.length > 0) return this.formatResults(query, results);
         errors.push(`DuckDuckGo ${variant}: returned 0 results`);
       } catch (err) {
@@ -10978,11 +11230,11 @@ var WebSearchTool = class extends BaseTool {
       }
     }
     const configHint = !this.config.searxngUrl && !this.config.braveApiKey && !this.config.tavilyApiKey ? "\nTip: Configure a search backend for better results:\n  \u2022 Self-hosted: set SEARXNG_URL in your environment\n  \u2022 Brave Search API: set BRAVE_SEARCH_API_KEY\n  \u2022 Tavily API: set TAVILY_API_KEY" : "";
-    return [
-      `Web search for "${query}" failed across all backends:`,
+    throw Object.assign(new Error([
+      `Web search for "${query}" found nothing across all backends:`,
       ...errors.map((e) => `  \u2022 ${e}`),
       configHint
-    ].join("\n");
+    ].join("\n")), { systemic: !anyBackendReachable });
   }
   formatResults(query, results) {
     const lines = [`Web search results for: "${query}"`, ""];
@@ -11350,6 +11602,15 @@ var McpToolWrapper = class extends BaseTool {
     this.description = `[MCP:${serverName}] ${description}`;
     this.inputSchema = inputSchema;
   }
+  // Every built-in tool of comparable risk (shell, git, file writes, the
+  // built-in github tool) overrides this to true. An MCP tool never did —
+  // BaseTool's default (false) meant a connected server's create/delete/push
+  // actions ran with zero human approval, whatever they did. MCP carries no
+  // standard "this mutates state" flag, so default to dangerous and name the
+  // exception (a read-only-looking verb) rather than the other way around.
+  isDangerous() {
+    return !isReadOnlyMcpToolName(this.toolName);
+  }
   async execute(input, _options) {
     return this.mcpClient.callTool(this.serverName, this.toolName, input);
   }
@@ -11462,7 +11723,7 @@ var ToolRegistry = class extends EventEmitter {
   requiresApproval(toolName) {
     const defaults = DEFAULT_APPROVAL_REQUIRED;
     const configured = this.config.requireApprovalFor;
-    return defaults.includes(toolName) || configured.includes(toolName);
+    return defaults.includes(toolName) || configured.includes(toolName) || this.isDangerous(toolName);
   }
   isDangerous(toolName) {
     return this.tools.get(toolName)?.isDangerous() ?? false;
@@ -14830,9 +15091,8 @@ var Cascade = class _Cascade extends EventEmitter {
     });
     this.toolRegistry = new ToolRegistry(this.config.tools, workspacePath);
     try {
-      const nodePath = __require("path");
       this.router.setDeadModelStore(new DeadModelStore(
-        fileDeadModelPersistence(nodePath.join(workspacePath, ".cascade", "dead-models.json"))
+        fileDeadModelPersistence(path24.join(workspacePath, ".cascade", "dead-models.json"))
       ));
     } catch {
     }