cascade-ai 0.68.0 → 0.69.0

package/dist/index.d.cts

@@ -61,30 +61,69 @@ interface ResumeStoreOptions {
     maxAgeMs?: number;
     /** Injectable clock, for tests. */
     now?: () => number;
+    /** How long a claim may be held before it is considered abandoned. */
+    claimTimeoutMs?: number;
 }
 declare class ResumeStore {
     private readonly dir;
     private readonly maxCheckpoints;
     private readonly maxAgeMs;
     private readonly now;
+    private readonly claimTimeoutMs;
     constructor(options: ResumeStoreOptions);
     /**
-     * Persist a checkpoint and prune. Never throws: failing to save a resume file
-     * must not turn a recoverable stop into a crash, which would be a strictly
-     * worse outcome than the one this store exists to improve.
+     * Persist a checkpoint and prune.
+     *
+     * Never throws — failing to save a resume file must not turn a recoverable
+     * stop into a crash — but DOES report whether the atomic rename landed.
+     * Callers decide whether an original claim is safe to discard based on that
+     * answer, so "I swallowed the error" and "the checkpoint is on disk" must not
+     * look alike to them.
+     *
+     * @returns true only when the checkpoint is durably on disk.
      */
     save(checkpoint: Omit<ResumeCheckpoint, 'version' | 'createdAt'> & {
         createdAt?: string;
-    }): Promise<void>;
+    }): Promise<boolean>;
     /** Valid, unexpired checkpoints, newest first. */
     list(): Promise<ResumeCheckpoint[]>;
     /** The most recent resumable run, or null. */
     latest(): Promise<ResumeCheckpoint | null>;
     /**
-     * Load a checkpoint and delete it in the same step. Resuming twice from one
-     * checkpoint would re-run restored work, so consumption is part of reading.
+     * Claim a checkpoint for a resume attempt.
+     *
+     * This used to DELETE the file and return it, which opened a window with no
+     * recovery record at all: between preparing the continuation and the resumed
+     * run writing its own checkpoint, a crash lost the only copy — and a crash is
+     * precisely what this store exists to survive. Deleting on read optimised for
+     * "never resume twice" at the cost of "never lose the work", which is the
+     * wrong trade for a recovery mechanism.
+     *
+     * Instead the file is RENAMED to `.claimed`, which still hides it from
+     * `list()` (so a concurrent resume cannot take the same work) but keeps it on
+     * disk. The caller then either `release`s it — restoring it for another
+     * attempt — or `settle`s it once the resumed run is safely under way. A claim
+     * abandoned by a dead process is reclaimed after `claimTimeoutMs`.
+     */
+    claim(taskId?: string): Promise<{
+        checkpoint: ResumeCheckpoint;
+        claimId: string;
+    } | null>;
+    /** Give a claim back, so the work stays recoverable after a failed start. */
+    release(claimId: string): Promise<void>;
+    /** Discard a claim for good — the resumed run has taken ownership. */
+    settle(claimId: string): Promise<void>;
+    /**
+     * Claim-and-discard in one step. Kept for callers that genuinely want the old
+     * semantics; prefer claim/settle so a crash mid-resume stays recoverable.
      */
     consume(taskId?: string): Promise<ResumeCheckpoint | null>;
+    /**
+     * Return claims abandoned by a process that died mid-resume. Without this a
+     * crash between claim and settle would strand the checkpoint invisibly —
+     * trading one loss window for another.
+     */
+    reclaimStale(): Promise<number>;
     /** Remove every checkpoint for a task id. */
     delete(taskId: string): Promise<void>;
     /** Drop expired checkpoints, then any beyond the newest `maxCheckpoints`. */
@@ -336,7 +375,17 @@ interface ToolExecuteOptions {
     }>;
 }
 type TierRole = 'T1' | 'T2' | 'T3';
-type TierStatus = 'IDLE' | 'ACTIVE' | 'COMPLETED' | 'FAILED' | 'ESCALATED';
+/**
+ * A tier's lifecycle state.
+ *
+ * BLOCKED is terminal like COMPLETED and FAILED — the tier will never run,
+ * because work it depended on failed first. It is NOT the same word as
+ * `MessageStatus.BLOCKED` below, which means "running but stuck": one describes
+ * a tier that never started, the other a tier that started and cannot finish.
+ * Anything rendering a status label should treat BLOCKED as "skipped", not as
+ * an error and not as in-progress.
+ */
+type TierStatus = 'IDLE' | 'ACTIVE' | 'COMPLETED' | 'FAILED' | 'ESCALATED' | 'BLOCKED';
 type TaskComplexity = 'Simple' | 'Moderate' | 'Complex' | 'Highly Complex';
 interface TierConfig {
     role: TierRole;
@@ -409,10 +458,27 @@ interface StatusUpdate {
 interface T2Result {
     sectionId: string;
     sectionTitle: string;
-    status: 'COMPLETED' | 'PARTIAL' | 'FAILED' | 'ESCALATED';
+    /**
+     * BLOCKED is not a kind of FAILED. A failed section was attempted and did not
+     * work; a blocked one was never attempted, because something it depended on
+     * failed first — so it spent no tokens and says nothing about whether it
+     * would have worked. Reporting it as FAILED (which is what happened until
+     * now) tells the user their work broke when in fact the scheduler protected
+     * them from paying for work that could not succeed yet.
+     */
+    status: 'COMPLETED' | 'PARTIAL' | 'FAILED' | 'ESCALATED' | 'BLOCKED';
     t3Results: T3Result[];
     sectionSummary: string;
     issues: string[];
+    /**
+     * Set only on BLOCKED sections: which upstream work stopped this one, by
+     * title and by id. Structured rather than flattened into `issues`, so a UI
+     * can link a skipped section back to its cause instead of parsing prose.
+     */
+    blockedBy?: {
+        ids: string[];
+        titles: string[];
+    };
     /**
      * Set when this section reached PARTIAL because the user was asked about an
      * escalation and chose "skip" — not because a T2/T3 pipeline shortfall left
@@ -1179,7 +1245,24 @@ declare class TaskAnalyzer {
     private feedback?;
     private bias;
     private lastProfile;
-    private lastSelectedModels;
+    /** Models chosen by the run currently in flight. Cleared when it completes. */
+    private currentRunSelections;
+    /**
+     * Immutable snapshot of the last COMPLETED run: its selections AND the task
+     * type they were chosen for.
+     *
+     * The task type has to travel WITH the selections. `lastProfile` is overwritten
+     * by the next analyze(), so if run B started before the user rated run A, A's
+     * models were credited under B's task type — teaching the router that a coding
+     * model is good at creative writing, from a rating that never said so.
+     *
+     * Explicit ratings arrive after the run finishes — rateLastRun() is by nature
+     * a reaction to a finished answer — but the run finalizer calls
+     * recordRunOutcome() first, and that used to clear the only map there was. So
+     * every explicit rating iterated an empty map, recorded nothing, and returned
+     * false: the 3x-weighted user signal never reached the tracker at all.
+     */
+    private lastCompletedRun?;
     constructor(tracker?: ModelPerformanceTracker, bias?: AutoBias);
     /**
      * Supply per-model rating counts. Optional by design: a host that collects no
@@ -1211,9 +1294,17 @@ declare class TaskAnalyzer {
      */
     recordRunOutcome(outcome: 'success' | 'failure', costByTier: Record<string, number>, contextTokens?: number): void;
     /**
-     * Record an explicit user rating (good/bad) for the last run's selected models.
+     * Record an explicit user rating (good/bad) for the last COMPLETED run's models.
      * Explicit ratings carry 3× the weight of auto-detected outcomes.
-     * Does NOT clear lastSelectedModels — the auto record already did that.
+     *
+     * Reads the completed-run snapshot, not the in-flight map: by the time a user
+     * can rate an answer, the finalizer has already run and the in-flight map is
+     * empty.
+     *
+     * The snapshot is CONSUMED. recordExplicit() weights a rating 3x by recording
+     * three samples, so a double submit would inject six — a stutter on the
+     * button would count as two opinions. Consuming makes a second call a no-op
+     * that reports false, which is what "rate this run" should mean.
      */
     recordExplicitRating(rating: 'good' | 'bad'): boolean;
     private scoreModel;
@@ -2150,9 +2241,49 @@ declare abstract class BaseTier extends EventEmitter {
      * which node (Cockpit node panel / Why panel).
      */
     protected servingModel?: string;
+    /**
+     * This tier's identity IN THE TASK GRAPH — the section or subtask id the
+     * planner assigned — plus where it sat in the dependency order.
+     *
+     * `id` and `graphNodeId` are deliberately different id spaces, and both are
+     * needed. `id` identifies this tier INSTANCE ("T2_a1b2c3d4", minted per
+     * construction); `graphNodeId` identifies the WORK ("s1"), which is what
+     * dependency edges point at. Without the distinction a graph view cannot be
+     * drawn at all: `dependsOn` lists section ids, while every running tier
+     * reports a generated tier id, so every edge would name a node that never
+     * appears in the stream.
+     */
+    protected graphNodeId?: string;
+    protected graphDependsOn?: readonly string[];
+    protected graphWave?: number;
     constructor(role: TierRole, id?: string, parentId?: string);
     /** Mark this tier as the run's presenter (root tier). */
     setPresenter(on?: boolean): void;
+    /**
+     * Record where this tier sits in the compiled task graph.
+     *
+     * Called by whichever tier scheduled this one: the id and edges are known at
+     * construction, the wave only once the scheduler reaches it, so the fields
+     * are set independently rather than all at once.
+     */
+    setGraphPosition(position: {
+        nodeId?: string;
+        dependsOn?: readonly string[];
+        wave?: number;
+    }): void;
+    /**
+     * The graph fields, for spreading into a status payload.
+     *
+     * One helper rather than two literals because `tier:status` is emitted from
+     * two different call sites with two different payload shapes; adding a field
+     * to only one of them makes it arrive intermittently, which is worse for a
+     * consumer than never arriving at all.
+     */
+    protected graphFields(): {
+        nodeId?: string;
+        dependsOn?: string[];
+        waveId?: number;
+    };
     getStatus(): TierStatus;
     protected setStatus(status: TierStatus, output?: string): void;
     /** Record the model serving this tier; future status events carry it. */
@@ -2532,6 +2663,25 @@ declare class Cascade extends EventEmitter {
     private lastInterruptedRun?;
     /** Durable resume checkpoints. See core/orchestration/resume-store.ts. */
     private resumeStore?;
+    /** Claim held by an in-flight resume, settled once the run owns the work. */
+    private claimedResumeId?;
+    /**
+     * Facts inherited from the checkpoint this run is resuming, so its own
+     * checkpoint is cumulative rather than only covering this attempt.
+     */
+    private resumedFrom?;
+    /** Whether THIS run persisted a checkpoint of its own. Drives settle-vs-release. */
+    private wroteCheckpointThisRun;
+    /**
+     * Whether the run reached the end of its normal path.
+     *
+     * NOT the same as `runError == null`: the cancellation and budget handlers
+     * both null `runError` deliberately (an intentional stop is not a telemetry
+     * error) and the breaker path never sets it at all. Treating that as success
+     * meant an immediate cancel — no output, no replacement checkpoint — deleted
+     * the original claim and the finished sections with it.
+     */
+    private completedNormally;
     /** Section results of the CURRENT run, so an interruption can checkpoint them. */
     private currentRunCompleted;
     private initPromise?;
@@ -2732,6 +2882,19 @@ declare class Cascade extends EventEmitter {
         maxTokens?: number;
         taskId?: string;
     }): Promise<string | null>;
+    /**
+     * Discard the claimed checkpoint once the resumed run has taken ownership of
+     * the work (it has produced its own checkpoint, or finished). Called by the
+     * run loop; safe to call when nothing is claimed.
+     */
+    private settleClaimedResume;
+    /**
+     * Hand back a claim taken by prepareDurableResume() when the caller never
+     * gets as far as run(). The REPL prepares the continuation and submits it
+     * separately, so a failure in between would otherwise strand the checkpoint
+     * for the whole lease timeout before reclaimStale() could recover it.
+     */
+    releaseClaimedResume(): Promise<void>;
     /** A resume gets a bigger budget — the previous attempt exhausted the old one. */
     private raiseBudgetForResume;
     /**
@@ -3215,17 +3378,67 @@ declare class TaskGraphValidationError extends Error {
 declare function compileTaskGraph<TPayload>(inputNodes: readonly TaskGraphInputNode<TPayload>[], options?: CompileTaskGraphOptions): CompiledTaskGraph<TPayload>;
 
 type SchedulerExecutionMode = 'parallel' | 'sequential';
+/**
+ * How a finished node turned out.
+ *
+ * The scheduler used to know only "the promise resolved", which is not the same
+ * question. T1 catches worker errors into an ordinary `T2Result { status:
+ * 'FAILED' }` so one dead section cannot crash the run — a resolved value. The
+ * scheduler saw success and released the dependents anyway, so "run the
+ * integration tests" would start after "implement the API" had failed outright,
+ * and then fail too, and bill for the privilege.
+ *
+ * `partial` deliberately does NOT block: partial output is usable, and treating
+ * it as failure would cancel work that a degraded-but-real result can support.
+ */
+type NodeOutcome = 'succeeded' | 'partial' | 'failed';
+/** What to do with the dependents of a failed node. */
+type UpstreamFailurePolicy = 
+/** Run them anyway — the historical behaviour, kept as the default. */
+'continue'
+/** Skip them, transitively, and report why. */
+ | 'block';
+/** Why a node never ran. */
+interface BlockedNode {
+    /**
+     * Ids of the failed ancestors responsible, nearest first. Stable and
+     * machine-readable — use these to link a blocked node back to its cause.
+     */
+    blockedBy: string[];
+    /**
+     * The same ancestors by title, in the same order. Node ids are internal
+     * ("s1", "s2"); anything a person reads should use these instead.
+     */
+    blockedByTitles: string[];
+    /** A sentence naming the cause, written with titles rather than ids. */
+    reason: string;
+}
 interface SchedulerHooks<TPayload, TResult> {
     execute(node: TaskGraphNode<TPayload>): Promise<TResult>;
     onWaveStart?(nodes: readonly TaskGraphNode<TPayload>[], wave: number): void | Promise<void>;
     onNodeComplete?(node: TaskGraphNode<TPayload>, result: TResult): void | Promise<void>;
+    /**
+     * Decide whether a result counts as success. Omit it and every result counts
+     * as `succeeded`, which is exactly the previous behaviour — so adding failure
+     * awareness to a caller is opt-in and cannot silently change an existing one.
+     */
+    classify?(node: TaskGraphNode<TPayload>, result: TResult): NodeOutcome;
+    /**
+     * A node that will never run because an ancestor failed. Callers use this to
+     * synthesize a result for it, so downstream reporting still sees every node.
+     */
+    onNodeBlocked?(node: TaskGraphNode<TPayload>, blocked: BlockedNode): void | Promise<void>;
 }
 interface SchedulerOptions {
     mode?: SchedulerExecutionMode;
+    /** Defaults to 'continue' so existing callers behave exactly as before. */
+    onUpstreamFailure?: UpstreamFailurePolicy;
 }
 interface SchedulerResult<TResult> {
     results: ReadonlyMap<string, TResult>;
     waves: readonly (readonly string[])[];
+    /** Nodes skipped because an ancestor failed. Empty under 'continue'. */
+    blocked: ReadonlyMap<string, BlockedNode>;
 }
 /**
  * Shared deterministic dependency scheduler for T1 sections and T2 subtasks.
@@ -3507,7 +3720,13 @@ declare class DashboardSocket {
     broadcastToRoom(room: string, event: string, data: unknown): void;
     broadcast(event: string, data: unknown): void;
     emitCascadeEvent(ev: CascadeEvent): void;
-    emitTierStatus(tierId: string, role: string, status: string, sessionId: string, action?: string): void;
+    /**
+     * `extra` exists because this signature is positional: every field the tier
+     * emits that is not named here is silently dropped on this path, while the
+     * other two forwarders spread the whole event through. That asymmetry is how
+     * a field can reach the web dashboard from one code path and not another.
+     */
+    emitTierStatus(tierId: string, role: string, status: string, sessionId: string, action?: string, extra?: Record<string, unknown>): void;
     emitStreamToken(tierId: string, text: string, sessionId: string): void;
     emitPeerMessage(event: PeerMessageEvent): void;
     emitApprovalRequest(request: PermissionRequest): void;