cascade-ai 0.48.1 → 0.50.0

package/dist/index.d.cts

@@ -17,6 +17,21 @@ interface ModelInfo {
     maxOutputTokens: number;
     supportsStreaming: boolean;
     isLocal: boolean;
+    /**
+     * True when Cascade has NO price for this model — the cost fields above are
+     * 0 only because there is nothing to put in them.
+     *
+     * This exists because 0 is ambiguous: a local Ollama model genuinely costs
+     * nothing, while a newly-released cloud preview model that isn't in the
+     * pricing dataset costs real money we can't quote. Treating the second like
+     * the first made unknown-priced models report $0.00 spend, put them outside
+     * the reach of the per-run cost cap, and gave them the best possible score in
+     * the value-based rankers. Anything that reads the cost fields must consult
+     * this flag first (see `isPricingUnknown` in core/router/pricing.ts).
+     *
+     * Never set on local models — their $0 is real.
+     */
+    pricingUnknown?: boolean;
     minSizeB?: number;
     /** Tool-use capability. False for Ollama; true for all cloud providers. */
     supportsToolUse?: boolean;
@@ -46,6 +61,25 @@ interface ProviderConfig {
     authToken?: string;
     /** Where an adopted credential came from, e.g. "Claude Code". Informational. */
     credentialSource?: string;
+    /**
+     * Local-vs-hosted toggle. `true` declares "this endpoint runs on hardware I
+     * already pay for, so inference genuinely costs $0"; `false` declares it is a
+     * paid hosted endpoint, so an unpriced model there reports "cost not tracked"
+     * rather than free.
+     *
+     * Only meaningful for `ollama` and `openai-compatible`, which can each point
+     * at either. Left unset, it defaults sensibly: ollama ⇒ local, and
+     * openai-compatible ⇒ local when `baseUrl` is loopback/LAN (llama.cpp, LM
+     * Studio, vLLM on your own box) and hosted otherwise (Together, Groq, …).
+     * See `isLocalEndpoint` in core/router/pricing.ts.
+     */
+    local?: boolean;
+    /**
+     * Deployment region for providers whose price varies by region (Azure lists
+     * different rates for `global`, `us` and `eu` deployments of the same model).
+     * Matched against the pricing dataset's per-region entries.
+     */
+    region?: string;
 }
 interface StreamChunk {
     text: string;
@@ -57,6 +91,13 @@ interface TokenUsage {
     outputTokens: number;
     totalTokens: number;
     estimatedCostUsd: number;
+    /**
+     * True when `estimatedCostUsd` is 0 because the model's price is UNKNOWN, not
+     * because the call was free. Cost readouts must say "not tracked" for these
+     * rather than "$0.00", and budget code must know the spend it just recorded
+     * is an undercount.
+     */
+    costUnknown?: boolean;
 }
 interface GenerateOptions {
     messages: ConversationMessage[];
@@ -1095,6 +1136,25 @@ interface DelegationSavings {
 
 type BenchmarkProfile = Partial<Record<Exclude<TaskType, 'mixed'>, number>>;
 
+interface PriceDisagreement {
+    modelId: string;
+    provider: string;
+    /** Per-1k rates the bundled dataset asserts. */
+    dataset: {
+        input: number;
+        output: number;
+    };
+    /** Per-1k rates the live source asserts. */
+    live: {
+        input: number;
+        output: number;
+    };
+    /** live/dataset ratio on the blended rate; >1 means live is more expensive. */
+    ratio: number;
+    datasetAsOf: string;
+    datasetSource: string;
+}
+
 type DataSource = 'live' | 'cache' | 'bundled';
 interface PriceEntry {
     input: number;
@@ -1126,6 +1186,8 @@ declare class LiveDataProvider {
     private snapshot;
     private prices;
     private capabilities;
+    /** Dataset-vs-live price mismatches, deduped by `provider:modelId`. */
+    private disagreements;
     private source;
     private fetchedAt;
     private loaded;
@@ -1156,8 +1218,25 @@ declare class LiveDataProvider {
     /**
      * Returns a price-corrected copy of each model when live pricing is known,
      * leaving the original untouched (so the shared catalog is never mutated).
+     *
+     * Reconciliation policy (see reconcilePrice in pricing.ts): the bundled
+     * dataset is the authoritative baseline, and a live quote overrides it
+     * because it is fresher by construction — but the disagreement is RECORDED,
+     * not swallowed. A dataset/live mismatch is the best signal available that
+     * the committed prices have gone stale, so it must be visible rather than
+     * silently resolved in either direction. A live quote of $0 for a non-local
+     * model is rejected outright: that is the very failure mode this change
+     * exists to prevent, and a marketplace's free-tier alias must never zero out
+     * the price of the paid model Cascade is actually calling.
      */
     applyLivePricing(models: ModelInfo[]): ModelInfo[];
+    private recordDisagreement;
+    /**
+     * Dataset-vs-live price mismatches seen this session, newest-model-first
+     * insertion order. Surfaced by `cascade models --verbose`; a non-empty list
+     * means src/core/router/pricing-data.json is probably due a refresh.
+     */
+    getPriceDisagreements(): PriceDisagreement[];
     /** Current capability facts for a model id, or null when unknown. */
     getCapability(modelId: string): CapabilityEntry | null;
     /**
@@ -1345,6 +1424,14 @@ interface RouterStats {
     outputTokensByTier: Record<string, number>;
     /** Accumulated cost (USD) broken down by feature tag (e.g. T2 section names). */
     costByFeature: Record<string, number>;
+    /**
+     * Calls made against models Cascade has no price for. Their spend is NOT in
+     * `totalCostUsd` — it can't be — so a non-zero count here means the totals
+     * above (and any budget check derived from them) are an undercount.
+     */
+    untrackedCostCalls: number;
+    /** Ids of the models responsible, for "cost not tracked for: …" readouts. */
+    untrackedCostModels: string[];
 }
 declare class CascadeRouter extends EventEmitter {
     private selector;
@@ -1771,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;
@@ -1786,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>;
 /**
@@ -1933,6 +2081,7 @@ declare class T1Administrator extends BaseTier {
     private t2Managers;
     private escalations;
     private store?;
+    private runBreaker?;
     private t2PeerBus;
     private permissionEscalator?;
     private toolCreator?;
@@ -1942,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.
@@ -2317,6 +2468,7 @@ declare class T2Manager extends BaseTier {
     private escalations;
     private peerSyncBuffer;
     private store?;
+    private runBreaker?;
     private t3PeerBus;
     private t2PeerBus?;
     private permissionEscalator?;
@@ -2328,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

@@ -17,6 +17,21 @@ interface ModelInfo {
     maxOutputTokens: number;
     supportsStreaming: boolean;
     isLocal: boolean;
+    /**
+     * True when Cascade has NO price for this model — the cost fields above are
+     * 0 only because there is nothing to put in them.
+     *
+     * This exists because 0 is ambiguous: a local Ollama model genuinely costs
+     * nothing, while a newly-released cloud preview model that isn't in the
+     * pricing dataset costs real money we can't quote. Treating the second like
+     * the first made unknown-priced models report $0.00 spend, put them outside
+     * the reach of the per-run cost cap, and gave them the best possible score in
+     * the value-based rankers. Anything that reads the cost fields must consult
+     * this flag first (see `isPricingUnknown` in core/router/pricing.ts).
+     *
+     * Never set on local models — their $0 is real.
+     */
+    pricingUnknown?: boolean;
     minSizeB?: number;
     /** Tool-use capability. False for Ollama; true for all cloud providers. */
     supportsToolUse?: boolean;
@@ -46,6 +61,25 @@ interface ProviderConfig {
     authToken?: string;
     /** Where an adopted credential came from, e.g. "Claude Code". Informational. */
     credentialSource?: string;
+    /**
+     * Local-vs-hosted toggle. `true` declares "this endpoint runs on hardware I
+     * already pay for, so inference genuinely costs $0"; `false` declares it is a
+     * paid hosted endpoint, so an unpriced model there reports "cost not tracked"
+     * rather than free.
+     *
+     * Only meaningful for `ollama` and `openai-compatible`, which can each point
+     * at either. Left unset, it defaults sensibly: ollama ⇒ local, and
+     * openai-compatible ⇒ local when `baseUrl` is loopback/LAN (llama.cpp, LM
+     * Studio, vLLM on your own box) and hosted otherwise (Together, Groq, …).
+     * See `isLocalEndpoint` in core/router/pricing.ts.
+     */
+    local?: boolean;
+    /**
+     * Deployment region for providers whose price varies by region (Azure lists
+     * different rates for `global`, `us` and `eu` deployments of the same model).
+     * Matched against the pricing dataset's per-region entries.
+     */
+    region?: string;
 }
 interface StreamChunk {
     text: string;
@@ -57,6 +91,13 @@ interface TokenUsage {
     outputTokens: number;
     totalTokens: number;
     estimatedCostUsd: number;
+    /**
+     * True when `estimatedCostUsd` is 0 because the model's price is UNKNOWN, not
+     * because the call was free. Cost readouts must say "not tracked" for these
+     * rather than "$0.00", and budget code must know the spend it just recorded
+     * is an undercount.
+     */
+    costUnknown?: boolean;
 }
 interface GenerateOptions {
     messages: ConversationMessage[];
@@ -1095,6 +1136,25 @@ interface DelegationSavings {
 
 type BenchmarkProfile = Partial<Record<Exclude<TaskType, 'mixed'>, number>>;
 
+interface PriceDisagreement {
+    modelId: string;
+    provider: string;
+    /** Per-1k rates the bundled dataset asserts. */
+    dataset: {
+        input: number;
+        output: number;
+    };
+    /** Per-1k rates the live source asserts. */
+    live: {
+        input: number;
+        output: number;
+    };
+    /** live/dataset ratio on the blended rate; >1 means live is more expensive. */
+    ratio: number;
+    datasetAsOf: string;
+    datasetSource: string;
+}
+
 type DataSource = 'live' | 'cache' | 'bundled';
 interface PriceEntry {
     input: number;
@@ -1126,6 +1186,8 @@ declare class LiveDataProvider {
     private snapshot;
     private prices;
     private capabilities;
+    /** Dataset-vs-live price mismatches, deduped by `provider:modelId`. */
+    private disagreements;
     private source;
     private fetchedAt;
     private loaded;
@@ -1156,8 +1218,25 @@ declare class LiveDataProvider {
     /**
      * Returns a price-corrected copy of each model when live pricing is known,
      * leaving the original untouched (so the shared catalog is never mutated).
+     *
+     * Reconciliation policy (see reconcilePrice in pricing.ts): the bundled
+     * dataset is the authoritative baseline, and a live quote overrides it
+     * because it is fresher by construction — but the disagreement is RECORDED,
+     * not swallowed. A dataset/live mismatch is the best signal available that
+     * the committed prices have gone stale, so it must be visible rather than
+     * silently resolved in either direction. A live quote of $0 for a non-local
+     * model is rejected outright: that is the very failure mode this change
+     * exists to prevent, and a marketplace's free-tier alias must never zero out
+     * the price of the paid model Cascade is actually calling.
      */
     applyLivePricing(models: ModelInfo[]): ModelInfo[];
+    private recordDisagreement;
+    /**
+     * Dataset-vs-live price mismatches seen this session, newest-model-first
+     * insertion order. Surfaced by `cascade models --verbose`; a non-empty list
+     * means src/core/router/pricing-data.json is probably due a refresh.
+     */
+    getPriceDisagreements(): PriceDisagreement[];
     /** Current capability facts for a model id, or null when unknown. */
     getCapability(modelId: string): CapabilityEntry | null;
     /**
@@ -1345,6 +1424,14 @@ interface RouterStats {
     outputTokensByTier: Record<string, number>;
     /** Accumulated cost (USD) broken down by feature tag (e.g. T2 section names). */
     costByFeature: Record<string, number>;
+    /**
+     * Calls made against models Cascade has no price for. Their spend is NOT in
+     * `totalCostUsd` — it can't be — so a non-zero count here means the totals
+     * above (and any budget check derived from them) are an undercount.
+     */
+    untrackedCostCalls: number;
+    /** Ids of the models responsible, for "cost not tracked for: …" readouts. */
+    untrackedCostModels: string[];
 }
 declare class CascadeRouter extends EventEmitter {
     private selector;
@@ -1771,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;
@@ -1786,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>;
 /**
@@ -1933,6 +2081,7 @@ declare class T1Administrator extends BaseTier {
     private t2Managers;
     private escalations;
     private store?;
+    private runBreaker?;
     private t2PeerBus;
     private permissionEscalator?;
     private toolCreator?;
@@ -1942,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.
@@ -2317,6 +2468,7 @@ declare class T2Manager extends BaseTier {
     private escalations;
     private peerSyncBuffer;
     private store?;
+    private runBreaker?;
     private t3PeerBus;
     private t2PeerBus?;
     private permissionEscalator?;
@@ -2328,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.