cascade-ai 0.72.0 → 0.74.0

package/dist/index.d.cts

@@ -1797,6 +1797,33 @@ declare class CascadeRouter extends EventEmitter {
     private sessionCostUsd;
     private runTokens;
     private runCostUsd;
+    /**
+     * Budget held for calls that are IN FLIGHT — admitted by the preflight check
+     * but not yet counted by recordStats. Without these, concurrent calls all
+     * measure themselves against the same unspent allowance and are all admitted.
+     * Released when each call settles; reset by beginRun() alongside the totals.
+     */
+    private reservedTokens;
+    private reservedCostUsd;
+    /**
+     * Fires when this run's budget is spent, cancelling work already in flight.
+     *
+     * The kill switch was previously only a flag, which stops calls that have
+     * not yet submitted. A parallel wave's earlier members are already at the
+     * provider by then, and they carried on generating for a run whose output
+     * would be discarded. Every provider call chains to this, so tripping the
+     * ceiling reaches the requests that are running, not just the ones queued.
+     */
+    private runAbort;
+    /**
+     * Bumped by every beginRun(). A release handle remembers the generation it
+     * was issued in and does nothing if that has moved on: beginRun() zeroes the
+     * counters, so a call still in flight from the previous run would otherwise
+     * subtract its estimate from the NEW run's totals and drive them negative —
+     * leaving later preflights believing there is more allowance than the cap
+     * actually holds, which is worse than no gate at all.
+     */
+    private runGeneration;
     private runBudgetExceeded;
     private runBudgetExceededReason;
     /**
@@ -2036,6 +2063,21 @@ declare class CascadeRouter extends EventEmitter {
      * Used to populate the desktop model pickers with the user's real models.
      */
     getAvailableModels(): ModelInfo[];
+    /**
+     * Why each configured provider failed its availability probe, kept so the
+     * surfaces can say something better than "add an API key" to a user who
+     * already has one. Cleared and refilled by each detectAvailableProviders().
+     */
+    private probeFailures;
+    /**
+     * What stopped the configured providers from being usable, if anything.
+     * Empty when every configured provider passed — or when none was configured,
+     * which is a different problem with a different answer.
+     */
+    providerProbeFailures(): Array<{
+        provider: ProviderType;
+        reason: string;
+    }>;
     /** Logs why a configured provider failed its availability probe. */
     private emitProbeFailure;
     private detectAvailableProviders;
@@ -2046,6 +2088,13 @@ declare class CascadeRouter extends EventEmitter {
     private getProvider;
     private createProvider;
     private getAnyModelForProvider;
+    /**
+     * `runGeneration` is the generation the call was ADMITTED in — see
+     * `generate()`. Session-wide accounting always applies (the spend is real
+     * whenever it lands), but the per-RUN ceiling is only meaningful for the run
+     * the call belongs to, so a straggler from a finished run is left out of it.
+     * Omitted by the direct callers in tests, which have no run to straddle.
+     */
     private recordStats;
     /**
      * Resets per-run accounting at the start of each `cascade run`. Session
@@ -2053,6 +2102,60 @@ declare class CascadeRouter extends EventEmitter {
      * per-task ceiling is cleared so the next task starts with a fresh allowance.
      */
     beginRun(): void;
+    /**
+     * Refuse a call whose input alone cannot fit what is left of the run budget.
+     *
+     * `enforceRunBudget()` below runs AFTER a call returns, which makes the caps
+     * a stop rather than a pre-authorisation: the tokens are already bought by
+     * the time it looks. That was tolerable while a prompt could not exceed
+     * 20,000 characters, and stopped being so when that cap was removed in
+     * 0.72.0 — a multi-megabyte prompt is billed in full on the very first call
+     * (the complexity classifier sends the whole thing), and no ceiling
+     * configured downstream can give that money back.
+     *
+     * Deliberately narrow, because a false refusal is worse than a late stop:
+     *
+     *   • INPUT ONLY. What a call returns is not knowable in advance, and
+     *     charging a worst-case `maxTokens` of output against the budget would
+     *     decline runs that would have finished comfortably. Input is the part
+     *     that is already determined, and it is the part the removed cap used to
+     *     bound.
+     *   • Compared against what REMAINS (`cap - spent`), not the whole cap, so a
+     *     call is judged on the budget it can actually draw from.
+     *   • Skipped when the model has no usable price. An estimate cannot be made,
+     *     and refusing on ignorance would break every self-hosted and local model
+     *     the moment a cost cap is set. The post-hoc stop still applies there.
+     *   • Skipped entirely when no cap is configured — there is nothing to
+     *     pre-authorise against.
+     *
+     * The message names the cap AND the estimate, because "too expensive" with
+     * no numbers gives the user nothing to change.
+     */
+    private enforcePreflightBudget;
+    /**
+     * What this call will send, in tokens.
+     *
+     * Text is the bulk of it, but not all of it: providers bill the serialized
+     * TOOL DEFINITIONS on every native-tool call (Anthropic sends each name,
+     * description and input schema), and an image is billed by its own size
+     * rather than as the `[image]` placeholder `contentToText` reduces it to. A
+     * tool-heavy or vision request could therefore pass either cap while its real
+     * input already exceeded the allowance.
+     */
+    private estimateInputTokens;
+    /**
+     * Report a wait that ended because something asked it to stop, the same way
+     * the provider call below reports one.
+     *
+     * The queue waits sit OUTSIDE the try/catch that maps aborts, so without
+     * this a cancellation surfaced as whatever the queue happened to throw and
+     * was retried or failed over like an ordinary error. A budget abort keeps
+     * saying it ran out of budget — otherwise the reason the run stopped is lost
+     * on the way up — and anything else that was aborted becomes a cancellation.
+     */
+    private asAbortFailure;
+    /** Trips the same run-level flag a post-hoc overrun does, and reports it the same way. */
+    private failPreflight;
     /**
      * Enforce the hard per-task ceiling. Once tripped, the flag makes every
      * subsequent (and concurrent) generate() call in this run fail fast.
@@ -3043,6 +3146,7 @@ interface BroadcastMessage {
     timestamp: string;
 }
 declare class PeerBus extends EventEmitter {
+    constructor();
     private outputs;
     private waiters;
     private members;

package/dist/index.d.ts

@@ -1797,6 +1797,33 @@ declare class CascadeRouter extends EventEmitter {
     private sessionCostUsd;
     private runTokens;
     private runCostUsd;
+    /**
+     * Budget held for calls that are IN FLIGHT — admitted by the preflight check
+     * but not yet counted by recordStats. Without these, concurrent calls all
+     * measure themselves against the same unspent allowance and are all admitted.
+     * Released when each call settles; reset by beginRun() alongside the totals.
+     */
+    private reservedTokens;
+    private reservedCostUsd;
+    /**
+     * Fires when this run's budget is spent, cancelling work already in flight.
+     *
+     * The kill switch was previously only a flag, which stops calls that have
+     * not yet submitted. A parallel wave's earlier members are already at the
+     * provider by then, and they carried on generating for a run whose output
+     * would be discarded. Every provider call chains to this, so tripping the
+     * ceiling reaches the requests that are running, not just the ones queued.
+     */
+    private runAbort;
+    /**
+     * Bumped by every beginRun(). A release handle remembers the generation it
+     * was issued in and does nothing if that has moved on: beginRun() zeroes the
+     * counters, so a call still in flight from the previous run would otherwise
+     * subtract its estimate from the NEW run's totals and drive them negative —
+     * leaving later preflights believing there is more allowance than the cap
+     * actually holds, which is worse than no gate at all.
+     */
+    private runGeneration;
     private runBudgetExceeded;
     private runBudgetExceededReason;
     /**
@@ -2036,6 +2063,21 @@ declare class CascadeRouter extends EventEmitter {
      * Used to populate the desktop model pickers with the user's real models.
      */
     getAvailableModels(): ModelInfo[];
+    /**
+     * Why each configured provider failed its availability probe, kept so the
+     * surfaces can say something better than "add an API key" to a user who
+     * already has one. Cleared and refilled by each detectAvailableProviders().
+     */
+    private probeFailures;
+    /**
+     * What stopped the configured providers from being usable, if anything.
+     * Empty when every configured provider passed — or when none was configured,
+     * which is a different problem with a different answer.
+     */
+    providerProbeFailures(): Array<{
+        provider: ProviderType;
+        reason: string;
+    }>;
     /** Logs why a configured provider failed its availability probe. */
     private emitProbeFailure;
     private detectAvailableProviders;
@@ -2046,6 +2088,13 @@ declare class CascadeRouter extends EventEmitter {
     private getProvider;
     private createProvider;
     private getAnyModelForProvider;
+    /**
+     * `runGeneration` is the generation the call was ADMITTED in — see
+     * `generate()`. Session-wide accounting always applies (the spend is real
+     * whenever it lands), but the per-RUN ceiling is only meaningful for the run
+     * the call belongs to, so a straggler from a finished run is left out of it.
+     * Omitted by the direct callers in tests, which have no run to straddle.
+     */
     private recordStats;
     /**
      * Resets per-run accounting at the start of each `cascade run`. Session
@@ -2053,6 +2102,60 @@ declare class CascadeRouter extends EventEmitter {
      * per-task ceiling is cleared so the next task starts with a fresh allowance.
      */
     beginRun(): void;
+    /**
+     * Refuse a call whose input alone cannot fit what is left of the run budget.
+     *
+     * `enforceRunBudget()` below runs AFTER a call returns, which makes the caps
+     * a stop rather than a pre-authorisation: the tokens are already bought by
+     * the time it looks. That was tolerable while a prompt could not exceed
+     * 20,000 characters, and stopped being so when that cap was removed in
+     * 0.72.0 — a multi-megabyte prompt is billed in full on the very first call
+     * (the complexity classifier sends the whole thing), and no ceiling
+     * configured downstream can give that money back.
+     *
+     * Deliberately narrow, because a false refusal is worse than a late stop:
+     *
+     *   • INPUT ONLY. What a call returns is not knowable in advance, and
+     *     charging a worst-case `maxTokens` of output against the budget would
+     *     decline runs that would have finished comfortably. Input is the part
+     *     that is already determined, and it is the part the removed cap used to
+     *     bound.
+     *   • Compared against what REMAINS (`cap - spent`), not the whole cap, so a
+     *     call is judged on the budget it can actually draw from.
+     *   • Skipped when the model has no usable price. An estimate cannot be made,
+     *     and refusing on ignorance would break every self-hosted and local model
+     *     the moment a cost cap is set. The post-hoc stop still applies there.
+     *   • Skipped entirely when no cap is configured — there is nothing to
+     *     pre-authorise against.
+     *
+     * The message names the cap AND the estimate, because "too expensive" with
+     * no numbers gives the user nothing to change.
+     */
+    private enforcePreflightBudget;
+    /**
+     * What this call will send, in tokens.
+     *
+     * Text is the bulk of it, but not all of it: providers bill the serialized
+     * TOOL DEFINITIONS on every native-tool call (Anthropic sends each name,
+     * description and input schema), and an image is billed by its own size
+     * rather than as the `[image]` placeholder `contentToText` reduces it to. A
+     * tool-heavy or vision request could therefore pass either cap while its real
+     * input already exceeded the allowance.
+     */
+    private estimateInputTokens;
+    /**
+     * Report a wait that ended because something asked it to stop, the same way
+     * the provider call below reports one.
+     *
+     * The queue waits sit OUTSIDE the try/catch that maps aborts, so without
+     * this a cancellation surfaced as whatever the queue happened to throw and
+     * was retried or failed over like an ordinary error. A budget abort keeps
+     * saying it ran out of budget — otherwise the reason the run stopped is lost
+     * on the way up — and anything else that was aborted becomes a cancellation.
+     */
+    private asAbortFailure;
+    /** Trips the same run-level flag a post-hoc overrun does, and reports it the same way. */
+    private failPreflight;
     /**
      * Enforce the hard per-task ceiling. Once tripped, the flag makes every
      * subsequent (and concurrent) generate() call in this run fail fast.
@@ -3043,6 +3146,7 @@ interface BroadcastMessage {
     timestamp: string;
 }
 declare class PeerBus extends EventEmitter {
+    constructor();
     private outputs;
     private waiters;
     private members;