cascade-ai 0.66.0 → 0.66.2

package/dist/index.d.cts

@@ -2948,6 +2948,14 @@ declare class T3Worker extends BaseTier {
      *   1. Find a semantically similar registered tool and retry with same input
      *   2. Synthesize a new tool via ToolCreator (if available) and run it
      *   3. Return the original error so the agent loop can decide what to do next
+     *
+     * Scoped to CHEAP, task-scoped failures — the class of problem it was built
+     * for is a wrong or missing tool name, where a name-similar sibling plausibly
+     * does the same job for the same (near-zero) cost. PROVIDER_BACKED_TOOLS never
+     * reach it: their siblings are keyword-similar but semantically different
+     * (generate_image is not a stand-in for generate_video), and every attempt —
+     * theirs, or a synthesized replacement's — is separately billed. See the
+     * fast-fail branch in executeTool().
      */
     private adaptiveFallback;
     /**

package/dist/index.d.ts

@@ -2948,6 +2948,14 @@ declare class T3Worker extends BaseTier {
      *   1. Find a semantically similar registered tool and retry with same input
      *   2. Synthesize a new tool via ToolCreator (if available) and run it
      *   3. Return the original error so the agent loop can decide what to do next
+     *
+     * Scoped to CHEAP, task-scoped failures — the class of problem it was built
+     * for is a wrong or missing tool name, where a name-similar sibling plausibly
+     * does the same job for the same (near-zero) cost. PROVIDER_BACKED_TOOLS never
+     * reach it: their siblings are keyword-similar but semantically different
+     * (generate_image is not a stand-in for generate_video), and every attempt —
+     * theirs, or a synthesized replacement's — is separately billed. See the
+     * fast-fail branch in executeTool().
      */
     private adaptiveFallback;
     /**

package/dist/index.js

@@ -1862,7 +1862,7 @@ function reconcilePrice(model, live) {
 }
 
 // src/constants.ts
-var CASCADE_VERSION = "0.66.0";
+var CASCADE_VERSION = "0.66.2";
 var CASCADE_CONFIG_DIR = ".cascade";
 var CASCADE_MD_FILE = "CASCADE.md";
 var CASCADE_IGNORE_FILE = ".cascadeignore";
@@ -6590,7 +6590,15 @@ var KNOWN_TOOLS = [
   "glob",
   "grep",
   "web_fetch",
-  "generate_image"
+  // Every media tool buildMediaTools can register, not just the image one.
+  // Omitting three of the four meant a run whose ONLY tools were media ones
+  // (a video-generation subtask on an account with no file/web tools) counted
+  // as "no tools registered" and dropped all tool guidance — the worker was
+  // then told nothing about using tools at all, and wrote the video as prose.
+  "generate_image",
+  "generate_video",
+  "generate_speech",
+  "transcribe_audio"
 ];
 var PROVIDER_BACKED_TOOLS = /* @__PURE__ */ new Set([
   "generate_image",
@@ -6619,6 +6627,15 @@ function buildWorkerRules(has) {
     // 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.',
+    // The video counterpart of the image rule above, and the fix for the
+    // reported "it writes scripts forever and never makes the video" run. The
+    // failure mode is identical — the model narrates the deliverable instead of
+    // producing it — but the stakes are not: a video subtask that ends in prose
+    // has burned the whole pre-production plan for nothing. Unlike the image
+    // rule this is NOT scoped to a document format, because the clip itself is
+    // the deliverable rather than an illustration inside one, and the reference
+    // syntax is a plain link: Markdown image syntax does not embed a video.
+    has("generate_video") && '- When the subtask deliverable is a video, you MUST call the "generate_video" tool \u2014 that call IS the deliverable, and the subtask is not done until it has returned. NEVER deliver the video as prose, a script, a storyboard, or a bracketed placeholder such as [video: a cat skating], and NEVER claim a video exists unless the tool reported a location for it. Call it exactly ONCE: it is billed per second of output and renders for minutes, so a second call charges the user again. Then report the location string the tool returned VERBATIM as your result, referencing it as [description](location) if it goes inside a document. If the tool reports a failure or a timeout, report that failure verbatim and stop \u2014 do NOT call it again, and do NOT substitute a written description of a video that was never made.',
     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.',
@@ -7161,6 +7178,12 @@ HIERARCHY CONTEXT: ${this.hierarchyContext}` : "") + textToolSuffix,
       if (isTaggedSystemic || isProviderBacked && classifyProviderError(err).systemic) {
         throw new CriticalToolError(errMsg, tc.name);
       }
+      if (isProviderBacked) {
+        throw new CriticalToolError(
+          `${tc.name} failed and was not retried \u2014 media generation is billed per attempt, so Cascade stops on the first failure instead of paying for a second. Reason: ${errMsg}`,
+          tc.name
+        );
+      }
       return await this.adaptiveFallback(tc, `Tool error: ${errMsg}`);
     }
   }
@@ -7170,6 +7193,14 @@ HIERARCHY CONTEXT: ${this.hierarchyContext}` : "") + textToolSuffix,
    *   1. Find a semantically similar registered tool and retry with same input
    *   2. Synthesize a new tool via ToolCreator (if available) and run it
    *   3. Return the original error so the agent loop can decide what to do next
+   *
+   * Scoped to CHEAP, task-scoped failures — the class of problem it was built
+   * for is a wrong or missing tool name, where a name-similar sibling plausibly
+   * does the same job for the same (near-zero) cost. PROVIDER_BACKED_TOOLS never
+   * reach it: their siblings are keyword-similar but semantically different
+   * (generate_image is not a stand-in for generate_video), and every attempt —
+   * theirs, or a synthesized replacement's — is separately billed. See the
+   * fast-fail branch in executeTool().
    */
   async adaptiveFallback(tc, originalError) {
     const altTool = this.findAlternativeTool(tc.name);
@@ -7922,15 +7953,244 @@ _(incomplete: ${t2Result.issues.join("; ")})_`;
   return output;
 }
 
+// src/core/multimodal/registry.ts
+var CAPABILITIES = [
+  // ── Image ──
+  {
+    modality: "image",
+    provider: "openai",
+    modelId: "dall-e-3",
+    api: "openai-images"
+  },
+  {
+    // 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: "gemini-2.5-flash-image",
+    api: "gemini-generate-content"
+  },
+  // ── Speech (text → audio) ──
+  {
+    modality: "speech",
+    provider: "openai",
+    modelId: "tts-1",
+    api: "openai-speech"
+  },
+  {
+    // The only quality claim in this table that needs no leaderboard: OpenAI
+    // ships these as the same voice at two fidelities and charges double for
+    // this one. That is the vendor's own ordering, not an inference.
+    modality: "speech",
+    provider: "openai",
+    modelId: "tts-1-hd",
+    api: "openai-speech",
+    quality: 70,
+    qualityBasis: "OpenAI's own hd variant of tts-1, priced 2x"
+  },
+  // ── Transcription (audio → text) ──
+  {
+    modality: "transcription",
+    provider: "openai",
+    modelId: "whisper-1",
+    api: "openai-transcriptions"
+  },
+  // ── Video ──
+  {
+    // Long-running: submit returns an operation name, the video lands minutes
+    // later, and the bytes come from a short-lived signed URL. generate.ts owns
+    // that polling loop; the registry only records the shape via `api`.
+    //
+    // `veo-3.1-generate-001` (no "-preview") is VERTEX AI's id for this model,
+    // not the Gemini Developer API's — this file calls
+    // generativelanguage.googleapis.com (see generate.ts), which 404s on it:
+    // "models/veo-3.1-generate-001 is not found for API version v1beta". On the
+    // Gemini API specifically, Veo 3.1 is still preview-only, so the correct id
+    // there is `veo-3.1-generate-preview`.
+    // https://ai.google.dev/gemini-api/docs/veo
+    modality: "video",
+    provider: "gemini",
+    modelId: "veo-3.1-generate-preview",
+    api: "gemini-predict-lro"
+  }
+];
+function capabilityCost(cap) {
+  const match = findPricing(cap.modelId, cap.provider, {
+    fallbackProviders: cap.provider === "gemini" ? ["vertex"] : []
+  });
+  const rate = match?.entry.rates?.[0];
+  if (!rate) return null;
+  const unitLabel = {
+    per_image: "per image",
+    per_second: "per second of video",
+    per_character: "per character",
+    per_audio_minute: "per audio minute"
+  };
+  const unit = unitLabel[rate.unit] ?? rate.unit;
+  const amount = rate.amount;
+  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;
+  constructor(availableProviders) {
+    this.available = new Set(availableProviders);
+  }
+  /** Every capability whose provider is configured AND which Cascade can call. */
+  usable(modality) {
+    return CAPABILITIES.filter(
+      (c) => !c.unsupported && this.available.has(c.provider) && (!modality || c.modality === modality)
+    );
+  }
+  /** Modalities this account can actually generate right now. */
+  availableModalities() {
+    return [...new Set(this.usable().map((c) => c.modality))];
+  }
+  /**
+   * Every usable capability for a modality, best first.
+   *
+   * Ranked models beat unranked ones, then higher quality, then lower unit
+   * 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.
+   */
+  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;
+      const pa = a.cost?.amount ?? Number.POSITIVE_INFINITY;
+      const pb = b.cost?.amount ?? Number.POSITIVE_INFINITY;
+      return pa - pb;
+    });
+    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 —
+   * including the things it cannot, and why.
+   *
+   * This is the USER-facing inventory (model ids and unit prices), keyed on
+   * which providers are configured. It is deliberately NOT what the planner
+   * reads: see `describeGenerationForPlanner()` below for that, and the note
+   * there for why the two cannot be the same string.
+   */
+  describe() {
+    const lines = [];
+    const usable = this.usable();
+    if (usable.length) {
+      lines.push("Generation models available on your configured providers:");
+      for (const modality of ["image", "speech", "transcription", "video"]) {
+        const forModality = usable.filter((c) => c.modality === modality);
+        if (!forModality.length) continue;
+        const shown = forModality.map((c) => {
+          const cost = capabilityCost(c);
+          return `${c.modelId}${cost ? ` (${cost.label})` : ""}`;
+        });
+        lines.push(`  ${modality}: ${shown.join(", ")}`);
+      }
+    } else {
+      lines.push("No generation models are available \u2014 none of your configured providers offers one.");
+    }
+    const blocked = CAPABILITIES.filter((c) => c.unsupported && this.available.has(c.provider));
+    for (const c of blocked) {
+      lines.push(`  ${c.modality}: ${c.modelId} exists on your account but is not callable. ${c.unsupported}`);
+    }
+    lines.push(
+      "  music: no supported provider exposes a music-generation API, so Cascade cannot generate music."
+    );
+    return lines.join("\n");
+  }
+};
+var PLANNER_FACTS = [
+  { tool: "generate_image", modality: "image", shape: "one call returns one finished image" },
+  { tool: "generate_speech", modality: "speech", shape: "one call returns one finished audio file" },
+  {
+    tool: "generate_video",
+    modality: "video",
+    shape: "one call returns one finished clip, after rendering for 1-3 minutes (Cascade stops waiting at 8)"
+  },
+  {
+    tool: "transcribe_audio",
+    modality: "transcription",
+    shape: "one call returns the transcript of one audio file"
+  }
+];
+function plannerPriceNote(modality) {
+  const costs = CAPABILITIES.filter((c) => c.modality === modality && !c.unsupported).map((c) => capabilityCost(c)).filter((c) => c !== null);
+  if (!costs.length) return "";
+  const labels = new Set(costs.map((c) => c.label));
+  if (labels.size === 1) return ` Billed ${costs[0].label}.`;
+  const units = new Set(costs.map((c) => c.unit));
+  return units.size === 1 ? ` Billed ${[...units][0]}.` : "";
+}
+function describeGenerationForPlanner(has) {
+  const present = PLANNER_FACTS.filter((f) => has(f.tool));
+  if (!present.length) return "";
+  const lines = ["MEDIA GENERATION \u2014 the only generation tools this run can call:"];
+  for (const f of present) {
+    lines.push(`- "${f.tool}" (${f.modality}): ${f.shape}.${plannerPriceNote(f.modality)}`);
+  }
+  lines.push(
+    "Each one is a single ATOMIC tool call, made by ONE T3 worker, that produces the finished file. It is never a multi-step pipeline, and no worker can satisfy it by describing the result in words.",
+    "No other modality has a tool here \u2014 never plan a step that generates music, 3D or anything not listed above."
+  );
+  if (has("generate_video")) {
+    lines.push(
+      'VIDEO PLANS MUST END IN THE TOOL CALL. Creative pre-production \u2014 a script, a shot list, direction notes \u2014 is expected and worth planning, but it is NOT the video. Any plan that involves video MUST contain exactly ONE subtask whose deliverable is the "generate_video" call itself; it MUST be the last subtask on that path (dependsOn the pre-production ones), and nothing after it may be required to produce the clip. Never end a video plan on a script, a storyboard or a review step. Never split one clip across several "generate_video" subtasks, and never plan a render \u2192 critique \u2192 re-render loop: every render is billed again and takes minutes.'
+    );
+  }
+  return lines.join("\n");
+}
+
 // src/core/tiers/t2-manager.ts
-function buildT2SystemPrompt(hasPeerMessage) {
+function buildT2SystemPrompt(has) {
+  const generation = describeGenerationForPlanner(has);
   return [
     "You are a T2 Manager agent in the Cascade AI system.",
     "Your role is to analyze a section of a task and decompose it into 2-5 discrete subtasks for T3 Workers.",
     'If subtasks have dependencies, you can specify "executionMode": "sequential" for the section.',
-    hasPeerMessage && 'Provide "peerT3Ids" to subtasks so they can coordinate using the peer_message tool.',
-    "Return ONLY valid JSON matching the T3 subtask array schema \u2014 no other text."
-  ].filter((l) => l !== false).join("\n");
+    has("peer_message") && 'Provide "peerT3Ids" to subtasks so they can coordinate using the peer_message tool.',
+    "Return ONLY valid JSON matching the T3 subtask array schema \u2014 no other text.",
+    generation && `
+${generation}`
+  ].filter((l) => l !== false && l !== "").join("\n");
 }
 var T2Manager = class extends BaseTier {
   router;
@@ -8227,7 +8487,7 @@ Return ONLY the JSON array.`;
     const messages = [{ role: "user", content: prompt }];
     const result = await this.router.generate("T2", {
       messages,
-      systemPrompt: this.systemPromptOverride + buildT2SystemPrompt(this.toolRegistry.hasTool("peer_message")) + (this.hierarchyContext ? `
+      systemPrompt: this.systemPromptOverride + buildT2SystemPrompt((name) => this.toolRegistry.hasTool(name)) + (this.hierarchyContext ? `
 
 HIERARCHY CONTEXT: ${this.hierarchyContext}` : ""),
       maxTokens: 2e3,
@@ -8777,6 +9037,7 @@ function isStrongKeywordOverlap(a = [], b = []) {
 }
 function buildT1SystemPrompt(has) {
   const canWriteArtifacts = has("file_write") || has("file_edit") || has("run_code") || has("pdf_create");
+  const generation = describeGenerationForPlanner(has);
   const rules = [
     "- Simple \u2192 1 T3, Moderate \u2192 2-3 T2s, Complex \u2192 3-5 T2s, Highly Complex \u2192 5+ T2s",
     "- Return ONLY valid JSON \u2014 no other text",
@@ -8811,7 +9072,9 @@ DEPENDENCY GUIDANCE:
 QUALITY RULES:
 - Each section must have a clear, testable "expectedOutput" so T2 knows when it is done.
 - Do NOT create trivial sections that only move files or print summaries \u2014 fold those into adjacent sections.
-- If the plan would naturally produce fewer than 2 independent sections, prefer Moderate routing (single T2).`;
+- If the plan would naturally produce fewer than 2 independent sections, prefer Moderate routing (single T2).${generation ? `
+
+${generation}` : ""}`;
 }
 var T1Administrator = class extends BaseTier {
   router;
@@ -9506,188 +9769,6 @@ Reply with exactly one word: YES, NO, or UNSURE.
   }
 };
 
-// src/core/multimodal/registry.ts
-var CAPABILITIES = [
-  // ── Image ──
-  {
-    modality: "image",
-    provider: "openai",
-    modelId: "dall-e-3",
-    api: "openai-images"
-  },
-  {
-    // 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: "gemini-2.5-flash-image",
-    api: "gemini-generate-content"
-  },
-  // ── Speech (text → audio) ──
-  {
-    modality: "speech",
-    provider: "openai",
-    modelId: "tts-1",
-    api: "openai-speech"
-  },
-  {
-    // The only quality claim in this table that needs no leaderboard: OpenAI
-    // ships these as the same voice at two fidelities and charges double for
-    // this one. That is the vendor's own ordering, not an inference.
-    modality: "speech",
-    provider: "openai",
-    modelId: "tts-1-hd",
-    api: "openai-speech",
-    quality: 70,
-    qualityBasis: "OpenAI's own hd variant of tts-1, priced 2x"
-  },
-  // ── Transcription (audio → text) ──
-  {
-    modality: "transcription",
-    provider: "openai",
-    modelId: "whisper-1",
-    api: "openai-transcriptions"
-  },
-  // ── Video ──
-  {
-    // Long-running: submit returns an operation name, the video lands minutes
-    // later, and the bytes come from a short-lived signed URL. generate.ts owns
-    // that polling loop; the registry only records the shape via `api`.
-    //
-    // `veo-3.1-generate-001` (no "-preview") is VERTEX AI's id for this model,
-    // not the Gemini Developer API's — this file calls
-    // generativelanguage.googleapis.com (see generate.ts), which 404s on it:
-    // "models/veo-3.1-generate-001 is not found for API version v1beta". On the
-    // Gemini API specifically, Veo 3.1 is still preview-only, so the correct id
-    // there is `veo-3.1-generate-preview`.
-    // https://ai.google.dev/gemini-api/docs/veo
-    modality: "video",
-    provider: "gemini",
-    modelId: "veo-3.1-generate-preview",
-    api: "gemini-predict-lro"
-  }
-];
-function capabilityCost(cap) {
-  const match = findPricing(cap.modelId, cap.provider, {
-    fallbackProviders: cap.provider === "gemini" ? ["vertex"] : []
-  });
-  const rate = match?.entry.rates?.[0];
-  if (!rate) return null;
-  const unitLabel = {
-    per_image: "per image",
-    per_second: "per second of video",
-    per_character: "per character",
-    per_audio_minute: "per audio minute"
-  };
-  const unit = unitLabel[rate.unit] ?? rate.unit;
-  const amount = rate.amount;
-  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;
-  constructor(availableProviders) {
-    this.available = new Set(availableProviders);
-  }
-  /** Every capability whose provider is configured AND which Cascade can call. */
-  usable(modality) {
-    return CAPABILITIES.filter(
-      (c) => !c.unsupported && this.available.has(c.provider) && (!modality || c.modality === modality)
-    );
-  }
-  /** Modalities this account can actually generate right now. */
-  availableModalities() {
-    return [...new Set(this.usable().map((c) => c.modality))];
-  }
-  /**
-   * Every usable capability for a modality, best first.
-   *
-   * Ranked models beat unranked ones, then higher quality, then lower unit
-   * 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.
-   */
-  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;
-      const pa = a.cost?.amount ?? Number.POSITIVE_INFINITY;
-      const pb = b.cost?.amount ?? Number.POSITIVE_INFINITY;
-      return pa - pb;
-    });
-    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 —
-   * including the things it cannot, and why. The planner sees this, so being
-   * candid here is what stops it inventing a `generate_music` call.
-   */
-  describe() {
-    const lines = [];
-    const usable = this.usable();
-    if (usable.length) {
-      lines.push("Generation models available on your configured providers:");
-      for (const modality of ["image", "speech", "transcription", "video"]) {
-        const forModality = usable.filter((c) => c.modality === modality);
-        if (!forModality.length) continue;
-        const shown = forModality.map((c) => {
-          const cost = capabilityCost(c);
-          return `${c.modelId}${cost ? ` (${cost.label})` : ""}`;
-        });
-        lines.push(`  ${modality}: ${shown.join(", ")}`);
-      }
-    } else {
-      lines.push("No generation models are available \u2014 none of your configured providers offers one.");
-    }
-    const blocked = CAPABILITIES.filter((c) => c.unsupported && this.available.has(c.provider));
-    for (const c of blocked) {
-      lines.push(`  ${c.modality}: ${c.modelId} exists on your account but is not callable. ${c.unsupported}`);
-    }
-    lines.push(
-      "  music: no supported provider exposes a music-generation API, so Cascade cannot generate music."
-    );
-    return lines.join("\n");
-  }
-};
-
 // src/tools/base.ts
 var BaseTool = class {
   workspaceRoot = process.cwd();
@@ -9708,10 +9789,17 @@ var BaseTool = class {
 
 // src/core/multimodal/generate.ts
 var DEFAULT_TIMEOUT_MS = 12e4;
+var GenerationGaveUpError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "GenerationGaveUpError";
+  }
+};
 async function callProvider(fn, modelId) {
   try {
     return await fn();
   } catch (err) {
+    if (err instanceof GenerationGaveUpError) throw err;
     const classified = classifyProviderError(err);
     throw new Error(describeProviderError(classified, modelId));
   }
@@ -9909,8 +9997,8 @@ async function generateVideo(cap, cfg, req, signal, onProgress) {
       onProgress?.("Still rendering\u2026");
     }
     if (!operation.done) {
-      throw new Error(
-        `Video was still rendering after ${Math.round(VIDEO_TIMEOUT_MS / 6e4)} minutes. It may still complete on the provider side, but Cascade stopped waiting.`
+      throw new GenerationGaveUpError(
+        `${cap.modelId} timed out after ${Math.round(VIDEO_TIMEOUT_MS / 6e4)} minutes \u2014 no video was produced. Cascade stopped waiting; the render may still finish on the provider side, but nothing was saved. Try again with a shorter clip or a simpler prompt.`
       );
     }
     if (operation.error?.message) throw new Error(operation.error.message);