cascade-ai 0.49.0 → 0.50.0

package/dist/index.d.cts

@@ -1858,6 +1858,12 @@ declare abstract class BaseTier extends EventEmitter {
     getStatus(): TierStatus;
     protected setStatus(status: TierStatus, output?: string): void;
     /** Record the model serving this tier; future status events carry it. */
+    /**
+     * The model actually serving this tier ("provider:id"), once one has been
+     * chosen. The run breaker reads it to attribute a failure to a model rather
+     * than to the subtask that happened to hit it.
+     */
+    getServingModel(): string | undefined;
     protected setServingModel(model: string | undefined): void;
     protected setLabel(label: string): void;
     setSystemPromptOverride(prompt: string): void;
@@ -1873,6 +1879,61 @@ declare abstract class BaseTier extends EventEmitter {
     protected throwIfCancelled(): void;
 }
 
+/**
+ * What kind of failure this is, and — crucially — whether retrying a DIFFERENT
+ * subtask against the same model could plausibly succeed.
+ */
+type ProviderErrorKind = 'rate_limit' | 'quota_exhausted' | 'auth' | 'model_unavailable' | 'context_length' | 'content_filter' | 'network' | 'unknown';
+interface ClassifiedError {
+    kind: ProviderErrorKind;
+    /** True when every other worker on this model is expected to fail the same way. */
+    systemic: boolean;
+    /** HTTP status, when the provider gave us one. */
+    status?: number;
+    /** The provider's own message, trimmed — never invented or paraphrased. */
+    raw: string;
+}
+
+interface BreakerTrip {
+    modelId: string;
+    kind: ClassifiedError['kind'];
+    /** How many systemic failures on this model were seen before tripping. */
+    failures: number;
+    /** User-facing explanation, including the provider's own words. */
+    message: string;
+}
+declare class RunBreaker {
+    private readonly threshold;
+    /** modelId → consecutive systemic failures of the SAME kind. */
+    private counts;
+    private trip;
+    constructor(threshold?: number);
+    /**
+     * Record a failed model call. Returns the trip if this failure is the one
+     * that opened the breaker, otherwise null.
+     *
+     * A non-systemic failure RESETS the model's counter: it is evidence the model
+     * is reachable and answering, which is exactly what a systemic streak claims
+     * it is not.
+     */
+    record(err: unknown, modelId: string | undefined): BreakerTrip | null;
+    /** True once the run should stop launching work that would fail identically. */
+    isOpen(): boolean;
+    /** Why the breaker opened, or null while it is closed. */
+    reason(): BreakerTrip | null;
+    /**
+     * One line for a worker/section that never ran because the breaker was
+     * already open. Says the work was skipped deliberately — not that it failed
+     * on its own merits, which is what an empty FAILED status would imply.
+     */
+    skipMessage(): string;
+    /** Test/diagnostic view of the per-model streaks. */
+    streaks(): Record<string, {
+        kind: string;
+        n: number;
+    }>;
+}
+
 type T2Evaluator = (req: PermissionRequest) => Promise<PermissionDecision | null>;
 type T1Evaluator = (req: PermissionRequest) => Promise<PermissionDecision | null>;
 /**
@@ -2020,6 +2081,7 @@ declare class T1Administrator extends BaseTier {
     private t2Managers;
     private escalations;
     private store?;
+    private runBreaker?;
     private t2PeerBus;
     private permissionEscalator?;
     private toolCreator?;
@@ -2029,6 +2091,8 @@ declare class T1Administrator extends BaseTier {
     private peerMessageSessionId;
     private planApprovalCallback?;
     constructor(router: CascadeRouter, toolRegistry: ToolRegistry, config: CascadeConfig);
+    /** Share the run-wide circuit breaker with every section manager. */
+    setRunBreaker(breaker: RunBreaker): void;
     setStore(store: MemoryStore): void;
     /**
      * Inject the shared PermissionEscalator for this task run.
@@ -2404,6 +2468,7 @@ declare class T2Manager extends BaseTier {
     private escalations;
     private peerSyncBuffer;
     private store?;
+    private runBreaker?;
     private t3PeerBus;
     private t2PeerBus?;
     private permissionEscalator?;
@@ -2415,6 +2480,13 @@ declare class T2Manager extends BaseTier {
     setPeerBus(bus: PeerBus): void;
     setPeerMessageCallback(cb: (event: PeerMessageEvent) => void, sessionId: string): void;
     constructor(router: CascadeRouter, toolRegistry: ToolRegistry, parentId: string);
+    /**
+     * Share the run-wide circuit breaker. Every T2 in a run gets the SAME
+     * instance: three sections each failing once against a dead model is the
+     * same fact as one section failing three times, and a per-section breaker
+     * would never see it.
+     */
+    setRunBreaker(breaker: RunBreaker): void;
     setStore(store: MemoryStore): void;
     /**
      * Inject the shared PermissionEscalator for this task run.

package/dist/index.d.ts

@@ -1858,6 +1858,12 @@ declare abstract class BaseTier extends EventEmitter {
     getStatus(): TierStatus;
     protected setStatus(status: TierStatus, output?: string): void;
     /** Record the model serving this tier; future status events carry it. */
+    /**
+     * The model actually serving this tier ("provider:id"), once one has been
+     * chosen. The run breaker reads it to attribute a failure to a model rather
+     * than to the subtask that happened to hit it.
+     */
+    getServingModel(): string | undefined;
     protected setServingModel(model: string | undefined): void;
     protected setLabel(label: string): void;
     setSystemPromptOverride(prompt: string): void;
@@ -1873,6 +1879,61 @@ declare abstract class BaseTier extends EventEmitter {
     protected throwIfCancelled(): void;
 }
 
+/**
+ * What kind of failure this is, and — crucially — whether retrying a DIFFERENT
+ * subtask against the same model could plausibly succeed.
+ */
+type ProviderErrorKind = 'rate_limit' | 'quota_exhausted' | 'auth' | 'model_unavailable' | 'context_length' | 'content_filter' | 'network' | 'unknown';
+interface ClassifiedError {
+    kind: ProviderErrorKind;
+    /** True when every other worker on this model is expected to fail the same way. */
+    systemic: boolean;
+    /** HTTP status, when the provider gave us one. */
+    status?: number;
+    /** The provider's own message, trimmed — never invented or paraphrased. */
+    raw: string;
+}
+
+interface BreakerTrip {
+    modelId: string;
+    kind: ClassifiedError['kind'];
+    /** How many systemic failures on this model were seen before tripping. */
+    failures: number;
+    /** User-facing explanation, including the provider's own words. */
+    message: string;
+}
+declare class RunBreaker {
+    private readonly threshold;
+    /** modelId → consecutive systemic failures of the SAME kind. */
+    private counts;
+    private trip;
+    constructor(threshold?: number);
+    /**
+     * Record a failed model call. Returns the trip if this failure is the one
+     * that opened the breaker, otherwise null.
+     *
+     * A non-systemic failure RESETS the model's counter: it is evidence the model
+     * is reachable and answering, which is exactly what a systemic streak claims
+     * it is not.
+     */
+    record(err: unknown, modelId: string | undefined): BreakerTrip | null;
+    /** True once the run should stop launching work that would fail identically. */
+    isOpen(): boolean;
+    /** Why the breaker opened, or null while it is closed. */
+    reason(): BreakerTrip | null;
+    /**
+     * One line for a worker/section that never ran because the breaker was
+     * already open. Says the work was skipped deliberately — not that it failed
+     * on its own merits, which is what an empty FAILED status would imply.
+     */
+    skipMessage(): string;
+    /** Test/diagnostic view of the per-model streaks. */
+    streaks(): Record<string, {
+        kind: string;
+        n: number;
+    }>;
+}
+
 type T2Evaluator = (req: PermissionRequest) => Promise<PermissionDecision | null>;
 type T1Evaluator = (req: PermissionRequest) => Promise<PermissionDecision | null>;
 /**
@@ -2020,6 +2081,7 @@ declare class T1Administrator extends BaseTier {
     private t2Managers;
     private escalations;
     private store?;
+    private runBreaker?;
     private t2PeerBus;
     private permissionEscalator?;
     private toolCreator?;
@@ -2029,6 +2091,8 @@ declare class T1Administrator extends BaseTier {
     private peerMessageSessionId;
     private planApprovalCallback?;
     constructor(router: CascadeRouter, toolRegistry: ToolRegistry, config: CascadeConfig);
+    /** Share the run-wide circuit breaker with every section manager. */
+    setRunBreaker(breaker: RunBreaker): void;
     setStore(store: MemoryStore): void;
     /**
      * Inject the shared PermissionEscalator for this task run.
@@ -2404,6 +2468,7 @@ declare class T2Manager extends BaseTier {
     private escalations;
     private peerSyncBuffer;
     private store?;
+    private runBreaker?;
     private t3PeerBus;
     private t2PeerBus?;
     private permissionEscalator?;
@@ -2415,6 +2480,13 @@ declare class T2Manager extends BaseTier {
     setPeerBus(bus: PeerBus): void;
     setPeerMessageCallback(cb: (event: PeerMessageEvent) => void, sessionId: string): void;
     constructor(router: CascadeRouter, toolRegistry: ToolRegistry, parentId: string);
+    /**
+     * Share the run-wide circuit breaker. Every T2 in a run gets the SAME
+     * instance: three sections each failing once against a dead model is the
+     * same fact as one section failing three times, and a per-section breaker
+     * would never see it.
+     */
+    setRunBreaker(breaker: RunBreaker): void;
     setStore(store: MemoryStore): void;
     /**
      * Inject the shared PermissionEscalator for this task run.

package/dist/index.js

@@ -1845,7 +1845,7 @@ function reconcilePrice(model, live) {
 }
 
 // src/constants.ts
-var CASCADE_VERSION = "0.49.0";
+var CASCADE_VERSION = "0.50.0";
 var CASCADE_CONFIG_DIR = ".cascade";
 var CASCADE_MD_FILE = "CASCADE.md";
 var CASCADE_IGNORE_FILE = ".cascadeignore";
@@ -5461,6 +5461,14 @@ var BaseTier = class extends EventEmitter {
     this.emit("tier:status", event);
   }
   /** Record the model serving this tier; future status events carry it. */
+  /**
+   * The model actually serving this tier ("provider:id"), once one has been
+   * chosen. The run breaker reads it to attribute a failure to a model rather
+   * than to the subtask that happened to hit it.
+   */
+  getServingModel() {
+    return this.servingModel;
+  }
   setServingModel(model) {
     this.servingModel = model || void 0;
   }
@@ -7196,6 +7204,7 @@ var T2Manager = class extends BaseTier {
   escalations = [];
   peerSyncBuffer = [];
   store;
+  runBreaker;
   t3PeerBus = new PeerBus();
   // ← T3↔T3 bus (local to this T2)
   t2PeerBus;
@@ -7226,6 +7235,15 @@ var T2Manager = class extends BaseTier {
     this.router = router;
     this.toolRegistry = toolRegistry;
   }
+  /**
+   * Share the run-wide circuit breaker. Every T2 in a run gets the SAME
+   * instance: three sections each failing once against a dead model is the
+   * same fact as one section failing three times, and a per-section breaker
+   * would never see it.
+   */
+  setRunBreaker(breaker) {
+    this.runBreaker = breaker;
+  }
   setStore(store) {
     this.store = store;
   }
@@ -7349,7 +7367,8 @@ Guidance (must be followed): ${decision.note}`
       const overallStatus = this.determineStatus(t3Results);
       const isOk = overallStatus === "COMPLETED" || overallStatus === "PARTIAL";
       this.setStatus(isOk ? "COMPLETED" : "FAILED", summary);
-      this.sendStatusUpdate({ progressPct: 100, currentAction: "Section complete", status: "IN_PROGRESS", output: summary });
+      const sectionAction = overallStatus === "COMPLETED" ? "Section complete" : overallStatus === "PARTIAL" ? "Section partially complete \u2014 some subtasks failed" : overallStatus === "ESCALATED" ? "Section escalated \u2014 needs a decision" : "Section failed \u2014 no subtask completed";
+      this.sendStatusUpdate({ progressPct: 100, currentAction: sectionAction, status: "IN_PROGRESS", output: summary });
       const result = {
         sectionId: assignment.sectionId,
         sectionTitle: assignment.sectionTitle,
@@ -7519,6 +7538,24 @@ HIERARCHY CONTEXT: ${this.hierarchyContext}` : ""),
     const reinforceCfg = this.router.getReinforcementsConfig?.() ?? { enabled: false, maxPerSection: 4 };
     let reinforcementsAdded = 0;
     while (remaining.size > 0) {
+      if (this.runBreaker?.isOpen()) {
+        const why = this.runBreaker.skipMessage();
+        this.log(`Run breaker open \u2014 skipping ${remaining.size} remaining subtask(s)`);
+        for (const id of remaining) {
+          this.t3PeerBus.publish(this.id, id, why, "FAILED");
+          resultMap.set(id, {
+            subtaskId: id,
+            status: "FAILED",
+            output: why,
+            testResults: { checksRun: [], passed: [], failed: [] },
+            issues: [why],
+            peerSyncsUsed: [],
+            correctionAttempts: 0
+          });
+        }
+        remaining.clear();
+        break;
+      }
       const runnableIds = [...remaining].filter((id) => (inDegree.get(id) ?? 0) === 0);
       if (runnableIds.length === 0) {
         const fallbackId = [...remaining].sort(
@@ -7621,8 +7658,32 @@ HIERARCHY CONTEXT: ${this.hierarchyContext}` : ""),
         remaining.delete(id);
         const r = waveResults[i];
         if (r.status === "rejected") {
-          this.log(`T3 worker ${id} failed: ${r.reason instanceof Error ? r.reason.message : String(r.reason)} \u2014 retrying once`);
           const assignment = sanitizedAssignments.find((a) => a.subtaskId === id);
+          const failedModel = workerMap.get(id)?.getServingModel();
+          const tripped = this.runBreaker?.record(r.reason, failedModel);
+          if (tripped) {
+            this.log(`Run breaker opened: ${tripped.failures} consecutive ${tripped.kind} failures on ${tripped.modelId} \u2014 stopping`);
+            this.emit("run:breaker", tripped);
+          }
+          if (this.runBreaker?.isOpen()) {
+            const why = this.runBreaker.skipMessage();
+            this.log(`T3 worker ${id} failed and the run breaker is open \u2014 not retrying`);
+            this.t3PeerBus.publish(this.id, id, why, "FAILED");
+            resultMap.set(id, {
+              subtaskId: id,
+              status: "FAILED",
+              output: why,
+              testResults: { checksRun: [], passed: [], failed: [] },
+              issues: [why],
+              peerSyncsUsed: [],
+              correctionAttempts: 0
+            });
+            for (const dependent of adj.get(id) ?? []) {
+              inDegree.set(dependent, Math.max(0, (inDegree.get(dependent) ?? 0) - 1));
+            }
+            continue;
+          }
+          this.log(`T3 worker ${id} failed: ${r.reason instanceof Error ? r.reason.message : String(r.reason)} \u2014 retrying once`);
           try {
             const retried = await this.retryT3(assignment, taskId);
             resultMap.set(id, retried);
@@ -7954,6 +8015,7 @@ var T1Administrator = class extends BaseTier {
   t2Managers = /* @__PURE__ */ new Map();
   escalations = [];
   store;
+  runBreaker;
   t2PeerBus = new PeerBus();
   permissionEscalator;
   toolCreator;
@@ -7968,6 +8030,10 @@ var T1Administrator = class extends BaseTier {
     this.toolRegistry = toolRegistry;
     this.config = config;
   }
+  /** Share the run-wide circuit breaker with every section manager. */
+  setRunBreaker(breaker) {
+    this.runBreaker = breaker;
+  }
   setStore(store) {
     this.store = store;
   }
@@ -8330,6 +8396,7 @@ SPEC RULES \u2014 each subtask is a self-contained spec slice (workers execute f
     };
     const managers = sections.map((section) => {
       const manager = new T2Manager(this.router, this.toolRegistry, this.id);
+      if (this.runBreaker) manager.setRunBreaker(this.runBreaker);
       manager.setHierarchyContext(`You are a T2 Manager for the section "${section.sectionTitle}". You are part of a COMPLEX task overseen by T1 Administrator.`);
       if (this.store) {
         manager.setStore(this.store);
@@ -8615,6 +8682,158 @@ Reply with exactly one word: YES, NO, or UNSURE.
   }
 };
 
+// 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 = ` 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/run-breaker.ts
+var DEFAULT_FAILURE_THRESHOLD = 3;
+var RunBreaker = class {
+  threshold;
+  /** modelId → consecutive systemic failures of the SAME kind. */
+  counts = /* @__PURE__ */ new Map();
+  trip = null;
+  constructor(threshold = DEFAULT_FAILURE_THRESHOLD) {
+    this.threshold = Math.max(1, threshold);
+  }
+  /**
+   * Record a failed model call. Returns the trip if this failure is the one
+   * that opened the breaker, otherwise null.
+   *
+   * A non-systemic failure RESETS the model's counter: it is evidence the model
+   * is reachable and answering, which is exactly what a systemic streak claims
+   * it is not.
+   */
+  record(err, modelId) {
+    if (this.trip) return null;
+    const id = modelId?.trim() || "unknown-model";
+    const c = classifyProviderError(err);
+    if (!c.systemic) {
+      this.counts.delete(id);
+      return null;
+    }
+    const prev = this.counts.get(id);
+    const n = prev && prev.kind === c.kind ? prev.n + 1 : 1;
+    this.counts.set(id, { kind: c.kind, n, last: c });
+    if (n >= this.threshold) {
+      this.trip = {
+        modelId: id,
+        kind: c.kind,
+        failures: n,
+        message: describeProviderError(c, id)
+      };
+      return this.trip;
+    }
+    return null;
+  }
+  /** True once the run should stop launching work that would fail identically. */
+  isOpen() {
+    return this.trip !== null;
+  }
+  /** Why the breaker opened, or null while it is closed. */
+  reason() {
+    return this.trip;
+  }
+  /**
+   * One line for a worker/section that never ran because the breaker was
+   * already open. Says the work was skipped deliberately — not that it failed
+   * on its own merits, which is what an empty FAILED status would imply.
+   */
+  skipMessage() {
+    const t = this.trip;
+    if (!t) return "Skipped.";
+    return `Skipped \u2014 the run stopped after ${t.failures} consecutive failures on ${t.modelId}. ${t.message}`;
+  }
+  /** Test/diagnostic view of the per-model streaks. */
+  streaks() {
+    const out = {};
+    for (const [k, v] of this.counts) out[k] = { kind: v.kind, n: v.n };
+    return out;
+  }
+};
+
 // src/tools/base.ts
 var BaseTool = class {
   workspaceRoot = process.cwd();
@@ -14187,6 +14406,7 @@ ${prompt}` : prompt;
     if (toolCreator) toolCreator.setPermissionEscalator(escalator);
     const rootPrompt = buildContextualPrompt(options.prompt, options.conversationHistory);
     let finalOutput = "";
+    const runBreaker = new RunBreaker();
     let t2Results = [];
     let runError = null;
     let identityPrompt = "";
@@ -14255,6 +14475,7 @@ ${prompt}` : prompt;
         this.emit("tier:status", { tierId: "t3-root", status: "COMPLETED", role: "T3" });
       } else if (complexity === "Moderate") {
         const t2 = new T2Manager(this.router, this.toolRegistry, "root");
+        t2.setRunBreaker(runBreaker);
         t2.setPresenter(true);
         t2.setHierarchyContext("You are the ROOT Manager for this task. There is no T1 Administrator involved in this run. You are responsible for decomposing the task and managing T3 workers directly.");
         if (identityPrompt) {
@@ -14315,6 +14536,7 @@ _(incomplete: ${reasons.join("; ")})_` : partial;
         }
       } else {
         const t1 = new T1Administrator(this.router, this.toolRegistry, this.config);
+        t1.setRunBreaker(runBreaker);
         t1.setPresenter(true);
         t1.setHierarchyContext("You are the top-level Administrator. You are responsible for the overall plan and supervising multiple T2 Managers.");
         if (identityPrompt) {
@@ -14339,6 +14561,20 @@ _(incomplete: ${reasons.join("; ")})_` : partial;
         finalOutput = result.output;
         t2Results = result.t2Results;
       }
+      const trip = runBreaker.reason();
+      if (trip) {
+        finalOutput = [
+          `\u26A0 **Run stopped early \u2014 ${trip.modelId} was failing every request.**`,
+          "",
+          trip.message,
+          "",
+          `Cascade stopped after ${trip.failures} consecutive failures rather than retrying every remaining subtask against the same model, which would have cost more and produced the same result.`,
+          finalOutput ? `
+---
+
+${finalOutput}` : ""
+        ].join("\n").trimEnd();
+      }
     } catch (err) {
       if (err instanceof CascadeCancelledError || err instanceof Error && err.name === "AbortError" || options.signal?.aborted) {
         this.emit("run:cancelled", {