cascade-ai 0.71.0 → 0.73.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;
     /**
@@ -2046,6 +2073,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 +2087,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.
@@ -2179,6 +2267,16 @@ declare class ToolRegistry extends EventEmitter {
     private plugins;
     constructor(config: ToolsConfig, workspaceRoot?: string);
     register(tool: BaseTool): void;
+    /**
+     * The directory every registered tool resolves relative paths against.
+     *
+     * Exposed so a caller that has to reason about a file a tool WROTE can look
+     * in the same place the tool wrote it. `process.cwd()` is not that place
+     * outside a plain CLI run: the hosted server's cwd is the app directory
+     * while the run's workspace is the tenant's scratch dir, and Electron's cwd
+     * is the app bundle rather than the user's chosen folder.
+     */
+    getWorkspaceRoot(): string;
     /**
      * Wait until a named tool is registered, resolving immediately if it already exists.
      * T3 workers can call this after encountering a missing-tool error to resume
@@ -3033,6 +3131,7 @@ interface BroadcastMessage {
     timestamp: string;
 }
 declare class PeerBus extends EventEmitter {
+    constructor();
     private outputs;
     private waiters;
     private members;
@@ -3294,6 +3393,20 @@ declare class T3Worker extends BaseTier {
      */
     private coordinateFileIntents;
     private requiresArtifact;
+    /**
+     * Where a file a tool wrote actually lives.
+     *
+     * This used to be `process.cwd()`, which is only the workspace in a plain
+     * CLI run. The hosted server runs with cwd at the app directory while the
+     * run's workspace is the tenant's scratch dir, and Electron's cwd is the app
+     * bundle rather than the folder the user picked. So the tool wrote
+     * `<workspace>/report.docx`, verification stat'd `<cwd>/report.docx`, found
+     * nothing, and the worker looped and then threw WorkerStallError — surfacing
+     * as "no file was created" on a file that had in fact been created, followed
+     * by a failed node. Asking the registry is exact: it is the same root every
+     * registered tool was configured with (registry.registerDefaults).
+     */
+    private artifactRoot;
     private extractArtifactPaths;
     private verifyArtifacts;
     /**

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;
     /**
@@ -2046,6 +2073,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 +2087,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.
@@ -2179,6 +2267,16 @@ declare class ToolRegistry extends EventEmitter {
     private plugins;
     constructor(config: ToolsConfig, workspaceRoot?: string);
     register(tool: BaseTool): void;
+    /**
+     * The directory every registered tool resolves relative paths against.
+     *
+     * Exposed so a caller that has to reason about a file a tool WROTE can look
+     * in the same place the tool wrote it. `process.cwd()` is not that place
+     * outside a plain CLI run: the hosted server's cwd is the app directory
+     * while the run's workspace is the tenant's scratch dir, and Electron's cwd
+     * is the app bundle rather than the user's chosen folder.
+     */
+    getWorkspaceRoot(): string;
     /**
      * Wait until a named tool is registered, resolving immediately if it already exists.
      * T3 workers can call this after encountering a missing-tool error to resume
@@ -3033,6 +3131,7 @@ interface BroadcastMessage {
     timestamp: string;
 }
 declare class PeerBus extends EventEmitter {
+    constructor();
     private outputs;
     private waiters;
     private members;
@@ -3294,6 +3393,20 @@ declare class T3Worker extends BaseTier {
      */
     private coordinateFileIntents;
     private requiresArtifact;
+    /**
+     * Where a file a tool wrote actually lives.
+     *
+     * This used to be `process.cwd()`, which is only the workspace in a plain
+     * CLI run. The hosted server runs with cwd at the app directory while the
+     * run's workspace is the tenant's scratch dir, and Electron's cwd is the app
+     * bundle rather than the folder the user picked. So the tool wrote
+     * `<workspace>/report.docx`, verification stat'd `<cwd>/report.docx`, found
+     * nothing, and the worker looped and then threw WorkerStallError — surfacing
+     * as "no file was created" on a file that had in fact been created, followed
+     * by a failed node. Asking the registry is exact: it is the same root every
+     * registered tool was configured with (registry.registerDefaults).
+     */
+    private artifactRoot;
     private extractArtifactPaths;
     private verifyArtifacts;
     /**