cascade-ai 0.20.0 → 0.20.2

package/dist/index.d.cts

@@ -1,5 +1,9 @@
 import EventEmitter from 'node:events';
+import { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
 import { Server } from 'node:http';
+import { OAuthClientInformationMixed, OAuthTokens, OAuthClientMetadata, OAuthClientInformationFull } from '@modelcontextprotocol/sdk/shared/auth.js';
+export { OAuthClientInformationMixed, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
+import Database from 'better-sqlite3';
 
 type ProviderType = 'anthropic' | 'openai' | 'gemini' | 'azure' | 'openai-compatible' | 'ollama';
 interface ModelInfo {
@@ -18,6 +22,13 @@ interface ModelInfo {
     supportsToolUse?: boolean;
     /** Self-declared or API-sourced specialization categories. */
     specializations?: string[];
+    /**
+     * Canonical base-model id this entry stands for, when `id` isn't itself
+     * canonical. Azure deployments are addressed by an arbitrary deployment name
+     * (the `id`), but back a real model (e.g. gpt-5) — `baseModelId` carries that
+     * real identity so benchmark scoring and live pricing resolve correctly.
+     */
+    baseModelId?: string;
 }
 interface ProviderConfig {
     type: ProviderType;
@@ -104,9 +115,14 @@ interface ImageAttachment {
 }
 interface McpServerConfig$1 {
     name: string;
-    command: string;
+    command?: string;
     args?: string[];
     env?: Record<string, string>;
+    url?: string;
+    headers?: Record<string, string>;
+    /** Path to a JSON store of this server's OAuth state (desktop/CLI). When set,
+     *  the run attaches an auto-refreshing OAuth token instead of a static header. */
+    oauthStore?: string;
 }
 interface ToolDefinition {
     name: string;
@@ -390,6 +406,8 @@ interface CascadeConfig {
     budget: BudgetConfig;
     theme: string;
     workspace: WorkspaceConfig;
+    /** Extended context: compact history/input that exceeds the model's window. */
+    extendedContext?: ExtendedContextConfig;
     cascadeAuto?: boolean;
     /** Cascade Auto trade-off bias when picking a model. Default: 'balanced'. */
     autoBias?: 'balanced' | 'quality' | 'cost';
@@ -402,6 +420,12 @@ interface CascadeConfig {
     knowledge?: {
         factsExtraction?: boolean;
     };
+    /** Workspace code index (Phase 3). Opt-in; registers a `code_search` tool. */
+    codeIndex?: {
+        enabled?: boolean;
+        autoRefresh?: boolean;
+        dbPath?: string;
+    };
     plugins?: string[];
     localConcurrency?: number;
     localInferenceTimeoutMs?: number;
@@ -425,6 +449,10 @@ interface CascadeConfig {
         enabled?: boolean;
         maxRounds?: number;
     };
+    /** Fast answer behaviour. `autoSimple`: pure small talk skips orchestration for a direct single-model reply. Default: true. */
+    fastAnswer?: {
+        autoSimple?: boolean;
+    };
     /** T3 wave execution: 'auto' (sequential for local, parallel for cloud), or force one. Default: 'auto'. */
     t3Execution?: 'auto' | 'parallel' | 'sequential';
     /** T3→T2 reinforcement: let a worker ask its manager to spawn sibling workers. Off by default. */
@@ -451,6 +479,10 @@ interface CascadeConfig {
      */
     routing?: {
         forceTier?: 'auto' | 'T1' | 'T2' | 'T3';
+        /** Override the model-performance stats file (cloud → persistent volume). */
+        perfStatsPath?: string;
+        /** Read shared scores but don't record this run's outcomes when false. Default true. */
+        learnFromOutcomes?: boolean;
     };
     /** Render the TUI in the alternate screen buffer (vim-style). Default: false. */
     altScreen?: boolean;
@@ -478,6 +510,10 @@ interface BenchmarksConfig {
     sourceUrl?: string;
     /** Fetch current per-token prices from OpenRouter (free, no key). Default: true. */
     pricingLive?: boolean;
+    /** Where the fetched live snapshot is cached. Cloud → the persistent volume,
+     *  so live benchmark scores survive redeploys and are shared across requests
+     *  instead of re-fetched on every fresh Cascade. Defaults to ~/.cascade. */
+    cacheFile?: string;
 }
 interface ToolsConfig {
     shellAllowlist: string[];
@@ -538,11 +574,30 @@ interface MemoryConfig {
     maxSessionMessages: number;
     autoSummarizeAt: number;
     retentionDays: number;
+    /**
+     * Opt-in: after a run completes, distill durable facts from the session into
+     * the project knowledge store (undoable per-fact from the Knowledge tab).
+     * Off by default — session content stays out of long-term memory unless the
+     * user chooses otherwise.
+     */
+    rememberSessions?: boolean;
+}
+interface ExtendedContextConfig {
+    /** Off by default — when on, oversized history/input is compacted to fit. */
+    enabled: boolean;
+    /** How far past the model's native window an input may go before it's
+     *  truncated (via chunk + map-reduce). 2 = up to 2× the window. */
+    maxMultiplier: number;
 }
 interface TierLimits {
     t1MaxTokens?: number;
     t2MaxTokens?: number;
     t3MaxTokens?: number;
+    /** Per-tier sampling temperature (0–2). Applied only when a call doesn't set
+     *  its own temperature — deterministic internal calls (temperature: 0) win. */
+    t1Temperature?: number;
+    t2Temperature?: number;
+    t3Temperature?: number;
 }
 interface BudgetConfig {
     dailyBudgetUsd?: number;
@@ -583,7 +638,7 @@ interface ThemeColors {
     t2Color: string;
     t3Color: string;
 }
-type CascadeEventType = 'task:start' | 'task:complete' | 'task:error' | 'tier:status' | 'tier:result' | 'tier:root' | 'stream:token' | 'stream:done' | 'tool:approval-request' | 'tool:approval-response' | 'tool:execute' | 'tool:result' | 'tool:call' | 'cost:update' | 'session:save' | 'escalation' | 'peer:sync' | 'peer:message' | 'plan' | 'log' | 'run:cancelled' | 'budget:warning' | 'budget:exceeded' | 'permission:user-required' | 'mcp:approval-required' | 'plan:approval-required';
+type CascadeEventType = 'task:start' | 'task:complete' | 'task:error' | 'tier:status' | 'tier:result' | 'tier:root' | 'stream:token' | 'stream:done' | 'tool:approval-request' | 'tool:approval-response' | 'tool:execute' | 'tool:result' | 'tool:call' | 'cost:update' | 'session:save' | 'escalation' | 'peer:sync' | 'peer:message' | 'plan' | 'log' | 'run:cancelled' | 'budget:warning' | 'budget:exceeded' | 'permission:user-required' | 'mcp:approval-required' | 'plan:approval-required' | 'context:approval-required' | 'context:compacted';
 interface CascadeEvent<T = unknown> {
     type: CascadeEventType;
     taskId?: string;
@@ -717,6 +772,36 @@ interface CascadeRunOptions {
      * controller.abort();
      */
     signal?: AbortSignal;
+    /**
+     * An optional, pre-computed complexity verdict for this run — e.g. from a
+     * cheap on-device classifier the caller ran first. When provided (and no tier
+     * is manually forced), the orchestrator uses it as the starting verdict and
+     * skips its own classifier LLM call, saving that round-trip. The heuristic
+     * complexity floors and mid-run escalation still apply, so an under-estimate
+     * can't strand genuinely complex work on a cheap tier. Only the first three
+     * levels are accepted as a hint; 'Highly Complex' is derived server-side.
+     */
+    complexityHint?: Exclude<TaskComplexity, 'Highly Complex'>;
+    /**
+     * "Fast answer" — bypass the whole T1/T2/T3 orchestration and reply with a
+     * single mid-tier model, no tools and no artifact verification. For quick
+     * questions and small edits where the multi-agent machinery just adds latency
+     * and cost. The reply still streams and is persisted like a normal turn.
+     */
+    fastAnswer?: boolean;
+    /**
+     * The user's ACTUAL message, for routing decisions only, when `prompt` has
+     * been augmented by the host (system guidance, memories, documents). The
+     * complexity heuristics/classifier and task-type analysis read this instead
+     * of the augmented prompt, so a bare "hi" still routes as small talk. The
+     * model still receives the full `prompt`. Defaults to `prompt` when unset.
+     */
+    routingPrompt?: string;
+    /**
+     * Optional model id to use for a fast answer (e.g. 'gpt-4o-mini'). When unset,
+     * a validated mid-tier model is auto-selected. Ignored unless `fastAnswer`.
+     */
+    fastAnswerModel?: string;
 }
 interface CascadeRunResult {
     output: string;
@@ -738,8 +823,23 @@ interface CascadeRunResult {
 declare class ModelSelector {
     private availableProviders;
     private availableModels;
+    /**
+     * Per-provider set of model ids the provider's own API confirmed it serves
+     * (from listModels discovery). When present for a provider, AUTO selection
+     * skips that provider's bundled catalog ids that aren't in the set — so a
+     * stale/access-gated catalog id is never picked, then 404'd, then failed over.
+     * Absent for a provider ⇒ no validation ran ⇒ behave exactly as before.
+     */
+    private validatedIds;
     constructor(availableProviders: Set<ProviderType>);
     addDynamicModel(model: ModelInfo): void;
+    /** Record the ids a provider's API actually serves (discovery). Empty ⇒ ignored. */
+    setValidatedModels(provider: ProviderType, ids: string[]): void;
+    /**
+     * A model is usable for AUTO selection when its provider is available AND —
+     * if that provider was validated — the id is one the provider confirmed.
+     */
+    private isUsable;
     /**
      * Permanently drop a model from the available set for this session. Used by
      * the router's 404 / "model not found" self-heal so a dead id is never
@@ -777,6 +877,11 @@ interface ModelStat {
     totalRetries: number;
     totalCostUsd: number;
     sampleCount: number;
+    /** Sum of input/context tokens across samples — so we can see whether a
+     *  model tends to fail on larger contexts and route less to it accordingly. */
+    totalContextTokens: number;
+    /** Sum of context tokens on the FAILED samples only. */
+    failureContextTokens: number;
 }
 interface FeatureStat {
     totalCostUsd: number;
@@ -786,11 +891,19 @@ declare class ModelPerformanceTracker {
     private stats;
     private featureStats;
     private readonly statsFile;
+    private readonly readOnly;
     private loaded;
-    constructor(statsFile?: string);
+    /**
+     * @param statsFile where stats persist (cloud → the persistent volume).
+     * @param options.readOnly consume the shared scores but don't record/save this
+     *        run's outcomes — the opt-out path for users who declined to contribute.
+     */
+    constructor(statsFile?: string, options?: {
+        readOnly?: boolean;
+    });
     load(): Promise<void>;
     save(): Promise<void>;
-    record(modelId: string, taskType: TaskType, outcome: 'success' | 'failure', retries?: number, costUsd?: number): void;
+    record(modelId: string, taskType: TaskType, outcome: 'success' | 'failure', retries?: number, costUsd?: number, contextTokens?: number): void;
     recordFeatureCost(featureTag: string, costUsd: number): void;
     /**
      * Record an explicit user rating (good/bad). Counts as 3 automatic samples
@@ -856,7 +969,7 @@ declare class TaskAnalyzer {
      * Record the outcome of a completed run across all tiers that were selected
      * during this session and persist stats to disk.
      */
-    recordRunOutcome(outcome: 'success' | 'failure', costByTier: Record<string, number>): void;
+    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.
      * Explicit ratings carry 3× the weight of auto-detected outcomes.
@@ -1080,6 +1193,12 @@ declare class WorldStateDB {
     private dbPath;
     private encryptionKey;
     constructor(workspacePath: string, debugMode?: boolean);
+    /**
+     * Append the CURRENTLY-stored fact for (e, r) to the history ledger before it
+     * is overwritten/deleted, timestamped [its recorded time → now]. No-op when
+     * there is no current row. The value stays encrypted with the same key.
+     */
+    private archiveCurrentFact;
     private initEncryptionKey;
     private encrypt;
     private decrypt;
@@ -1117,8 +1236,27 @@ declare class WorldStateDB {
      * delete — users can prune what the planner remembers about their project.
      */
     deleteFact(entity: string, relation: string): boolean;
-    /** Delete every fact. Returns how many were removed. */
+    /** Delete every fact. Returns how many were removed. History is preserved. */
     clearFacts(): number;
+    /**
+     * Prior values for one (entity, relation), newest-first — the durable trail of
+     * what this fact used to be before it was overwritten or deleted. Decrypted
+     * here (the ciphertext never leaves this process).
+     */
+    getFactHistory(entity: string, relation: string): Array<{
+        value: string;
+        sourceWorker: string;
+        validFrom: string;
+        validTo: string;
+        change: string;
+    }>;
+    /**
+     * Restore a historical value for (entity, relation) as the current fact. The
+     * value currently in place (if any) is itself archived first, so restore is
+     * undoable. When `validFrom` is given, restores that exact historical entry;
+     * otherwise restores the most recent one. Returns whether anything was restored.
+     */
+    restoreFact(entity: string, relation: string, validFrom?: string): boolean;
     exportKnowledge(): {
         facts: WorldFact[];
         worldLog: WorldStateEntry[];
@@ -1272,6 +1410,15 @@ declare class CascadeRouter extends EventEmitter {
     refreshLiveData(): Promise<void>;
     /** Returns the live-data provider once refreshLiveData has run (UX/insight). */
     getLiveData(): LiveDataProvider | undefined;
+    /**
+     * Validate the official cloud providers (anthropic/openai/gemini) against
+     * their own /models list at init time so AUTO selection only picks a model the
+     * key actually serves. This is the fix for "a non-existent catalog model gets
+     * selected, then the run fails over through several models before one works".
+     * Cached per key (TTL) so a per-request router doesn't re-discover; fully
+     * best-effort + time-boxed, so offline/error simply keeps the bundled catalog.
+     */
+    private validateCloudProviderModels;
     /**
      * Query each available cloud provider's live model list and register the
      * results. Confirms catalog ids still exist and surfaces newly released
@@ -1322,6 +1469,12 @@ declare class CascadeRouter extends EventEmitter {
     /** Set (or clear) the current run's abort signal for instant cancellation. */
     setRunSignal(signal: AbortSignal | undefined): void;
     getSelector(): ModelSelector;
+    /**
+     * The tightest context window (in tokens) across the resolved tier models, or
+     * undefined if none are resolved yet. Extended-context compaction budgets
+     * against this so the compacted context fits whichever tier handles the run.
+     */
+    getReferenceContextWindow(): number | undefined;
     /** Wire the Cascade Auto task analyzer used for per-subtask model routing. */
     setTaskAnalyzer(analyzer: TaskAnalyzer): void;
     setWorldStateDB(db: WorldStateDB | undefined): void;
@@ -1399,6 +1552,8 @@ declare class CascadeRouter extends EventEmitter {
      * Used to populate the desktop model pickers with the user's real models.
      */
     getAvailableModels(): ModelInfo[];
+    /** Logs why a configured provider failed its availability probe. */
+    private emitProbeFailure;
     private detectAvailableProviders;
     private discoverOllamaModels;
     /** Returns true when at least one real model was discovered from the endpoint. */
@@ -1451,9 +1606,11 @@ declare abstract class BaseTool {
 
 interface McpServerConfig {
     name: string;
-    command: string;
+    command?: string;
     args?: string[];
     env?: Record<string, string>;
+    url?: string;
+    headers?: Record<string, string>;
 }
 /**
  * Gate called before each MCP server is spawned. Lets the caller (REPL or
@@ -1487,7 +1644,16 @@ declare class McpClient {
     private approvalCallback;
     private onWarn;
     constructor(options?: McpClientOptions);
-    connect(server: McpServerConfig): Promise<void>;
+    connect(server: McpServerConfig, opts?: {
+        authProvider?: OAuthClientProvider;
+    }): Promise<void>;
+    /**
+     * Connect to a remote MCP server. Tries Streamable HTTP first (the current
+     * transport); if that fails (a legacy server that only speaks SSE), retries
+     * once over SSE. Auth headers ride on every request. Returns the live
+     * transport so the caller can register it.
+     */
+    private connectRemote;
     disconnect(serverName: string): Promise<void>;
     disconnectAll(): Promise<void>;
     callTool(serverName: string, toolName: string, input: Record<string, unknown>): Promise<string>;
@@ -1813,13 +1979,14 @@ declare class T1Administrator extends BaseTier {
 /** One entry in the per-run orchestration decision trail (see /why). */
 interface DecisionLogEntry {
     at: string;
-    kind: 'complexity' | 'model' | 'failover' | 'escalation';
+    kind: 'complexity' | 'model' | 'failover' | 'escalation' | 'context';
     detail: string;
 }
 declare class Cascade extends EventEmitter {
     private router;
     private toolRegistry;
     private mcpClient;
+    private codeIndex?;
     private config;
     /** Orchestration decisions for the CURRENT run — cleared on each run(). */
     private decisionLog;
@@ -1855,6 +2022,13 @@ declare class Cascade extends EventEmitter {
      */
     private pendingMcpApprovals;
     private requestMcpApproval;
+    /**
+     * Build the workspace code index and register the `code_search` tool. Uses the
+     * user's own provider key for embeddings (and, if chat-capable, reranking).
+     * The index persists to a per-workspace SQLite file; `autoRefresh` brings it
+     * up to date at init (incremental — only changed files re-embed).
+     */
+    private initCodeIndex;
     private recordDecision;
     /**
      * The orchestration decision trail for the most recent run: complexity
@@ -1872,6 +2046,18 @@ declare class Cascade extends EventEmitter {
      * directly (no re-decompose).
      */
     resolvePlanApproval(approved: boolean, note?: string, editedPlan?: TaskPlan): void;
+    private pendingContextApproval?;
+    /** Resolve a pending extended-context confirmation from a UI listener. */
+    resolveContextApproval(approved: boolean): void;
+    private requestContextApproval;
+    /**
+     * Extended context: when enabled, compact an over-budget conversation history
+     * (rolling summary — cheap, automatic) and/or a single oversized input (chunk
+     * + map-reduce — confirm-gated) so the run fits the model's window. Returns a
+     * new options object with the compacted prompt/history; a no-op when disabled,
+     * when nothing overflows, or when the model window isn't known yet.
+     */
+    private applyExtendedContext;
     /**
      * Autonomy control (used by the /auto command). 'auto' makes the next run
      * hands-off: the plan gate auto-approves and non-dangerous tools auto-approve,
@@ -1919,6 +2105,22 @@ declare class Cascade extends EventEmitter {
     private estimatePlanCost;
     init(): Promise<void>;
     private isCasualGreeting;
+    /**
+     * Pure small talk that a single tool-less model answers best: greetings,
+     * acknowledgements and self-identity questions. Deliberately NARROWER than
+     * looksLikeConversational — "what is X" / "show me Y" / "list Z" need tools
+     * or real lookup and stay on the worker path. Bare confirmations ("yes",
+     * "ok") in an ongoing conversation are task input, not small talk.
+     */
+    private looksLikeSmallTalk;
+    /**
+     * A terse option/menu selection ("3", "b)", "option 2") replying to an
+     * ongoing conversation. These inherit the prior turn's intent — they are
+     * usually an ACTION choice, so they must not be short-circuited to a
+     * tool-less direct answer, and a context-free on-device hint about them
+     * is noise (the hint classifier never saw the conversation).
+     */
+    private looksLikeTerseOptionReply;
     private looksLikeSimpleArtifactTask;
     private looksLikeConversational;
     /**
@@ -1951,8 +2153,31 @@ declare class Cascade extends EventEmitter {
     private looksLikeModerateBuild;
     private static globCache;
     private countWorkspaceFiles;
+    /**
+     * Raises a raw complexity verdict (from the classifier LLM or a caller hint)
+     * to the tier the prompt's signals demand. A small model that under-rates
+     * clearly multi-step build work can't strand it below where it belongs:
+     * explicit build+scale signals floor it to Complex (full T1→T2→T3), and a
+     * single-deliverable build floors a "Simple" up to Moderate (one manager).
+     * Conservative on purpose — the source is free to go higher, and a manual
+     * tier override is the escape hatch. Records the decision it makes.
+     */
+    private floorComplexity;
     private determineComplexity;
     run(options: CascadeRunOptions): Promise<CascadeRunResult>;
+    /**
+     * Direct single-model reply — the "fast answer" path. No planning, no workers,
+     * no tools, no artifact verification: the user's message (with recent history)
+     * answered by one mid-tier model, streamed as the primary output and shaped
+     * into the normal CascadeRunResult so persistence + the run receipt still work.
+     */
+    private runFastAnswer;
+    /**
+     * Distill a completed session into durable facts and store them in the
+     * project knowledge graph (opt-in via memory.rememberSessions). Best-effort:
+     * skips trivial exchanges, uses one cheap T3 call, and swallows all errors.
+     */
+    private rememberSession;
     getRouter(): CascadeRouter;
     getToolRegistry(): ToolRegistry;
     /**
@@ -2589,6 +2814,519 @@ interface HookResult {
     error?: string;
 }
 
+/** The persisted state of one MCP server's OAuth: DCR result, tokens, PKCE verifier. */
+interface McpOAuthState {
+    clientInformation?: OAuthClientInformationMixed;
+    tokens?: OAuthTokens;
+    codeVerifier?: string;
+}
+/** Pluggable persistence for a single server's OAuth state (differs per surface). */
+interface McpOAuthStore {
+    load(): McpOAuthState | undefined | Promise<McpOAuthState | undefined>;
+    save(state: McpOAuthState): void | Promise<void>;
+    clear?(): void | Promise<void>;
+}
+interface McpOAuthProviderOptions {
+    /** Where the authorization server redirects back (our callback / loopback). */
+    redirectUrl: string;
+    store: McpOAuthStore;
+    /** Send the user to the authorization URL (open a browser / hand it to the web). */
+    redirect: (authorizationUrl: URL) => void | Promise<void>;
+    clientName?: string;
+    scope?: string;
+    /** Fixed OAuth `state` (e.g. the cloud pending-flow key). Random if omitted. */
+    state?: string;
+}
+/**
+ * Our `OAuthClientProvider`: storage + redirect for the MCP SDK's OAuth client.
+ * The SDK calls these hooks while it runs discovery/DCR/PKCE/refresh for us.
+ */
+declare class McpOAuthProvider implements OAuthClientProvider {
+    private readonly opts;
+    private cache;
+    private readonly _state;
+    constructor(opts: McpOAuthProviderOptions);
+    /** The `state` this provider uses — callers validate it on the callback. */
+    get oauthState(): string;
+    private loaded;
+    private persist;
+    get redirectUrl(): string;
+    get clientMetadata(): OAuthClientMetadata;
+    state(): string;
+    clientInformation(): Promise<OAuthClientInformationMixed | undefined>;
+    saveClientInformation(info: OAuthClientInformationFull): Promise<void>;
+    tokens(): Promise<OAuthTokens | undefined>;
+    saveTokens(tokens: OAuthTokens): Promise<void>;
+    redirectToAuthorization(authorizationUrl: URL): Promise<void>;
+    saveCodeVerifier(codeVerifier: string): Promise<void>;
+    codeVerifier(): Promise<string>;
+    invalidateCredentials(scope: 'all' | 'client' | 'tokens' | 'verifier' | 'discovery'): Promise<void>;
+}
+/** A 0600 JSON file store for one server's OAuth state (desktop/CLI). */
+declare class FileMcpOAuthStore implements McpOAuthStore {
+    private readonly filePath;
+    constructor(filePath: string);
+    load(): McpOAuthState | undefined;
+    save(state: McpOAuthState): void;
+    clear(): void;
+}
+/**
+ * Build a refresh-only provider over a file store, for a run connecting an
+ * already-authorized OAuth MCP server. Refresh is silent; if the refresh token
+ * is dead the transport would need a browser redirect, which a headless run
+ * can't do — so `redirect` throws a clear "reconnect" message instead.
+ */
+declare function fileOAuthProvider(storePath: string): McpOAuthProvider;
+/** Drive the OAuth flow to the point of a browser redirect (or already-authorized). */
+declare function beginMcpOAuth(provider: OAuthClientProvider, serverUrl: string): Promise<'AUTHORIZED' | 'REDIRECT'>;
+/** Complete the flow with the authorization code (saves tokens via the provider). */
+declare function completeMcpOAuth(provider: OAuthClientProvider, serverUrl: string, authorizationCode: string): Promise<void>;
+/** The authorization server (issuer) protecting an MCP server, if it advertises one. */
+declare function discoverMcpAuthServer(serverUrl: string): Promise<string | undefined>;
+/** Refresh an access token from a stored refresh token + client registration. */
+declare function refreshMcpToken(input: {
+    authorizationServerUrl: string;
+    clientInformation: OAuthClientInformationMixed;
+    refreshToken: string;
+}): Promise<OAuthTokens>;
+interface LoopbackOAuthResult {
+    tokens: OAuthTokens;
+    clientInformation?: OAuthClientInformationMixed;
+}
+/**
+ * Run the full OAuth connect for a rich native client: open a one-shot
+ * `127.0.0.1` listener, let the MCP SDK drive discovery/DCR/PKCE, open the
+ * system browser via `openUrl`, catch the code on the loopback, finish the
+ * exchange, and return the tokens (also persisted through `store`).
+ */
+declare function connectMcpWithLoopbackOAuth(opts: {
+    serverUrl: string;
+    store: McpOAuthStore;
+    openUrl: (url: string) => void | Promise<void>;
+    clientName?: string;
+    scope?: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}): Promise<LoopbackOAuthResult>;
+
+/** A unit of indexed text. `sourceId` groups chunks from one document/file. */
+interface Chunk {
+    id: string;
+    text: string;
+    sourceId: string;
+    /** Order of this chunk within its source (0-based). */
+    ord: number;
+    meta?: Record<string, unknown>;
+}
+/** A chunk with a relevance score (higher = more relevant). */
+interface ScoredChunk extends Chunk {
+    score: number;
+}
+/** Turns text into embedding vectors. Implementations wrap a provider API or a
+ *  local model. `model` + `dims` are recorded with every vector so a future
+ *  model change forces a clean re-index rather than silent quality rot. */
+interface Embedder {
+    readonly model: string;
+    /** Vector dimension. 0 until the first embed call resolves it. */
+    readonly dims: number;
+    /** Embed a batch of texts → one vector per input (same order). */
+    embed(texts: string[]): Promise<number[][]>;
+}
+interface SearchOptions {
+    namespace: string;
+    k?: number;
+    /** Restrict results to these source ids (e.g. the docs attached to a run). */
+    sourceIds?: string[];
+}
+/** Persists chunk vectors and answers the two first-stage queries of hybrid
+ *  retrieval. The Phase-1 implementation is SQLite-backed (BLOB vectors +
+ *  FTS5), swappable later for a dedicated ANN index behind this interface. */
+interface VectorStore {
+    upsert(records: Array<{
+        chunk: Chunk;
+        vector: number[];
+    }>, embedModel: string): void;
+    /** True once this source has chunks for the given embed model (skip re-embed). */
+    hasSource(namespace: string, sourceId: string, embedModel: string): boolean;
+    lexicalSearch(query: string, opts: SearchOptions): ScoredChunk[];
+    denseSearch(queryVector: number[], opts: SearchOptions): ScoredChunk[];
+    deleteSource(namespace: string, sourceId: string): void;
+}
+
+interface ChunkOptions {
+    /** Target chunk size in characters (~512 tokens by default). */
+    targetChars?: number;
+    /** Overlap carried from the end of one chunk into the next. */
+    overlapChars?: number;
+    /** Drop a trailing chunk smaller than this unless it's the only one. */
+    minChars?: number;
+}
+/**
+ * Chunk prose/markdown into overlapping windows. Returns `{ text, ord }` in
+ * document order. Deterministic and dependency-free.
+ */
+declare function chunkText(input: string, options?: ChunkOptions): Array<{
+    text: string;
+    ord: number;
+}>;
+
+interface OpenAIEmbedderOptions {
+    apiKey?: string;
+    baseURL?: string;
+    model: string;
+    /** Matryoshka truncation for text-embedding-3-* (e.g. 512). Omit for native. */
+    dimensions?: number;
+}
+/**
+ * Embedder backed by an OpenAI-compatible `/v1/embeddings` endpoint. Works
+ * against OpenAI, OpenAI-compatible gateways, and Ollama (which exposes the same
+ * route) — so the cloud uses a provider API and desktop/CLI can point at a local
+ * Ollama with no separate runtime.
+ */
+declare class OpenAICompatibleEmbedder implements Embedder {
+    readonly model: string;
+    private client;
+    private dimensions;
+    private resolvedDims;
+    constructor(opts: OpenAIEmbedderOptions);
+    get dims(): number;
+    embed(texts: string[]): Promise<number[][]>;
+}
+/**
+ * Pick an embeddings-capable provider from the user's configured providers and
+ * build an Embedder, or return null when none can embed (e.g. an Anthropic-only
+ * setup). Prefers a hosted OpenAI/compatible key over a local Ollama.
+ */
+declare function embedderFromProviders(providers: ProviderConfig[], opts?: {
+    model?: string;
+    dimensions?: number;
+}): Embedder | null;
+
+declare class SqliteVectorStore implements VectorStore {
+    private db;
+    constructor(db: Database.Database);
+    private migrate;
+    upsert(records: Array<{
+        chunk: Chunk;
+        vector: number[];
+    }>, embedModel: string): void;
+    hasSource(namespace: string, sourceId: string, embedModel: string): boolean;
+    deleteSource(namespace: string, sourceId: string): void;
+    lexicalSearch(query: string, opts: SearchOptions): ScoredChunk[];
+    denseSearch(queryVector: number[], opts: SearchOptions): ScoredChunk[];
+    private sourceFilter;
+}
+
+interface Reranker {
+    readonly name: string;
+    /** Reorder candidates for a query; return the best `topK`, best-first. */
+    rerank(query: string, candidates: ScoredChunk[], topK: number): Promise<ScoredChunk[]>;
+}
+/** A minimal text-completion function (prompt in, text out). */
+type CompleteFn = (prompt: string) => Promise<string>;
+/** Parse a model's "3,1,4" answer into 0-based indices, keeping only valid,
+ *  in-range, non-duplicate entries. Returns null when nothing parses. */
+declare function parseRankOrder(reply: string, count: number): number[] | null;
+declare class LLMReranker implements Reranker {
+    readonly name = "llm-listwise";
+    private complete;
+    /** Cap on candidates sent to the model (keeps the prompt + cost bounded). */
+    private maxCandidates;
+    constructor(opts: {
+        complete: CompleteFn;
+        maxCandidates?: number;
+    });
+    rerank(query: string, candidates: ScoredChunk[], topK: number): Promise<ScoredChunk[]>;
+}
+/**
+ * Build a completion function from the user's providers using an OpenAI-
+ * compatible `/chat/completions` endpoint (OpenAI, compatible gateways, Ollama).
+ * Returns null when no such provider is configured (reranking then no-ops and
+ * the fused order stands). Mirrors embedderFromProviders so the same key powers
+ * both stages.
+ */
+declare function chatCompleterFromProviders(providers: ProviderConfig[], opts?: {
+    model?: string;
+}): CompleteFn | null;
+
+interface RetrieverSearchOptions {
+    namespace: string;
+    /** Final number of chunks to return. */
+    k?: number;
+    /** Restrict to these source ids (e.g. only this run's attached docs). */
+    sourceIds?: string[];
+    /** Candidates to pull from each first stage before fusion. */
+    candidates?: number;
+    /** RRF damping constant (higher = flatter). Standard default is 60. */
+    rrfK?: number;
+    /** Rerank the fused candidates when a reranker is configured (default true). */
+    rerank?: boolean;
+}
+/**
+ * Fuse several ranked lists into one by Reciprocal Rank Fusion. Each list
+ * contributes 1/(rrfK + rank) to an item's score; identical items across lists
+ * accumulate. Returns items best-first.
+ */
+declare function reciprocalRankFusion(lists: ScoredChunk[][], rrfK?: number): ScoredChunk[];
+declare class Retriever {
+    private readonly embedder;
+    private readonly store;
+    /** Optional second-stage reranker (Phase 2). When set, search reranks the
+     *  fused candidates before returning the top-k. */
+    private readonly reranker?;
+    constructor(embedder: Embedder, store: VectorStore, 
+    /** Optional second-stage reranker (Phase 2). When set, search reranks the
+     *  fused candidates before returning the top-k. */
+    reranker?: Reranker | undefined);
+    /** Chunk model this retriever embeds with (for cache/version keys). */
+    get embedModel(): string;
+    /** True when this source is already indexed under the current embed model. */
+    isIndexed(namespace: string, sourceId: string): boolean;
+    /**
+     * Embed and store a source's chunks. Skips work when the source is already
+     * indexed under the current embed model (so re-runs don't re-embed). Returns
+     * the number of chunks newly indexed.
+     */
+    index(namespace: string, sourceId: string, chunks: Array<{
+        text: string;
+        ord: number;
+    }>): Promise<number>;
+    /** Hybrid search: lexical ∪ dense, fused with RRF, then optionally reranked. */
+    search(query: string, opts: RetrieverSearchOptions): Promise<ScoredChunk[]>;
+}
+
+type RetrievalMode = 'none' | 'cag' | 'rag' | 'graph' | 'code';
+interface RetrievalContext {
+    /** Retrievable sources attached to this run (e.g. documents). */
+    sourceCount: number;
+    /** Total characters across those sources. */
+    totalChars: number;
+    /** Below this size, sources are injected in full (cache-augmented). */
+    cagCharBudget: number;
+    /** A single direct model call — no orchestration/retrieval machinery. */
+    fastAnswer?: boolean;
+}
+interface RetrievalPlan {
+    mode: RetrievalMode;
+    /** Human-readable rationale (surfaced in notices / decision logs). */
+    reason: string;
+}
+/** Rough characters-per-token, the standard ~4:1 approximation for English text. */
+declare const CHARS_PER_TOKEN = 4;
+/**
+ * The character budget below which attached documents are injected in full
+ * (CAG) rather than retrieved (RAG) — derived from the model context window
+ * instead of a fixed byte cliff. Reserve most of the window for the system
+ * prompt, conversation history, and the model's own output, and let attached
+ * documents occupy up to `docFraction` of what the window can hold. A larger
+ * window therefore admits larger documents in full; retrieval only kicks in
+ * for corpora that genuinely wouldn't fit. (A 52 KB doc is ~13k tokens — it
+ * fits comfortably in any modern window, so it should never be forced to RAG.)
+ */
+declare function cagCharBudget(contextWindowTokens: number, opts?: {
+    docFraction?: number;
+    charsPerToken?: number;
+}): number;
+/**
+ * Choose the retrieval mode for a run. Pure and deterministic so it's unit-
+ * testable and reusable across cloud, desktop, and CLI.
+ */
+declare function planRetrieval(ctx: RetrievalContext): RetrievalPlan;
+
+interface CodeChunker {
+    chunk(text: string, opts?: {
+        filename?: string;
+    }): Array<{
+        text: string;
+        ord: number;
+    }>;
+}
+interface CodeChunkOptions {
+    targetChars?: number;
+    /** Lines of trailing context carried into the next chunk when a segment is
+     *  hard-split (0 for whole-definition segments, which don't need it). */
+    overlapLines?: number;
+    filename?: string;
+}
+/**
+ * Chunk source code into definition-aligned, size-bounded pieces. Returns
+ * `{ text, ord }` in file order. Deterministic and dependency-free.
+ */
+declare function chunkCode(text: string, opts?: CodeChunkOptions): Array<{
+    text: string;
+    ord: number;
+}>;
+/** Default heuristic implementation of the CodeChunker seam. */
+declare const heuristicCodeChunker: CodeChunker;
+
+interface FileManifest {
+    /** repo-relative path → content hash (hex). */
+    files: Record<string, string>;
+    /** Fingerprint over the whole (sorted) manifest — equal roots ⇒ no changes. */
+    root: string;
+}
+interface ManifestDiff {
+    added: string[];
+    changed: string[];
+    removed: string[];
+    unchanged: string[];
+}
+declare function hashContent(content: string | Buffer): string;
+declare function buildManifest(entries: Array<{
+    path: string;
+    hash: string;
+}>): FileManifest;
+declare function diffManifest(oldManifest: FileManifest | null, next: FileManifest): ManifestDiff;
+
+interface WorkspaceIndexOptions {
+    root: string;
+    /** better-sqlite3 DB hosting vectors + the manifest. */
+    db: Database.Database;
+    embedder: Embedder;
+    reranker?: Reranker;
+    /** Predicate for paths to skip (e.g. CascadeIgnore.isIgnored bound to root). */
+    isIgnored?: (absPath: string) => boolean;
+    namespace?: string;
+    extensions?: string[];
+    maxFileBytes?: number;
+    chunker?: CodeChunker;
+}
+interface RefreshResult {
+    filesIndexed: number;
+    filesRemoved: number;
+    filesUnchanged: number;
+    chunks: number;
+    root: string;
+}
+declare class WorkspaceIndex {
+    private readonly root;
+    private readonly db;
+    private readonly store;
+    private readonly retriever;
+    private readonly namespace;
+    private readonly extensions;
+    private readonly maxFileBytes;
+    private readonly isIgnored;
+    private readonly chunker;
+    constructor(opts: WorkspaceIndexOptions);
+    private migrate;
+    /** Recursively collect indexable files under root (relative paths). */
+    private collectFiles;
+    private loadStoredManifest;
+    private saveManifest;
+    /**
+     * Scan the workspace and bring the index up to date, re-embedding only files
+     * whose contents changed since the last refresh. Returns what changed.
+     */
+    refresh(onFile?: (rel: string) => void): Promise<RefreshResult>;
+    /** Hybrid + reranked search over the indexed codebase. */
+    search(query: string, k?: number): Promise<ScoredChunk[]>;
+}
+
+/** The slice of world-state this retriever needs — so it's testable in isolation. */
+interface GraphFactSource {
+    getAllFacts(): WorldFact[];
+    getFactsForEntities(entities: string[]): WorldFact[];
+}
+interface GraphSearchOptions {
+    /** How many hops to expand from the seed entities (default 1). */
+    hops?: number;
+    /** Max facts to return. */
+    limit?: number;
+}
+interface RankedFact extends WorldFact {
+    /** Query-overlap score (higher = more relevant); 0 for pure hop-neighbors. */
+    score: number;
+    /** Hop distance from a seed entity (0 = seed). */
+    hop: number;
+}
+declare class GraphRetriever {
+    private readonly source;
+    constructor(source: GraphFactSource);
+    /**
+     * Retrieve facts relevant to a query, expanding the graph a few hops from the
+     * entities the query mentions. Returns facts ranked by relevance.
+     */
+    search(query: string, opts?: GraphSearchOptions): RankedFact[];
+    /** Human-readable "- entity relation value" lines for injection into a run. */
+    format(facts: RankedFact[]): string;
+}
+
+/**
+ * Lets a worker search the indexed workspace codebase by meaning + keywords and
+ * get back the most relevant passages with their file paths. Backed by the
+ * hybrid + reranked WorkspaceIndex, so it finds code by concept, not just exact
+ * string match.
+ */
+declare class CodeSearchTool extends BaseTool {
+    private readonly index;
+    readonly name = "code_search";
+    readonly description = "Search the indexed workspace codebase for code relevant to a query (semantic + keyword). Returns the most relevant snippets with their file paths. Use to find where something is implemented or how an API is used.";
+    readonly inputSchema: {
+        type: string;
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            k: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    constructor(index: WorkspaceIndex);
+    execute(input: Record<string, unknown>, _options: ToolExecuteOptions): Promise<string>;
+}
+
+/**
+ * Lets a worker query the project knowledge graph (world-state) for facts
+ * related to entities in the query, following relationships a couple of hops.
+ * Best for relational / multi-hop questions ("what depends on X?", "which
+ * component owns Y?") that vector search answers poorly.
+ */
+declare class GraphSearchTool extends BaseTool {
+    readonly name = "knowledge_graph_search";
+    readonly description = "Search the project knowledge graph (learned entity\u2192relation\u2192value facts) for information related to a query, expanding a couple of hops across relationships. Use for relational or multi-hop questions about the project.";
+    readonly inputSchema: {
+        type: string;
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            hops: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    private retriever;
+    constructor(source: GraphFactSource);
+    execute(input: Record<string, unknown>, _options: ToolExecuteOptions): Promise<string>;
+}
+
+interface DistilledFact {
+    entity: string;
+    relation: string;
+    value: string;
+}
+/** A run is worth distilling only if the conversation carried real content. */
+declare function sessionWorthRemembering(history: ConversationMessage[], latestPrompt: string, output: string): boolean;
+/**
+ * Build the transcript the distiller reads: recent history + the final turn,
+ * capped so a long session doesn't blow the distiller's budget.
+ */
+declare function buildSessionTranscript(history: ConversationMessage[], latestPrompt: string, output: string, maxChars?: number): string;
+/**
+ * Distill durable facts from a session transcript via one cheap model call.
+ * `generate` returns the model's raw text; parsing is defensive (a JSON array of
+ * triples anywhere in the reply). Never throws — returns [] on any problem.
+ */
+declare function distillSessionFacts(transcript: string, generate: (prompt: string) => Promise<string>): Promise<DistilledFact[]>;
+
 /** Structured log levels for audit entries */
 type LogLevel = 'debug' | 'info' | 'warn' | 'error';
 /** Extended audit entry with log level */
@@ -2783,4 +3521,211 @@ 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_CREDENTIALS_FILE, 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 };
+/**
+ * Best-effort guess of the canonical base model an Azure deployment backs, from
+ * its (arbitrary) deployment name. Ordered most-specific → least so "gpt-5-mini"
+ * doesn't match the "gpt-5" base. Distinct point releases (gpt-5.5, gpt-5.4,
+ * gpt-5.4-mini) resolve to their OWN base so their real economics + benchmark
+ * scores apply — only unrecognised gpt-5.x fold into the gpt-5 base.
+ * Returns null when the name gives no signal (e.g. "prod-fast") — the caller
+ * then keeps neutral defaults, or the user can set an explicit base model.
+ */
+declare function inferAzureBaseModel(deploymentName: string): string | null;
+/**
+ * The ModelInfo for one configured Azure deployment. On Azure the deployment IS
+ * the model (you address it by deployment name, and which base model backs it is
+ * opaque to the API) — so each `providers[]` entry with a deploymentName becomes
+ * one selectable model.
+ *
+ * Which base model it serves drives correct benchmark scoring + pricing, so we
+ * resolve it: an explicit `cfg.model` (user override) wins, else we infer it from
+ * the deployment name. When resolved to a known catalog model, this deployment
+ * INHERITS that model's real economics (context window, pricing, vision, output
+ * cap) while keeping the deployment name as its callable `id` and carrying the
+ * base identity in `baseModelId`. Unresolved deployments fall back to neutral
+ * GPT-4o-class defaults (an estimate, not $0), exactly as before.
+ */
+declare function azureModelForDeployment(cfg: ProviderConfig): ModelInfo | null;
+
+interface CloudUser {
+    id: string;
+    email: string | null;
+    name: string | null;
+    plan?: string;
+}
+interface CloudSession {
+    serverUrl: string;
+    accessToken: string;
+    /** Epoch ms when the access token expires (refresh before this). */
+    accessExpiresAt: number;
+    refreshToken: string;
+    user: CloudUser;
+}
+
+interface EncryptedBlob {
+    ciphertext: string;
+    salt: string;
+    iv: string;
+}
+declare function encryptJSON(data: unknown, passphrase: string): Promise<EncryptedBlob>;
+/** Throws (AES-GCM auth-tag check fails) on a wrong passphrase or tampered ciphertext. */
+declare function decryptJSON<T>(blob: EncryptedBlob, passphrase: string): Promise<T>;
+
+declare const DEFAULT_CLOUD_URL = "https://app.cascadeai.in";
+/** Providers the loopback flow can start (must match the server's `/auth/native/:provider`). */
+type NativeProvider = 'google' | 'github';
+interface DeviceStart {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    expiresIn: number;
+    interval: number;
+}
+interface CloudConversation {
+    id: string;
+    title: string;
+    /** Branching: leaf of the currently-selected path (null for an empty chat). */
+    activeLeafId?: string | null;
+    skillId?: string | null;
+    createdAt?: number;
+    updatedAt?: number;
+}
+interface CloudMessage {
+    /** Present on messages read from the server; absent on minimal echoes. */
+    id?: string;
+    /** Branching: the message this replies to (null = a root turn). */
+    parentId?: string | null;
+    role: string;
+    content: string;
+    tier?: string | null;
+    model?: string | null;
+    costUsd?: number | null;
+    /** JSON-encoded run-explorer report, or null. */
+    why?: string | null;
+    /** Branching: ids of this message + its siblings, oldest first (for < n/m >). */
+    siblingIds?: string[];
+}
+/** A locally-executed turn to persist into the cloud conversation tree. */
+interface CloudTurnInput {
+    userContent: string;
+    assistant: {
+        content: string;
+        tier?: string | null;
+        model?: string | null;
+        costUsd?: number | null;
+        why?: string | null;
+    };
+    /** Fork a sibling of this edited user turn (server derives the parent). */
+    editOfMessageId?: string;
+    /** Re-answer this user turn (reply saved as a sibling; no new user message). */
+    regenerateFromUserMessageId?: string;
+}
+type DevicePollResult = 'pending' | 'slow_down' | 'expired' | {
+    session: CloudSession;
+};
+/**
+ * Where the signed-in session persists. The CLI uses the default file store
+ * (`~/.cascade-ai/cloud-session.json`, 0600); the desktop injects a
+ * `safeStorage`-backed one. Kept tiny so any host can implement it.
+ */
+interface CloudSessionStore {
+    load(): CloudSession | null;
+    save(session: CloudSession): void;
+    clear(): void;
+}
+declare class CloudClient {
+    private readonly serverUrl;
+    private readonly store;
+    constructor(serverUrl: string, dir?: string, store?: CloudSessionStore);
+    /** Build a client from a stored session, or null if not signed in. */
+    static fromSession(dir?: string, store?: CloudSessionStore): CloudClient | null;
+    private url;
+    startDevice(): Promise<DeviceStart>;
+    /** Single poll of the device grant. On approval, persists + returns the session. */
+    pollDevice(deviceCode: string): Promise<DevicePollResult>;
+    /**
+     * Run the full device flow: start it, hand the code to `onCode`, then poll at
+     * the server's interval until approved or expired.
+     */
+    runDeviceLogin(onCode: (d: DeviceStart) => void, opts?: {
+        signal?: AbortSignal;
+    }): Promise<CloudSession>;
+    /**
+     * Run the loopback flow for a rich native client (the desktop). Opens a
+     * one-shot listener on `http://127.0.0.1:<random>`, sends the user to the
+     * provider in the system browser via `openUrl`, catches the one-time code on
+     * the loopback redirect, and exchanges it (+ the PKCE verifier) for tokens.
+     *
+     * No secret is involved: PKCE S256 proves the client that started the flow is
+     * the one redeeming the code. Storage-agnostic — persists through the same
+     * session store as the device flow, so callers get a ready `CloudSession`.
+     */
+    runLoopbackLogin(openUrl: (url: string) => void | Promise<void>, opts?: {
+        provider?: NativeProvider;
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<CloudSession>;
+    /** Exchange a fresh token response for a stored session (fetches the user). */
+    private finishLogin;
+    private session;
+    private refresh;
+    private accessToken;
+    /** Authenticated request that refreshes once on a 401 (e.g. server-side revoke). */
+    private authed;
+    private authedGet;
+    private fetchMe;
+    me(): Promise<CloudUser>;
+    listConversations(): Promise<CloudConversation[]>;
+    getMessages(conversationId: string): Promise<CloudMessage[]>;
+    /** Start a new cloud conversation and return it. */
+    createConversation(title?: string): Promise<CloudConversation>;
+    /** Persist a locally-executed turn; returns the new active path (with siblings). */
+    appendTurn(conversationId: string, turn: CloudTurnInput): Promise<CloudMessage[]>;
+    /** Branching: switch the active path to a sibling; returns the new path. */
+    selectBranch(conversationId: string, messageId: string): Promise<CloudMessage[]>;
+    /** Branching: delete a message and its subtree; returns the new path. */
+    deleteMessage(conversationId: string, messageId: string): Promise<CloudMessage[]>;
+    renameConversation(conversationId: string, title: string): Promise<void>;
+    deleteConversation(conversationId: string): Promise<void>;
+    /** Fetch the stored encrypted settings envelope (ciphertext only), or null. */
+    pullSecrets(): Promise<{
+        blob: EncryptedBlob | null;
+        version?: number;
+        updatedAt?: number;
+    }>;
+    /** Store/replace the encrypted settings envelope. The server never decrypts it. */
+    pushSecrets(blob: EncryptedBlob): Promise<{
+        version: number;
+        updatedAt: number;
+    }>;
+    /** Forget the stored envelope on the server. */
+    deleteSecrets(): Promise<void>;
+    logout(): Promise<void>;
+}
+
+interface SyncBundle {
+    v: 1;
+    /** LLM provider keys / endpoints. */
+    providers?: ProviderConfig[];
+    /** Web-search backend keys (Brave / Tavily) + SearXNG URL. */
+    webSearch?: WebSearchConfig;
+    /** MCP servers / connectors (headers carry auth). */
+    mcpServers?: McpServerConfig$1[];
+    /** Per-tier model overrides (non-secret). */
+    models?: ModelOverrides;
+    /** Budget caps (non-secret). */
+    budget?: BudgetConfig;
+    /** Assorted non-secret preferences. */
+    prefs?: {
+        autoBias?: 'balanced' | 'quality' | 'cost';
+        cascadeAuto?: boolean;
+        extendedContext?: ExtendedContextConfig;
+        autonomy?: 'manual' | 'auto';
+    };
+}
+/** Pluck the portable subset of a config into a bundle (undefined fields omitted). */
+declare function gatherSyncBundle(config: CascadeConfig): SyncBundle;
+/** Merge a pulled bundle into a config, returning the updated config to persist. */
+declare function applySyncBundle(bundle: SyncBundle, config: CascadeConfig): CascadeConfig;
+
+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, CHARS_PER_TOKEN, COMPLEXITY_T2_COUNT, Cascade, CascadeCancelledError, type CascadeConfig, type CascadeEvent, type CascadeEventType, CascadeIgnore, type CascadeMessage, CascadeRouter, type CascadeRunOptions, type CascadeRunResult, type CascadeThemeName, CascadeToolError, type Chunk, type ChunkOptions, CloudClient, type CloudConversation, type CloudMessage, type CloudSession, type CloudSessionStore, type CloudTurnInput, type CloudUser, type CodeChunkOptions, type CodeChunker, CodeSearchTool, type CompleteFn, ConfigManager, type ConversationMessage, DEFAULT_API_PORT, DEFAULT_APPROVAL_REQUIRED, DEFAULT_AUTO_SUMMARIZE_AT, DEFAULT_CLOUD_URL, DEFAULT_CONTEXT_LIMIT, DEFAULT_DASHBOARD_PORT, DEFAULT_MAX_SESSION_MESSAGES, DEFAULT_RETENTION_DAYS, DEFAULT_THEME, type DashboardConfig, DashboardServer, type DeviceStart, type DistilledFact, type Embedder, type EncryptedBlob, type EscalationPayload, type ExtendedContextConfig, type FileManifest, FileMcpOAuthStore, GLOBAL_CONFIG_DIR, GLOBAL_CREDENTIALS_FILE, GLOBAL_DB_FILE, GLOBAL_KEYSTORE_FILE, GLOBAL_RUNTIME_DB_FILE, type GenerateOptions, type GenerateResult, type GraphFactSource, GraphRetriever, type GraphSearchOptions, GraphSearchTool, type HookDefinition, type HooksConfig, HooksRunner, type Identity, type ImageAttachment, Keystore, LLMReranker, LM_STUDIO_BASE_URL, type LegacyThemeName, MODELS, type ManifestDiff, McpClient, McpOAuthProvider, type McpOAuthState, type McpOAuthStore, type McpServerConfig$1 as McpServerConfig, type MemoryConfig, MemoryStore, type Message, type MessageContent, type MessagePayload, type MessageStatus, type MessageType, type ModelInfo, type ModelOverrides, type NativeProvider, OLLAMA_BASE_URL, OpenAICompatibleEmbedder, type OpenAIEmbedderOptions, 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 RankedFact, type RefreshResult, type Reranker, type RetrievalContext, type RetrievalMode, type RetrievalPlan, Retriever, type RetrieverSearchOptions, type RuntimeNode, type RuntimeNodeLog, type RuntimeRefreshPayload, type RuntimeScope, type RuntimeSession, type RuntimeSnapshotPayload, type ScheduledTask, type ScoredChunk, type SearchOptions, type Session, type SessionCheckpoint, type SessionMetadata, type SessionSubscriptionPayload, SqliteVectorStore, type StatusUpdate, type StoredMessage, type StreamChunk, type SyncBundle, 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 VectorStore, type WebSearchConfig, type WebhookConfig, type WorkspaceConfig, WorkspaceIndex, type WorkspaceIndexOptions, applySyncBundle, azureModelForDeployment, beginMcpOAuth, buildManifest, buildSessionTranscript, cagCharBudget, chatCompleterFromProviders, chunkCode, chunkText, completeMcpOAuth, connectMcpWithLoopbackOAuth, createCascade, decryptJSON as decryptSyncBlob, diffManifest, discoverMcpAuthServer, distillSessionFacts, embedderFromProviders, encryptJSON as encryptSyncBlob, fileOAuthProvider, gatherSyncBundle, hashContent, heuristicCodeChunker, inferAzureBaseModel, nodeHttpFetch, parseRankOrder, planRetrieval, preferIpv4Host, reciprocalRankFusion, refreshMcpToken, runCascade, sessionWorthRemembering, streamCascade };