cascade-ai 0.49.0 → 0.51.0

package/dist/index.d.cts

@@ -196,6 +196,12 @@ interface ToolExecuteOptions {
     tierId: string;
     sessionId: string;
     requireApproval: boolean;
+    /**
+     * Cancels a long-running tool call. Media generation can take a minute or
+     * more, so a cancelled run must be able to stop one mid-flight rather than
+     * paying it out and discarding the result.
+     */
+    signal?: AbortSignal;
     saveSnapshot?: (filePath: string, content: string) => Promise<void>;
     sendPeerSync?: (to: string, syncType: PeerSyncType, content: string | Record<string, unknown>) => void;
     getPeerMessages?: () => Array<{
@@ -647,6 +653,11 @@ interface BudgetConfig {
     maxTokensPerRun?: number;
     /** Optional hard per-task cost ceiling (USD). */
     maxCostPerRunUsd?: number;
+    /**
+     * Consecutive systemic failures against one model before the run stops
+     * launching work certain to fail the same way. Default 3.
+     */
+    failureThreshold?: number;
     warnAtPct: number;
 }
 interface WorkspaceConfig {
@@ -977,6 +988,20 @@ declare class ModelPerformanceTracker {
     costEfficiencyScore(model: ModelInfo, complexity: 1 | 2 | 3 | 4 | 5): number;
 }
 
+interface FeedbackCounts {
+    good: number;
+    bad: number;
+}
+/**
+ * Lookup of per-model feedback, keyed by model id.
+ *
+ * Deliberately just counts: no conversation text, no prompts, no timestamps.
+ * A routing prior needs to know that a model earned N good and M bad verdicts
+ * and nothing else, and storing more would put chat content in a second place
+ * with different retention rules for no gain.
+ */
+type FeedbackSource = (modelId: string) => FeedbackCounts | undefined;
+
 type TaskType = 'code' | 'analysis' | 'creative' | 'data' | 'mixed';
 /** Cascade Auto cost/quality trade-off bias. See CascadeConfig.autoBias. */
 type AutoBias = 'balanced' | 'quality' | 'cost';
@@ -992,10 +1017,18 @@ interface TaskProfile {
 }
 declare class TaskAnalyzer {
     private tracker?;
+    /** Per-model thumbs counts, when the host collects them. */
+    private feedback?;
     private bias;
     private lastProfile;
     private lastSelectedModels;
     constructor(tracker?: ModelPerformanceTracker, bias?: AutoBias);
+    /**
+     * Supply per-model rating counts. Optional by design: a host that collects no
+     * feedback (the CLI, a fresh install) scores exactly as it did before, since
+     * feedbackAdjustment returns 0 for an empty record.
+     */
+    setFeedbackSource(source: FeedbackSource): void;
     setTracker(tracker: ModelPerformanceTracker): void;
     /** Change the cost/quality bias at runtime (e.g. when config reloads). */
     setBias(bias: AutoBias): void;
@@ -1463,6 +1496,7 @@ declare class CascadeRouter extends EventEmitter {
     private tpmLimiter;
     private localQueue;
     private taskAnalyzer?;
+    private pendingFeedbackSource?;
     private worldStateDB?;
     private privacyPaths?;
     private guidanceQueue?;
@@ -1578,6 +1612,12 @@ declare class CascadeRouter extends EventEmitter {
      */
     getReferenceContextWindow(): number | undefined;
     /** Wire the Cascade Auto task analyzer used for per-subtask model routing. */
+    /**
+     * Feed per-model thumbs counts into Auto routing. Forwarded to the analyzer
+     * because that is where the public benchmark score is combined; the prior
+     * adjusts that number rather than sitting anywhere else in the pipeline.
+     */
+    setFeedbackSource(source: FeedbackSource): void;
     setTaskAnalyzer(analyzer: TaskAnalyzer): void;
     setWorldStateDB(db: WorldStateDB | undefined): void;
     getWorldStateDB(): WorldStateDB | undefined;
@@ -1858,6 +1898,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 +1919,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 +2121,7 @@ declare class T1Administrator extends BaseTier {
     private t2Managers;
     private escalations;
     private store?;
+    private runBreaker?;
     private t2PeerBus;
     private permissionEscalator?;
     private toolCreator?;
@@ -2029,6 +2131,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.
@@ -2087,6 +2191,7 @@ interface DecisionLogEntry {
 declare class Cascade extends EventEmitter {
     private router;
     private toolRegistry;
+    private multimodal;
     private mcpClient;
     private codeIndex?;
     private config;
@@ -2172,6 +2277,26 @@ declare class Cascade extends EventEmitter {
      * Idempotent init guard, so it works before the first run.
      */
     previewPlan(prompt: string): Promise<TaskPlan>;
+    /**
+     * Register image / speech / transcription tools for the modalities this
+     * config can actually serve.
+     *
+     * The sink writes bytes into the workspace, because that is what a desktop or
+     * CLI run wants and it keeps a generated asset indistinguishable from any
+     * other file the run produced. A host with different storage (the cloud
+     * server stores a file row) constructs the tools itself via buildMediaTools
+     * with its own sink.
+     */
+    private registerMediaTools;
+    /**
+     * Supply per-model thumbs-up/down counts so Auto routing can weigh how models
+     * have actually performed for this user, on top of public benchmarks.
+     *
+     * Optional everywhere: with no source, or an empty record, scoring is
+     * byte-identical to before. The adjustment is capped and sample-size shrunk —
+     * see core/router/feedback-prior.ts.
+     */
+    setFeedbackSource(source: FeedbackSource): void;
     /** True when a task stopped at the budget cap and can be resumed via /continue. */
     hasResumableRun(): boolean;
     /**
@@ -2404,6 +2529,7 @@ declare class T2Manager extends BaseTier {
     private escalations;
     private peerSyncBuffer;
     private store?;
+    private runBreaker?;
     private t3PeerBus;
     private t2PeerBus?;
     private permissionEscalator?;
@@ -2415,6 +2541,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

@@ -196,6 +196,12 @@ interface ToolExecuteOptions {
     tierId: string;
     sessionId: string;
     requireApproval: boolean;
+    /**
+     * Cancels a long-running tool call. Media generation can take a minute or
+     * more, so a cancelled run must be able to stop one mid-flight rather than
+     * paying it out and discarding the result.
+     */
+    signal?: AbortSignal;
     saveSnapshot?: (filePath: string, content: string) => Promise<void>;
     sendPeerSync?: (to: string, syncType: PeerSyncType, content: string | Record<string, unknown>) => void;
     getPeerMessages?: () => Array<{
@@ -647,6 +653,11 @@ interface BudgetConfig {
     maxTokensPerRun?: number;
     /** Optional hard per-task cost ceiling (USD). */
     maxCostPerRunUsd?: number;
+    /**
+     * Consecutive systemic failures against one model before the run stops
+     * launching work certain to fail the same way. Default 3.
+     */
+    failureThreshold?: number;
     warnAtPct: number;
 }
 interface WorkspaceConfig {
@@ -977,6 +988,20 @@ declare class ModelPerformanceTracker {
     costEfficiencyScore(model: ModelInfo, complexity: 1 | 2 | 3 | 4 | 5): number;
 }
 
+interface FeedbackCounts {
+    good: number;
+    bad: number;
+}
+/**
+ * Lookup of per-model feedback, keyed by model id.
+ *
+ * Deliberately just counts: no conversation text, no prompts, no timestamps.
+ * A routing prior needs to know that a model earned N good and M bad verdicts
+ * and nothing else, and storing more would put chat content in a second place
+ * with different retention rules for no gain.
+ */
+type FeedbackSource = (modelId: string) => FeedbackCounts | undefined;
+
 type TaskType = 'code' | 'analysis' | 'creative' | 'data' | 'mixed';
 /** Cascade Auto cost/quality trade-off bias. See CascadeConfig.autoBias. */
 type AutoBias = 'balanced' | 'quality' | 'cost';
@@ -992,10 +1017,18 @@ interface TaskProfile {
 }
 declare class TaskAnalyzer {
     private tracker?;
+    /** Per-model thumbs counts, when the host collects them. */
+    private feedback?;
     private bias;
     private lastProfile;
     private lastSelectedModels;
     constructor(tracker?: ModelPerformanceTracker, bias?: AutoBias);
+    /**
+     * Supply per-model rating counts. Optional by design: a host that collects no
+     * feedback (the CLI, a fresh install) scores exactly as it did before, since
+     * feedbackAdjustment returns 0 for an empty record.
+     */
+    setFeedbackSource(source: FeedbackSource): void;
     setTracker(tracker: ModelPerformanceTracker): void;
     /** Change the cost/quality bias at runtime (e.g. when config reloads). */
     setBias(bias: AutoBias): void;
@@ -1463,6 +1496,7 @@ declare class CascadeRouter extends EventEmitter {
     private tpmLimiter;
     private localQueue;
     private taskAnalyzer?;
+    private pendingFeedbackSource?;
     private worldStateDB?;
     private privacyPaths?;
     private guidanceQueue?;
@@ -1578,6 +1612,12 @@ declare class CascadeRouter extends EventEmitter {
      */
     getReferenceContextWindow(): number | undefined;
     /** Wire the Cascade Auto task analyzer used for per-subtask model routing. */
+    /**
+     * Feed per-model thumbs counts into Auto routing. Forwarded to the analyzer
+     * because that is where the public benchmark score is combined; the prior
+     * adjusts that number rather than sitting anywhere else in the pipeline.
+     */
+    setFeedbackSource(source: FeedbackSource): void;
     setTaskAnalyzer(analyzer: TaskAnalyzer): void;
     setWorldStateDB(db: WorldStateDB | undefined): void;
     getWorldStateDB(): WorldStateDB | undefined;
@@ -1858,6 +1898,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 +1919,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 +2121,7 @@ declare class T1Administrator extends BaseTier {
     private t2Managers;
     private escalations;
     private store?;
+    private runBreaker?;
     private t2PeerBus;
     private permissionEscalator?;
     private toolCreator?;
@@ -2029,6 +2131,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.
@@ -2087,6 +2191,7 @@ interface DecisionLogEntry {
 declare class Cascade extends EventEmitter {
     private router;
     private toolRegistry;
+    private multimodal;
     private mcpClient;
     private codeIndex?;
     private config;
@@ -2172,6 +2277,26 @@ declare class Cascade extends EventEmitter {
      * Idempotent init guard, so it works before the first run.
      */
     previewPlan(prompt: string): Promise<TaskPlan>;
+    /**
+     * Register image / speech / transcription tools for the modalities this
+     * config can actually serve.
+     *
+     * The sink writes bytes into the workspace, because that is what a desktop or
+     * CLI run wants and it keeps a generated asset indistinguishable from any
+     * other file the run produced. A host with different storage (the cloud
+     * server stores a file row) constructs the tools itself via buildMediaTools
+     * with its own sink.
+     */
+    private registerMediaTools;
+    /**
+     * Supply per-model thumbs-up/down counts so Auto routing can weigh how models
+     * have actually performed for this user, on top of public benchmarks.
+     *
+     * Optional everywhere: with no source, or an empty record, scoring is
+     * byte-identical to before. The adjustment is capped and sample-size shrunk —
+     * see core/router/feedback-prior.ts.
+     */
+    setFeedbackSource(source: FeedbackSource): void;
     /** True when a task stopped at the budget cap and can be resumed via /continue. */
     hasResumableRun(): boolean;
     /**
@@ -2404,6 +2529,7 @@ declare class T2Manager extends BaseTier {
     private escalations;
     private peerSyncBuffer;
     private store?;
+    private runBreaker?;
     private t3PeerBus;
     private t2PeerBus?;
     private permissionEscalator?;
@@ -2415,6 +2541,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.