cascade-ai 0.12.24 → 0.13.2

package/dist/index.d.cts

@@ -64,6 +64,14 @@ interface GenerateOptions {
      * concurrent workers rely on. Ignored when a vision model is required.
      */
     model?: ModelInfo;
+    /** Name/tag of the current sub-feature (e.g. T2 section title) for cost accounting. */
+    featureTag?: string;
+    /**
+     * Privacy-tier constraint: when set, the call must resolve to a LOCAL model
+     * (never a cloud provider). The router errors if no local model is available
+     * rather than silently falling back to cloud.
+     */
+    forceLocal?: boolean;
 }
 interface GenerateResult {
     content: string;
@@ -189,6 +197,7 @@ interface T2ToT3Assignment {
     constraints: string[];
     peerT3Ids: string[];
     parentT2: string;
+    sectionTitle?: string;
     dependsOn?: string[];
     executionMode?: 'parallel' | 'sequential';
 }
@@ -218,6 +227,8 @@ interface T3ResultPayload {
     issues: string[];
     peerSyncsUsed: string[];
     correctionAttempts: number;
+    /** True when the subtask matched a privacy.paths local-only pattern — its raw output must be withheld from upper tiers. */
+    localOnly?: boolean;
     /** Sibling workers this T3 asked its T2 to spawn (T3→T2 reinforcement request). */
     reinforcements?: T2ToT3Assignment[];
 }
@@ -406,6 +417,26 @@ interface CascadeConfig {
         enabled?: boolean;
         maxPerSection?: number;
     };
+    /**
+     * Per-path privacy tiers. Paths matching a `local-only` pattern force the
+     * subtask onto LOCAL models and withhold raw output from the tiers above
+     * (T1/T2 see only success/fail). Patterns use .gitignore syntax, like
+     * .cascadeignore.
+     */
+    privacy?: {
+        paths?: Array<{
+            pattern: string;
+            policy: 'local-only';
+        }>;
+    };
+    /**
+     * Routing controls. `forceTier` pins the run's root tier — 'T1' (full
+     * hierarchy), 'T2' (manager + workers), 'T3' (single worker) — bypassing the
+     * complexity classifier. 'auto' (default) uses classification.
+     */
+    routing?: {
+        forceTier?: 'auto' | 'T1' | 'T2' | 'T3';
+    };
     /** Render the TUI in the alternate screen buffer (vim-style). Default: false. */
     altScreen?: boolean;
 }
@@ -496,6 +527,7 @@ interface WorkspaceConfig {
     configPath: string;
     keystorePath: string;
     auditLogPath: string;
+    debugWorldState?: boolean;
 }
 type CascadeThemeName = 'midnight' | 'aurora' | 'ember' | 'tide' | 'bloom' | 'daybreak';
 type LegacyThemeName = 'cascade' | 'dark' | 'light' | 'dracula' | 'nord' | 'solarized';
@@ -571,6 +603,19 @@ interface PermissionRequest {
      * auto-approve a later dangerous action.
      */
     forceReprompt?: boolean;
+    /**
+     * Escalation trail — each engaged tier's non-binding recommendation as the
+     * request rose toward the user. Dangerous tools never get a terminal
+     * decision from a tier; the tier records its advice here instead, so the
+     * user sees who asked and what T2/T1 thought.
+     */
+    trail?: PermissionTrailEntry[];
+}
+/** One tier's advisory verdict recorded while a request escalated upward. */
+interface PermissionTrailEntry {
+    tier: 'T2' | 'T1';
+    verdict: 'approve' | 'deny' | 'unsure';
+    reason?: string;
 }
 /**
  * A decision made at any tier (T2, T1, or USER) about a PermissionRequest.
@@ -653,6 +698,8 @@ interface CascadeRunResult {
     costByTier?: Record<string, number>;
     /** Per-tier total token counts. Available when the router tracked stats. */
     tokensByTier?: Record<string, number>;
+    /** Per-feature (T2 section) cost breakdown (USD) — "what did this feature cost?". */
+    costByFeature?: Record<string, number>;
     /** Per-tier cost as a percentage of total spend (0–100). */
     costPercentByTier?: Record<string, number>;
 }
@@ -700,14 +747,20 @@ interface ModelStat {
     totalCostUsd: number;
     sampleCount: number;
 }
+interface FeatureStat {
+    totalCostUsd: number;
+    runCount: number;
+}
 declare class ModelPerformanceTracker {
     private stats;
+    private featureStats;
     private readonly statsFile;
     private loaded;
     constructor(statsFile?: string);
     load(): Promise<void>;
     save(): Promise<void>;
     record(modelId: string, taskType: TaskType, outcome: 'success' | 'failure', retries?: number, costUsd?: number): void;
+    recordFeatureCost(featureTag: string, costUsd: number): void;
     /**
      * Record an explicit user rating (good/bad). Counts as 3 automatic samples
      * so user feedback carries significantly more weight than auto-detected outcomes.
@@ -715,6 +768,7 @@ declare class ModelPerformanceTracker {
     recordExplicit(modelId: string, taskType: TaskType, rating: 'good' | 'bad', costUsd?: number): void;
     /** Returns all stats keyed by "modelId:taskType" — used by `cascade stats`. */
     getAll(): Map<string, ModelStat>;
+    getAllFeatures(): Map<string, FeatureStat>;
     /**
      * Returns 0.05–1.0; defaults to 0.5 (neutral prior) when no history exists.
      * High retry counts penalise the score.
@@ -916,6 +970,65 @@ declare class LiveDataProvider {
     hasLivePricing(): boolean;
 }
 
+interface WorldStateEntry {
+    id: string;
+    timestamp: string;
+    summary: string;
+    workerId: string;
+}
+declare class WorldStateDB {
+    private workspacePath;
+    private debugMode;
+    private db;
+    private keyPath;
+    private dbPath;
+    private encryptionKey;
+    constructor(workspacePath: string, debugMode?: boolean);
+    private initEncryptionKey;
+    private encrypt;
+    private decrypt;
+    addEntry(workerId: string, summary: string): string;
+    getAllEntries(): WorldStateEntry[];
+    getFormattedState(): string;
+    private dumpDebugIfNeeded;
+    close(): void;
+}
+
+interface PrivacyPathPolicy {
+    pattern: string;
+    policy: 'local-only';
+}
+declare class PrivacyPaths {
+    private localOnly;
+    private hasRules;
+    constructor(policies?: PrivacyPathPolicy[]);
+    /** True when any privacy rules are configured at all (cheap short-circuit). */
+    hasPolicies(): boolean;
+    /** True when the given workspace-relative path falls under a local-only policy. */
+    isLocalOnly(relativePath: string): boolean;
+    /** True when ANY of the given paths falls under a local-only policy. */
+    anyLocalOnly(relativePaths: string[]): boolean;
+}
+
+interface GuidanceEntry {
+    text: string;
+    /** Target a specific tier node (exact id or id prefix). Omitted = every worker. */
+    nodeId?: string;
+    timestamp: string;
+}
+declare class GuidanceQueue {
+    private entries;
+    /** Per-consumer read cursor so a broadcast entry reaches each worker once. */
+    private cursors;
+    push(text: string, nodeId?: string): GuidanceEntry;
+    /**
+     * New entries for this consumer since its last drain, filtered to entries
+     * that target it (or target everyone). Advances the consumer's cursor.
+     */
+    drain(consumerId: string): GuidanceEntry[];
+    get size(): number;
+}
+
 interface RouterStats {
     totalTokens: number;
     totalCostUsd: number;
@@ -928,6 +1041,8 @@ interface RouterStats {
     /** Input and output token counts per tier for granular cost analysis. */
     inputTokensByTier: Record<string, number>;
     outputTokensByTier: Record<string, number>;
+    /** Accumulated cost (USD) broken down by feature tag (e.g. T2 section names). */
+    costByFeature: Record<string, number>;
 }
 declare class CascadeRouter extends EventEmitter {
     private selector;
@@ -952,6 +1067,9 @@ declare class CascadeRouter extends EventEmitter {
     private tpmLimiter;
     private localQueue;
     private taskAnalyzer?;
+    private worldStateDB?;
+    private privacyPaths?;
+    private guidanceQueue?;
     private liveData?;
     /** Snapshot of configured/default tier models, taken before Cascade Auto overrides them. */
     private originalTierModels?;
@@ -1032,6 +1150,19 @@ declare class CascadeRouter extends EventEmitter {
     getSelector(): ModelSelector;
     /** Wire the Cascade Auto task analyzer used for per-subtask model routing. */
     setTaskAnalyzer(analyzer: TaskAnalyzer): void;
+    setWorldStateDB(db: WorldStateDB | undefined): void;
+    getWorldStateDB(): WorldStateDB | undefined;
+    setPrivacyPaths(paths: PrivacyPaths | undefined): void;
+    getPrivacyPaths(): PrivacyPaths | undefined;
+    setGuidanceQueue(queue: GuidanceQueue | undefined): void;
+    getGuidanceQueue(): GuidanceQueue | undefined;
+    /**
+     * "Private" = inference never leaves the user's machine/network: Ollama
+     * models (isLocal), or an OpenAI-compatible endpoint (e.g. llama.cpp, vLLM,
+     * LM Studio) whose configured host is loopback or a private range. A cloud
+     * OpenAI-compatible endpoint (public host) does NOT qualify.
+     */
+    private isPrivateModel;
     /**
      * Cascade Auto per-subtask routing: pick the benchmark-best model for a
      * specific subtask's text, scoped to the tier's eligible candidates. Returns
@@ -1264,7 +1395,16 @@ declare abstract class BaseTier extends EventEmitter {
     protected hierarchyContext: string;
     /** Propagated AbortSignal — set by the tier's `execute()` before work begins. */
     protected signal?: AbortSignal;
+    /**
+     * True for the run's ROOT tier (T3 for Simple, T2 for Moderate, T1 for
+     * Complex). Its own synthesis stream is the user-facing answer and is
+     * tagged `primary` so the desktop renders it live — background workers,
+     * which would interleave, are not tagged.
+     */
+    protected isPresenter: boolean;
     constructor(role: TierRole, id?: string, parentId?: string);
+    /** Mark this tier as the run's presenter (root tier). */
+    setPresenter(on?: boolean): void;
     getStatus(): TierStatus;
     protected setStatus(status: TierStatus, output?: string): void;
     protected setLabel(label: string): void;
@@ -1491,8 +1631,17 @@ declare class Cascade extends EventEmitter {
     private taskAnalyzer?;
     private perfTracker?;
     private toolCreator?;
+    private worldStateDB?;
+    private encryptedAuditLogger?;
+    private guidanceQueue;
     private workspacePath;
     constructor(config: CascadeConfig, workspacePath: string, store?: MemoryStore);
+    /**
+     * Live intervention: inject a user correction into the running hierarchy.
+     * Every active T3 worker (or only the one matching `nodeId`) picks it up at
+     * the top of its next agent-loop iteration as a USER INTERVENTION message.
+     */
+    injectGuidance(text: string, nodeId?: string): void;
     private initOptionalFeatures;
     setStore(store: MemoryStore): void;
     /**
@@ -1551,6 +1700,8 @@ declare class Cascade extends EventEmitter {
     resumeRun(opts?: {
         maxTokens?: number;
     }): Promise<CascadeRunResult | null>;
+    getWorkspacePath(): string;
+    getWorldStateDB(): WorldStateDB | undefined;
     /**
      * Record an explicit user rating for the last completed run.
      * Explicit ratings carry 3× the weight of auto-detected outcomes so user
@@ -1577,6 +1728,14 @@ declare class Cascade extends EventEmitter {
      * do?" requests from being mis-routed into a multi-agent, multi-thousand-token run.
      */
     private looksLikeReadOnlyInquiry;
+    /**
+     * Strong, explicit signals that a task needs the full hierarchy (planning +
+     * multiple sections/workers). Deliberately conservative: requires a
+     * build/implementation verb AND either an app/system-scale noun or an
+     * explicit multi-part structure, so ordinary single-file asks (handled as
+     * Simple/Moderate) don't get over-escalated.
+     */
+    private looksClearlyComplex;
     private static globCache;
     private countWorkspaceFiles;
     private determineComplexity;
@@ -1787,6 +1946,8 @@ declare class T3Worker extends BaseTier {
     private toolRegistry;
     private context;
     private assignment?;
+    /** True when this subtask matched a privacy.paths local-only pattern. */
+    private localOnlyMatch;
     private peerSyncBuffer;
     private store?;
     private audit?;
@@ -2026,6 +2187,8 @@ declare class DashboardSocket {
     onApprovalResponse(callback: (data: PermissionDecisionPayload) => void): void;
     private setupHandlers;
     onSessionRate(callback: (sessionId: string, rating: 'good' | 'bad') => void): void;
+    onSessionHalt(callback: (sessionId: string) => void): void;
+    onSessionSteer(callback: (message: string, sessionId?: string, nodeId?: string) => void): void;
     onConfigUpdate(callback: (data: {
         keys?: Record<string, string>;
         models?: Record<string, string>;
@@ -2036,7 +2199,7 @@ declare class DashboardSocket {
     }) => void): void;
     emitToSocket(socketId: string, event: string, data: unknown): void;
     onConfigGet(callback: (socketId: string) => void): void;
-    onCascadeRun(callback: (prompt: string, model: string, socketId: string, sessionId?: string) => void): void;
+    onCascadeRun(callback: (prompt: string, model: string, socketId: string, sessionId?: string, forceTier?: string) => void): void;
     close(): void;
 }
 
@@ -2050,6 +2213,20 @@ declare class DashboardServer {
     private globalStore;
     private broadcastTimer;
     private activeSessions;
+    private activeControllers;
+    /**
+     * Run taskIds per chat session — file snapshots are keyed by the run's
+     * taskId (see t3-worker saveSnapshot), so session rollback needs the list
+     * of runs the session performed in this server's lifetime.
+     */
+    private sessionTaskIds;
+    /**
+     * Tool-approval requests awaiting a user decision from a connected client,
+     * keyed by the request's uuid. The desktop shows a modal on
+     * `permission:user-required` and answers with `permission:decision`; this
+     * map is how that answer reaches the run that's blocked on it.
+     */
+    private pendingApprovals;
     private port;
     private host;
     private workspacePath;
@@ -2082,6 +2259,25 @@ declare class DashboardServer {
     private persistRunStart;
     /** Record run end: the assistant reply (when there is one) and the runtime row's final status. */
     private persistRunEnd;
+    /**
+     * Route steering text into running Cascade instances. Targets the given
+     * session, or every active session when none is specified (the desktop
+     * usually has exactly one run in flight). Returns how many were reached.
+     */
+    private steerSessions;
+    private recordSessionTask;
+    /**
+     * Approval bridge: cascade calls this when a dangerous tool escalates to the
+     * user. The request itself was already pushed to the client via the
+     * `permission:user-required` forward; here we just park a resolver keyed by
+     * the request id and wait for the client's `permission:decision` (handled in
+     * onApprovalResponse). Never auto-approves — an unanswered request stays
+     * pending until the client answers, the run ends, or the escalator's own
+     * timeout denies it.
+     */
+    private makeApprovalCallback;
+    /** Deny + clear any approvals still pending for a session (run end / abort). */
+    private denyPendingApprovals;
     private persistRuntimeRow;
     /**
      * Continuing an existing session: the Cascade orchestrator is per-run and
@@ -2323,4 +2519,4 @@ declare class CascadeToolError extends Error {
 declare function preferIpv4Host(url: string | undefined): string | undefined;
 declare function nodeHttpFetch(input: string | URL | Request, init?: RequestInit, redirectCount?: number): Promise<Response>;
 
-export { AZURE_BASE_URL_TEMPLATE, type ApprovalRequest, type ApprovalResponse, type AuditEntry, AuditLogger, type BenchmarksConfig, type BudgetConfig, CASCADE_AUDIT_FILE, CASCADE_CONFIG_DIR, CASCADE_CONFIG_FILE, CASCADE_DASHBOARD_SECRET_FILE, CASCADE_DB_FILE, CASCADE_IGNORE_FILE, CASCADE_KEYSTORE_FILE, CASCADE_MD_FILE, CASCADE_VERSION, COMPLEXITY_T2_COUNT, Cascade, CascadeCancelledError, type CascadeConfig, type CascadeEvent, type CascadeEventType, CascadeIgnore, type CascadeMessage, CascadeRouter, type CascadeRunOptions, type CascadeRunResult, type CascadeThemeName, CascadeToolError, ConfigManager, type ConversationMessage, DEFAULT_API_PORT, DEFAULT_APPROVAL_REQUIRED, DEFAULT_AUTO_SUMMARIZE_AT, DEFAULT_CONTEXT_LIMIT, DEFAULT_DASHBOARD_PORT, DEFAULT_MAX_SESSION_MESSAGES, DEFAULT_RETENTION_DAYS, DEFAULT_THEME, type DashboardConfig, DashboardServer, type EscalationPayload, GLOBAL_CONFIG_DIR, GLOBAL_DB_FILE, GLOBAL_KEYSTORE_FILE, GLOBAL_RUNTIME_DB_FILE, type GenerateOptions, type GenerateResult, type HookDefinition, type HooksConfig, HooksRunner, type Identity, type ImageAttachment, Keystore, LM_STUDIO_BASE_URL, type LegacyThemeName, MODELS, McpClient, type McpServerConfig$1 as McpServerConfig, type MemoryConfig, MemoryStore, type Message, type MessageContent, type MessagePayload, type MessageStatus, type MessageType, type ModelInfo, type ModelOverrides, OLLAMA_BASE_URL, PROVIDER_DISPLAY_NAMES, type PeerMessage, type PeerMessageEvent, type PeerSyncPayload, type PeerSyncType, type PermissionDecision, type PermissionDecisionPayload, type PermissionRequest, type PlanReviewConfig, type ProviderConfig, type ProviderType, type RuntimeNode, type RuntimeNodeLog, type RuntimeRefreshPayload, type RuntimeScope, type RuntimeSession, type RuntimeSnapshotPayload, type ScheduledTask, type Session, type SessionCheckpoint, type SessionMetadata, type SessionSubscriptionPayload, type StatusUpdate, type StoredMessage, type StreamChunk, T1Administrator, type T1ToT2Assignment, T1_MODEL_PRIORITY, T2Manager, type T2Result, type T2ToT3Assignment, T2_MODEL_PRIORITY, type T3Result, type T3ResultPayload, type T3SubtaskSpec, T3Worker, T3_MODEL_PRIORITY, THEME_NAMES, TOOL_NAMES, type TaskComplexity, TaskScheduler, Telemetry, type TelemetryConfig, type Theme, type ThemeColors, type ThemeName, type TierConfig, type TierLimits, type TierRole, type TierStatus, type TokenUsage, type ToolCall, type ToolDefinition, type ToolExecuteOptions, ToolRegistry, type ToolResult, type ToolsConfig, VISION_MODEL_PRIORITY, type WebSearchConfig, type WebhookConfig, type WorkspaceConfig, createCascade, nodeHttpFetch, preferIpv4Host, runCascade, streamCascade };
+export { AZURE_BASE_URL_TEMPLATE, type ApprovalRequest, type ApprovalResponse, type AuditEntry, AuditLogger, type BenchmarksConfig, type BudgetConfig, CASCADE_AUDIT_FILE, CASCADE_CONFIG_DIR, CASCADE_CONFIG_FILE, CASCADE_DASHBOARD_SECRET_FILE, CASCADE_DB_FILE, CASCADE_IGNORE_FILE, CASCADE_KEYSTORE_FILE, CASCADE_MD_FILE, CASCADE_VERSION, COMPLEXITY_T2_COUNT, Cascade, CascadeCancelledError, type CascadeConfig, type CascadeEvent, type CascadeEventType, CascadeIgnore, type CascadeMessage, CascadeRouter, type CascadeRunOptions, type CascadeRunResult, type CascadeThemeName, CascadeToolError, ConfigManager, type ConversationMessage, DEFAULT_API_PORT, DEFAULT_APPROVAL_REQUIRED, DEFAULT_AUTO_SUMMARIZE_AT, DEFAULT_CONTEXT_LIMIT, DEFAULT_DASHBOARD_PORT, DEFAULT_MAX_SESSION_MESSAGES, DEFAULT_RETENTION_DAYS, DEFAULT_THEME, type DashboardConfig, DashboardServer, type EscalationPayload, GLOBAL_CONFIG_DIR, GLOBAL_DB_FILE, GLOBAL_KEYSTORE_FILE, GLOBAL_RUNTIME_DB_FILE, type GenerateOptions, type GenerateResult, type HookDefinition, type HooksConfig, HooksRunner, type Identity, type ImageAttachment, Keystore, LM_STUDIO_BASE_URL, type LegacyThemeName, MODELS, McpClient, type McpServerConfig$1 as McpServerConfig, type MemoryConfig, MemoryStore, type Message, type MessageContent, type MessagePayload, type MessageStatus, type MessageType, type ModelInfo, type ModelOverrides, OLLAMA_BASE_URL, PROVIDER_DISPLAY_NAMES, type PeerMessage, type PeerMessageEvent, type PeerSyncPayload, type PeerSyncType, type PermissionDecision, type PermissionDecisionPayload, type PermissionRequest, type PermissionTrailEntry, type PlanReviewConfig, type ProviderConfig, type ProviderType, type RuntimeNode, type RuntimeNodeLog, type RuntimeRefreshPayload, type RuntimeScope, type RuntimeSession, type RuntimeSnapshotPayload, type ScheduledTask, type Session, type SessionCheckpoint, type SessionMetadata, type SessionSubscriptionPayload, type StatusUpdate, type StoredMessage, type StreamChunk, T1Administrator, type T1ToT2Assignment, T1_MODEL_PRIORITY, T2Manager, type T2Result, type T2ToT3Assignment, T2_MODEL_PRIORITY, type T3Result, type T3ResultPayload, type T3SubtaskSpec, T3Worker, T3_MODEL_PRIORITY, THEME_NAMES, TOOL_NAMES, type TaskComplexity, TaskScheduler, Telemetry, type TelemetryConfig, type Theme, type ThemeColors, type ThemeName, type TierConfig, type TierLimits, type TierRole, type TierStatus, type TokenUsage, type ToolCall, type ToolDefinition, type ToolExecuteOptions, ToolRegistry, type ToolResult, type ToolsConfig, VISION_MODEL_PRIORITY, type WebSearchConfig, type WebhookConfig, type WorkspaceConfig, createCascade, nodeHttpFetch, preferIpv4Host, runCascade, streamCascade };