cascade-ai 0.53.0 → 0.55.0

package/dist/index.d.cts

@@ -192,6 +192,33 @@ interface ToolResult {
     output: string;
     isError: boolean;
 }
+/**
+ * What to do about a section that escalated — a worker hit something it could
+ * not decide alone.
+ *
+ * `timeout` is a real outcome, not an error: a cloud run holds server resources
+ * while it waits, so an unanswered escalation fails the section rather than
+ * hanging indefinitely. The section reports WHY it failed, so an unattended run
+ * is diagnosable rather than merely dead.
+ */
+interface EscalationDecision {
+    action: 'retry' | 'skip' | 'guidance' | 'timeout';
+    /** Required for 'guidance' — the instruction the retry must follow. */
+    note?: string;
+    /**
+     * Set when the SDK produced `action: 'skip'` itself — no listener wired,
+     * `autonomy: 'auto'`, or the run was aborted — rather than a person
+     * answering the prompt. `resolveEscalation()`, the one path a human
+     * response reaches, never sets this.
+     *
+     * A skip decided by the system is not the same fact as a skip a user
+     * chose: T2's `userSkipped` marker (which tells T1's reviewer "accept this
+     * as satisfied, not a gap") must NOT be set for the automatic case — a
+     * section nobody ever looked at is exactly the case a corrective pass
+     * exists to catch.
+     */
+    automatic?: boolean;
+}
 interface ToolExecuteOptions {
     tierId: string;
     sessionId: string;
@@ -294,6 +321,19 @@ interface T2Result {
     t3Results: T3Result[];
     sectionSummary: string;
     issues: 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
+     * it incomplete. T1's reviewer pass sees only the section summary, so
+     * without this flag it cannot tell "the model gave up" from "the user
+     * decided this was good enough" and would generate a correction plan that
+     * redoes exactly the work the user just chose to keep as-is.
+     *
+     * NOT set when the 'skip' came from `EscalationDecision.automatic` — no
+     * listener wired, `autonomy: 'auto'`, or an aborted run. Nobody reviewed
+     * that section, so it must stay eligible for the corrective pass.
+     */
+    userSkipped?: boolean;
 }
 interface T3ResultPayload {
     subtaskId: string;
@@ -904,6 +944,16 @@ declare class ModelSelector {
      */
     private discovered;
     constructor(availableProviders: Set<ProviderType>);
+    /**
+     * Verdicts from earlier runs about ids that 404 on this account. Consulted
+     * BEFORE a model enters the pool, which is the only placement that helps: a
+     * T3 wave runs concurrently, so filtering after the first failure still lets
+     * every other worker in the wave call the dead id.
+     */
+    private deadModels?;
+    setDeadModelStore(store: {
+        isDead(provider: string, modelId: string): boolean;
+    }): void;
     addDynamicModel(model: ModelInfo): void;
     /** Record the ids a provider's API actually serves (discovery). Empty ⇒ ignored. */
     setValidatedModels(provider: ProviderType, ids: string[]): void;
@@ -1077,6 +1127,60 @@ declare class TaskAnalyzer {
     static clearCache(): void;
 }
 
+interface DeadModelRecord {
+    /** `provider:modelId` — the same key shape the failover event reports. */
+    key: string;
+    provider: string;
+    modelId: string;
+    /** Provider's own words, kept verbatim so the user can act on them. */
+    reason: string;
+    firstSeenAt: number;
+    lastSeenAt: number;
+    /** How many times this model has been found dead. */
+    hits: number;
+}
+/**
+ * Where records live between runs. Desktop/CLI back this with a JSON file,
+ * the cloud server with a per-user table. Both are synchronous-optional: a
+ * store that fails to load must never stop a run.
+ */
+interface DeadModelPersistence {
+    load(): DeadModelRecord[];
+    save(records: DeadModelRecord[]): void;
+}
+declare class DeadModelStore {
+    private persistence?;
+    private records;
+    private readonly ttlMs;
+    private readonly now;
+    constructor(persistence?: DeadModelPersistence | undefined, opts?: {
+        ttlMs?: number;
+        now?: () => number;
+    });
+    private restore;
+    private isExpired;
+    private flush;
+    /**
+     * Record that a model was found dead. Returns true when this is the first
+     * time (so the caller can log it once rather than once per concurrent
+     * worker in the wave that discovered it).
+     */
+    record(provider: string, modelId: string, reason: string): boolean;
+    /** True when this model is known dead and the verdict has not expired. */
+    isDead(provider: string, modelId: string): boolean;
+    /** Why a model is considered dead, for /why and the models command. */
+    reasonFor(provider: string, modelId: string): string | null;
+    /** Live records, expired ones filtered out. */
+    list(): DeadModelRecord[];
+    /**
+     * Forget a verdict — used when the user fixes the underlying problem (adds
+     * the model to their project, gets quota) and wants it retried now rather
+     * than after the TTL.
+     */
+    forget(provider: string, modelId: string): boolean;
+    clear(): void;
+}
+
 declare class MemoryStore {
     private db;
     constructor(dbPath: string);
@@ -1505,10 +1609,38 @@ declare class CascadeRouter extends EventEmitter {
      */
     private budgetState;
     private budgetExceededReason;
+    /**
+     * Whether the run/session budget is permanently tripped, and why.
+     *
+     * A tier or worker that catches `BudgetExceededError` internally (T3Worker
+     * does, so one dead-end subtask doesn't crash the whole run) absorbs the
+     * exception into a normal FAILED/PARTIAL result — the tier returns as if
+     * nothing unusual happened. That silently skips `Cascade.run()`'s dedicated
+     * budget-exceeded handling (the `run:budget-exceeded` event and
+     * `lastInterruptedRun` for `/continue`). This lets a caller check the
+     * router's own state directly after a tier returns, regardless of how that
+     * tier chose to report the error internally.
+     */
+    budgetExceededInfo(): {
+        reason: string;
+    } | null;
     private tpmLimiter;
     private localQueue;
     private taskAnalyzer?;
     private pendingFeedbackSource?;
+    /** Models known dead for this account (404 / retired / not enabled). */
+    private deadModels;
+    /**
+     * Back the dead-model memory with durable storage (a JSON file on desktop, a
+     * per-user table in the cloud). Without one the verdicts still work, but only
+     * for the life of the process — so tomorrow's run pays the same wave of 404s
+     * to learn the same fact.
+     */
+    setDeadModelStore(store: DeadModelStore): void;
+    /** Models known dead for this account, for `cascade models` and /why. */
+    listDeadModels(): ReturnType<DeadModelStore['list']>;
+    /** Retry a model the user has since fixed, without waiting out the TTL. */
+    forgetDeadModel(provider: string, modelId: string): boolean;
     private worldStateDB?;
     private privacyPaths?;
     private guidanceQueue?;
@@ -1866,8 +1998,17 @@ declare class ToolRegistry extends EventEmitter {
     registerPlugin(plugin: ToolPlugin): void;
     /** Returns the names of all registered plugins */
     getRegisteredPlugins(): string[];
-    /** Registers all tools from an MCP client */
-    registerMcpTools(mcpClient: McpClient): void;
+    /**
+     * Registers all tools from an MCP client.
+     *
+     * `isAllowed` receives the FINAL registered name (`mcp__server__tool`) — the
+     * same string the user sees and the same one that reaches the provider — so
+     * a per-tool opt-out in Settings can be expressed as a plain name list.
+     * Filtering here rather than at call time means a deselected tool is genuinely
+     * absent from the definitions handed to the model, so it is never proposed,
+     * never counted against the tool budget, and never has to be refused.
+     */
+    registerMcpTools(mcpClient: McpClient, isAllowed?: (registeredName: string) => boolean): void;
     setIgnoredPaths(patterns: string[]): void;
     getToolDefinitions(): ToolDefinition[];
     getTool(name: string): BaseTool | undefined;
@@ -2134,6 +2275,7 @@ declare class T1Administrator extends BaseTier {
     private escalations;
     private store?;
     private runBreaker?;
+    private escalationCallback?;
     private t2PeerBus;
     private permissionEscalator?;
     private toolCreator?;
@@ -2143,6 +2285,13 @@ declare class T1Administrator extends BaseTier {
     private peerMessageSessionId;
     private planApprovalCallback?;
     constructor(router: CascadeRouter, toolRegistry: ToolRegistry, config: CascadeConfig);
+    /** Ask the user what to do when any section escalates. */
+    setEscalationCallback(cb: (ctx: {
+        sectionId: string;
+        sectionTitle: string;
+        issues: string[];
+        summary: string;
+    }) => Promise<EscalationDecision>): void;
     /** Share the run-wide circuit breaker with every section manager. */
     setRunBreaker(breaker: RunBreaker): void;
     setStore(store: MemoryStore): void;
@@ -2212,6 +2361,34 @@ interface GeneratedAsset {
  */
 type AssetSink = (asset: GeneratedAsset) => Promise<string>;
 
+/** What the host's browser view can tell us about the page on screen. */
+interface CurrentPageSnapshot {
+    url: string;
+    title: string;
+    /** Rendered visible text, host-truncated if enormous. */
+    text: string;
+}
+/**
+ * Returns the page the user is currently viewing, or null when the browser is
+ * closed / on a blank tab.
+ */
+type CurrentPageProvider = () => Promise<CurrentPageSnapshot | null>;
+/** Characters of page text handed to a model in one call. */
+declare const MAX_PAGE_TEXT_CHARS = 40000;
+declare class CurrentPageTool extends BaseTool {
+    readonly name = "read_current_page";
+    readonly description: string;
+    readonly inputSchema: {
+        type: string;
+        properties: {};
+        required: never[];
+    };
+    private provider;
+    constructor(provider: CurrentPageProvider);
+    isDangerous(): boolean;
+    execute(_input: Record<string, unknown>, _options: ToolExecuteOptions): Promise<string>;
+}
+
 /** One entry in the per-run orchestration decision trail (see /why). */
 interface DecisionLogEntry {
     at: string;
@@ -2278,6 +2455,32 @@ declare class Cascade extends EventEmitter {
     resolveMcpApproval(serverName: string, approved: boolean): void;
     private pendingPlanApproval?;
     private requestPlanApproval;
+    private pendingEscalations;
+    private requestEscalationDecision;
+    /**
+     * Resolve a pending escalation from a REPL / dashboard / cloud listener.
+     *
+     * `requestId` comes back from the `escalation:decision-required` event and is
+     * what makes an answer land on the section that asked. It is optional so a
+     * host with only one escalation in flight (and any caller that predates the
+     * id) still works: without it the oldest outstanding request is answered,
+     * which is correct whenever there is exactly one.
+     *
+     * `automatic` defaults to false — a call into this method is normally a real
+     * person answering the prompt. Pass `true` from a host that is itself
+     * settling the gate on nobody's behalf (a REST caller who never had a
+     * chance to connect, a session halt with no per-section review behind it),
+     * so T2 doesn't set `userSkipped` for a decision no one actually reviewed —
+     * see EscalationDecision.automatic.
+     */
+    resolveEscalation(action: EscalationDecision['action'], note?: string, requestId?: string, automatic?: boolean): void;
+    /**
+     * Release every parked escalation — run teardown, so none outlive the run.
+     * `automatic: true`: teardown resolving a section nobody answered is the
+     * same system-decided case as the early-return skips above, not a person
+     * reviewing and accepting that section's output.
+     */
+    private releasePendingEscalations;
     /**
      * Resolve a pending boardroom plan approval from a REPL / dashboard listener.
      * An optional `note` re-plans and re-asks; an optional `editedPlan` is applied
@@ -2328,6 +2531,17 @@ declare class Cascade extends EventEmitter {
      * existing tools rather than duplicating them.
      */
     setMediaSink(sink: AssetSink): void;
+    /**
+     * Let the agent read the page the user has open in the host's browser.
+     *
+     * Host-supplied because only a host WITH a browser can answer it — so the
+     * tool is simply absent in the CLI and in hosted runs, rather than present
+     * and always failing. Registered outside `enabledTools` for the same reason
+     * media tools are: that allowlist is a blast-radius control for tools that
+     * touch the machine, and reading a page the user already opened touches
+     * nothing. `disabledTools` still removes it.
+     */
+    setCurrentPageProvider(provider: CurrentPageProvider): void;
     private registerMediaTools;
     /**
      * Supply per-model thumbs-up/down counts so Auto routing can weigh how models
@@ -2575,6 +2789,19 @@ declare class T2Manager extends BaseTier {
     private t2PeerBus?;
     private permissionEscalator?;
     private toolCreator?;
+    /**
+     * Asked when a section ends ESCALATED — i.e. a worker hit something it could
+     * not decide alone. Without this the escalation was a dead end: the status
+     * said "needs a decision" and no decision was ever requested, so an MCP run
+     * that legitimately needed input just stopped there.
+     */
+    private escalationCallback?;
+    /**
+     * The one allowed retry has been spent. Retrying is bounded because an
+     * escalation loop that can re-ask forever burns a budget on a question that
+     * is not resolving; a second escalation is terminal instead.
+     */
+    private escalationRetryUsed;
     /** Optional boardroom gate (Moderate / root-T2 runs) — pauses after decomposition. */
     private planApprovalCallback?;
     /** AbortController for the current T3 wave — aborted on cancel-and-respawn */
@@ -2596,6 +2823,13 @@ declare class T2Manager extends BaseTier {
      */
     setPermissionEscalator(escalator: PermissionEscalator): void;
     setToolCreator(creator: ToolCreator): void;
+    /** Ask the user what to do when a section escalates. */
+    setEscalationCallback(cb: (ctx: {
+        sectionId: string;
+        sectionTitle: string;
+        issues: string[];
+        summary: string;
+    }) => Promise<EscalationDecision>): void;
     /** Boardroom gate for Moderate (root-T2) runs: pause after decomposition. */
     setPlanApprovalCallback(cb: (subtasks: ReadonlyArray<{
         subtaskId: string;
@@ -2887,6 +3121,50 @@ declare class ConfigManager {
     getApiKey(provider: string): string | undefined;
     private loadConfig;
     private injectEnvKeys;
+    /**
+     * Follow a disambiguation rename into `tools.mcpTrusted`.
+     *
+     * `mcpTrusted` is matched by EXACT name (`McpClient.connect()`). Two shapes
+     * of rename reach here, and they need OPPOSITE treatment:
+     *
+     * - Distinct raw names that only collide via sanitizing (`foo bar` /
+     *   `foo@bar`): each had its OWN trust entry, and the old string now belongs
+     *   to nothing — the server that used it moved away, so the entry has to
+     *   move with it. A plain rewrite is correct here.
+     * - Literally identical names (a hand-edited or duplicated config: two rows
+     *   both named `foo`): there is only ONE trust entry for both, since
+     *   `mcpTrusted` itself is deduplicated. `this.config.tools.mcpServers` has
+     *   already been updated to the disambiguated list by the time this runs
+     *   (see `load()`), so the untouched survivor is STILL named `foo` — a plain
+     *   rewrite would move the one entry entirely onto the renamed row and
+     *   leave the survivor untrusted. The entry must be kept for the survivor
+     *   AND granted to the renamed identity, not moved.
+     *
+     * Renames are grouped by `from` before either treatment is applied, and
+     * each group is settled in one step. Two DIFFERENT rows can start out with
+     * the exact same raw name and BOTH get renamed away (e.g. three servers
+     * named `foo bar`, `foo@bar`, `foo@bar` — the two `foo@bar` rows collide
+     * with `foo bar` and with each other, so both are renamed to distinct
+     * identities while `foo bar` survives untouched). Processing renames one at
+     * a time in that shape drops coverage: the first rename's REPLACE branch
+     * would erase `from` from `trusted` entirely, so the guard on the second
+     * rename with the same `from` sees it already gone and silently skips —
+     * granting trust to only one of the two renamed identities. Grouping first
+     * means every renamed identity that shares a `from` is added or substituted
+     * together, in the one pass that still sees the original entry.
+     *
+     * `tools.disabledTools` deliberately gets no equivalent treatment. It's
+     * matched by sanitized PREFIX, and a prefix collision is exactly what made
+     * an existing entry ambiguous between the two servers in the first place —
+     * there is no way to tell, from the stored string alone, which of the two
+     * a denial was meant for. Leaving those entries untouched resolves that
+     * ambiguity for free: the survivor keeps the original (now unique) prefix,
+     * so an old entry keeps applying to it, while the renamed server starts
+     * clean under its new prefix. Rewriting the entry to follow the rename
+     * would do the opposite — move a denial that already worked for the
+     * survivor onto a server it may never have meant to cover.
+     */
+    private renameMcpServerReferences;
     private ensureDefaultIdentity;
 }
 
@@ -2900,6 +3178,10 @@ declare class DashboardSocket {
     private authRequired;
     private secret;
     constructor(httpServer: Server, options: DashboardSocketOptions);
+    /** How many sockets are currently in a room — 0 means nobody can answer. */
+    roomSize(room: string): number;
+    /** Is this exact connection still live? A reconnect issues a NEW socket id. */
+    hasSocket(socketId: string): boolean;
     broadcastToRoom(room: string, event: string, data: unknown): void;
     broadcast(event: string, data: unknown): void;
     emitCascadeEvent(ev: CascadeEvent): void;
@@ -2909,6 +3191,15 @@ declare class DashboardSocket {
     emitApprovalRequest(request: PermissionRequest): void;
     onApprovalResponse(callback: (data: PermissionDecisionPayload) => void): void;
     private setupHandlers;
+    /**
+     * A client subscribed to a session's room.
+     *
+     * The host uses this to replay a gate the run is already parked on. Socket.IO
+     * does not buffer room emissions, so a prompt broadcast while the renderer was
+     * reconnecting is simply gone; without a replay the section waits out its full
+     * timeout with the user sitting in front of a screen that never asked.
+     */
+    onJoinSession(callback: (sessionId: string, socketId: string) => void): void;
     onSessionRate(callback: (sessionId: string, rating: 'good' | 'bad') => void): void;
     onSessionHalt(callback: (sessionId: string) => void): void;
     /**
@@ -2922,6 +3213,20 @@ declare class DashboardSocket {
         note?: string;
         editedPlan?: unknown;
     }) => void): void;
+    /**
+     * A section escalated and the run is parked waiting for an answer. The
+     * desktop shows the escalation modal on `escalation:decision-required` and
+     * answers here.
+     *
+     * Unlike a plan decision, silence is NOT taken as consent — the SDK fails
+     * the section on timeout — so this handler only ever forwards a real choice.
+     */
+    onEscalationDecision(callback: (data: {
+        sessionId: string;
+        requestId?: string;
+        action: 'retry' | 'skip' | 'guidance';
+        note?: string;
+    }) => void): void;
     onSessionSteer(callback: (message: string, sessionId?: string, nodeId?: string) => void): void;
     onConfigUpdate(callback: (data: {
         keys?: Record<string, string>;
@@ -2947,6 +3252,13 @@ declare class DashboardServer {
     private globalStore;
     private broadcastTimer;
     private activeSessions;
+    /**
+     * Supplied by the desktop shell so a run can read the page the user has
+     * open in the built-in browser. Absent in the CLI, where there is no
+     * browser — so the tool is simply not registered rather than present and
+     * always failing.
+     */
+    private currentPageProvider?;
     private activeControllers;
     /**
      * Run taskIds per chat session — file snapshots are keyed by the run's
@@ -2961,6 +3273,17 @@ declare class DashboardServer {
      * map is how that answer reaches the run that's blocked on it.
      */
     private pendingApprovals;
+    /**
+     * The escalation prompt a session is currently parked on, kept so it can be
+     * delivered to a client that was not reachable when it was raised.
+     *
+     * Socket.IO buffers nothing: a prompt emitted while the renderer is mid
+     * reconnect is gone, and the section then waits out its full five minutes
+     * with the user in front of a screen that never asked them anything. Holding
+     * the payload lets `join:session` replay it, and lets a run with no reachable
+     * client be settled instead of parked (see ORPHANED_ESCALATION_GRACE_MS).
+     */
+    private pendingEscalations;
     /**
      * The orchestration decision trail ("why") of each session's most recent
      * run — captured when the run ends so the desktop's Why panel can show it
@@ -2973,6 +3296,8 @@ declare class DashboardServer {
     private host;
     private workspacePath;
     constructor(config: CascadeConfig, store: MemoryStore, workspacePath?: string);
+    /** Wire the host's browser view in (desktop only). */
+    setCurrentPageProvider(provider: CurrentPageProvider): void;
     start(): Promise<void>;
     stop(): Promise<void>;
     getSocket(): DashboardSocket;
@@ -3039,6 +3364,66 @@ declare class DashboardServer {
      * client so an open desktop sees the run appear live.
      */
     private runScheduledTask;
+    /**
+     * Is anyone able to answer for this session right now?
+     *
+     * The originating socket first — that connection is definitely watching this
+     * run — then the session room, which is where a client lands after a
+     * reconnect issues it a new socket id.
+     */
+    private hasResponder;
+    /**
+     * Send a run event to whoever is watching this session.
+     *
+     * A captured socket id goes stale the moment Socket.IO reconnects — the
+     * client is back, but under a new id, and `emitToSocket` on the old one is a
+     * silent no-op. Falling back to the session room keeps the run addressable
+     * across a reconnect; emitting to one OR the other (never both) keeps a
+     * client that is both the originator and a room member from seeing every
+     * token twice.
+     */
+    private emitToSessionClients;
+    /**
+     * Raise an escalation prompt, and make sure it can still be answered.
+     *
+     * Held in `pendingEscalations` — keyed by requestId, because a Complex wave
+     * dispatches sections concurrently and two can be parked at once — so a
+     * client that joins late (or rejoins after a reconnect) gets every waiting
+     * prompt replayed. Keying by session would drop the first of a pair: its
+     * grace timer would be cleared by the second, leaving it parked for the full
+     * timeout with nobody able to answer it. If nobody is reachable at all, the gate is
+     * settled as `skip` after a short grace period rather than parked for the
+     * full timeout: that matches the SDK's policy when no listener exists, and
+     * five minutes of a held run is a real cost for a REST caller who has already
+     * hung up. The grace period exists so an ordinary two-second reconnect is not
+     * mistaken for an absent user.
+     */
+    private raiseEscalation;
+    /**
+     * Replay EVERY parked prompt to a client that just subscribed to the session.
+     *
+     * Plural because a Complex run dispatches sections concurrently, so a wave can
+     * leave more than one waiting at the same time — the same reason the SDK keys
+     * its gates and the clients queue theirs.
+     *
+     * `timeoutMs` is recomputed as the time actually LEFT, because the SDK's timer
+     * has been running since the prompt was raised. Sent verbatim, a client
+     * reconnecting four minutes in would show a fresh five-minute countdown and
+     * then watch the section fail with four of those minutes still on the clock.
+     * A remaining duration is used rather than an absolute deadline so the two
+     * sides never have to agree on a wall clock.
+     */
+    private replayEscalations;
+    /** Forget ONE parked prompt — the one that was answered or timed out. */
+    private clearPendingEscalation;
+    /**
+     * Forget the session's OLDEST prompt — for a client that answered without a
+     * requestId, which is exactly the gate `resolveEscalation` will settle.
+     * Insertion order makes `values()` oldest-first.
+     */
+    private clearOldestSessionEscalation;
+    /** Forget every prompt a session was parked on (run ended, or halted). */
+    private clearSessionEscalations;
     /** Deny + clear any approvals still pending for a session (run end / abort). */
     private denyPendingApprovals;
     private persistRuntimeRow;
@@ -3185,6 +3570,104 @@ declare function connectMcpWithLoopbackOAuth(opts: {
     timeoutMs?: number;
 }): Promise<LoopbackOAuthResult>;
 
+/** One tool a server advertises, named exactly as it is registered at run time. */
+interface DiscoveredMcpTool {
+    /** The server that advertises it. */
+    server: string;
+    /** The server-side tool name (what the vendor calls it). */
+    tool: string;
+    /** The registered name — `mcp__server__tool`. This is the selection key. */
+    name: string;
+    description: string;
+}
+interface McpDiscoveryResult {
+    server: string;
+    tools: DiscoveredMcpTool[];
+    /** Set when the server could not be reached or refused the connection. */
+    error?: string;
+}
+/**
+ * Connect to each server, list its tools, disconnect.
+ *
+ * Servers are pre-trusted here because the caller has already added them —
+ * discovery reads a list, it never invokes anything. A server that fails is
+ * reported with its error rather than throwing, so one dead connector cannot
+ * blank out the Settings panel for the working ones.
+ */
+declare function discoverMcpTools(servers: McpServerConfig$1[]): Promise<McpDiscoveryResult[]>;
+
+/** Prefix marking a tool that came from an MCP server. */
+declare const MCP_TOOL_PREFIX = "mcp__";
+/** Provider-safe name for a tool exposed by an MCP server. Bounded — see MAX_MCP_TOOL_NAME_LENGTH. */
+declare function mcpToolName(serverName: string, toolName: string): string;
+declare function isMcpToolName(name: string): boolean;
+/**
+ * A name for a NEW MCP server connection that won't collide, on its sanitized
+ * tool prefix, with any name already in use.
+ *
+ * Compared by prefix, not by the raw name: `foo bar` and `foo@bar` are
+ * different strings but both register as `mcp__foo_bar__…`, so a check against
+ * raw names would accept a pair that still collides downstream — the exact gap
+ * that let two connectors' tools overwrite each other in the registry.
+ *
+ * Mirrored on the cloud side (`cloud/server/src/db.ts` `uniqueMcpServerName`,
+ * DB-backed instead of array-backed) — kept in sync by hand since the two sides
+ * don't share a runtime, but the algorithm and suffix format must match or a
+ * name that's unique on one side could still collide on the other after a sync
+ * pull (see `mergeMcpServers` in `src/cloud/keysync.ts`, which performs the
+ * same comparison for that reason).
+ */
+declare function uniqueMcpServerName(desired: string, existingNames: string[]): string;
+/** One entry renamed by `disambiguateMcpServerNames`, so callers can follow it. */
+interface McpServerRename {
+    from: string;
+    to: string;
+}
+/**
+ * Rename pre-existing entries whose sanitized prefixes collide.
+ *
+ * For config loaded from disk (desktop and CLI share one config file), rather
+ * than a fresh connection — `uniqueMcpServerName` only guards a NEW entry, so a
+ * file that already contains a colliding pair (hand-edited, or written by a
+ * CLI version that predates the check) stays broken until something touches it.
+ * The FIRST entry of each colliding group keeps its name, since that connection
+ * is presumably already working; later ones are suffixed exactly as
+ * `uniqueMcpServerName` would have produced had they been added after this
+ * existed. A no-op when nothing collides, so callers can run it unconditionally
+ * on every load without needing a one-time migration flag.
+ *
+ * A server's name is referenced elsewhere in config — `tools.mcpTrusted`
+ * (`McpClient.connect()` matches it exactly) and `tools.disabledTools`
+ * (matched by sanitized prefix). This function only owns `mcpServers`, so it
+ * returns the rename list rather than reaching into config fields it doesn't
+ * know about; the caller applies it to whatever else keys off the old name.
+ */
+declare function disambiguateMcpServerNames<T extends {
+    name: string;
+}>(servers: T[]): {
+    servers: T[];
+    renames: McpServerRename[];
+};
+/**
+ * Prefix matching every tool from one server, for filtering.
+ *
+ * Also lets a host drop a server's per-tool selections when the server itself
+ * is removed — otherwise a tool switched off before removal stays off when the
+ * same connector is added back, with nothing on screen explaining why.
+ */
+declare function mcpServerPrefix(serverName: string): string;
+/**
+ * Drop one removed server's entries from a deny list.
+ *
+ * The deny list lives as one flat array, not scoped per server, so removing a
+ * connector without this left its denials behind — reconnecting the SAME name
+ * later silently re-disabled tools the user had switched off in a previous
+ * life of that connection, with nothing on screen explaining why. Shared by
+ * every removal path (desktop IPC, `cascade mcp remove`) so the behavior can't
+ * drift between them the way the duplicated inline version risked.
+ */
+declare function removeMcpServerDenials(disabledTools: string[] | undefined, serverName: string): string[] | undefined;
+
 /** A unit of indexed text. `sourceId` groups chunks from one document/file. */
 interface Chunk {
     id: string;
@@ -3972,14 +4455,39 @@ declare class CloudClient {
     logout(): Promise<void>;
 }
 
+/**
+ * Bundle format version.
+ *
+ * 1 — the original shape. Knows nothing about per-tool selections.
+ * 2 — carries `disabledTools`.
+ *
+ * The distinction is load-bearing, not bookkeeping. In a v2 bundle an absent
+ * `disabledTools` is a real statement — "nothing is switched off on the device
+ * I pushed from" — and pulling it must be able to switch tools back ON. In a v1
+ * bundle the field is absent because the format had no way to express it, and
+ * reading that as "nothing is switched off" would silently re-enable the
+ * destructive connector tool a user had deliberately turned off. Absent and
+ * empty are the same JSON; only the version tells them apart.
+ */
+type SyncBundleVersion = 1 | 2;
 interface SyncBundle {
-    v: 1;
+    v: SyncBundleVersion;
     /** 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-tool selections for the servers above — the tools switched OFF.
+     * Present from v2 on.
+     *
+     * Travels WITH the servers, and must: syncing a connector without its
+     * selections hands the other device the connector, its credentials, and every
+     * tool switched back on — including the destructive one the user had
+     * deliberately turned off, with nothing on screen saying so.
+     */
+    disabledTools?: string[];
     /** Per-tier model overrides (non-secret). */
     models?: ModelOverrides;
     /** Budget caps (non-secret). */
@@ -3997,4 +4505,4 @@ 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_MODELS, 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 };
+export { AZURE_BASE_MODELS, 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, type CurrentPageProvider, type CurrentPageSnapshot, CurrentPageTool, 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 DiscoveredMcpTool, type DistilledFact, type Embedder, type EncryptedBlob, type EscalationDecision, 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, MAX_PAGE_TEXT_CHARS, MCP_TOOL_PREFIX, MODELS, type ManifestDiff, McpClient, type McpDiscoveryResult, McpOAuthProvider, type McpOAuthState, type McpOAuthStore, type McpServerConfig$1 as McpServerConfig, type McpServerRename, 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, disambiguateMcpServerNames, discoverMcpAuthServer, discoverMcpTools, distillSessionFacts, embedderFromProviders, encryptJSON as encryptSyncBlob, fileOAuthProvider, gatherSyncBundle, hashContent, heuristicCodeChunker, inferAzureBaseModel, isMcpToolName, mcpServerPrefix, mcpToolName, nodeHttpFetch, parseRankOrder, planRetrieval, preferIpv4Host, reciprocalRankFusion, refreshMcpToken, removeMcpServerDenials, runCascade, sessionWorthRemembering, streamCascade, uniqueMcpServerName };