cascade-ai 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,1578 @@
+import EventEmitter from 'node:events';
+import { Server } from 'node:http';
+
+type ProviderType = 'anthropic' | 'openai' | 'gemini' | 'azure' | 'openai-compatible' | 'ollama';
+interface ModelInfo {
+    id: string;
+    name: string;
+    provider: ProviderType;
+    contextWindow: number;
+    isVisionCapable: boolean;
+    inputCostPer1kTokens: number;
+    outputCostPer1kTokens: number;
+    maxOutputTokens: number;
+    supportsStreaming: boolean;
+    isLocal: boolean;
+    minSizeB?: number;
+}
+interface ProviderConfig {
+    type: ProviderType;
+    label?: string;
+    apiKey?: string;
+    baseUrl?: string;
+    deploymentName?: string;
+    apiVersion?: string;
+    model?: string;
+}
+interface StreamChunk {
+    text: string;
+    finishReason?: 'stop' | 'length' | 'tool_use' | null;
+    usage?: TokenUsage;
+}
+interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    estimatedCostUsd: number;
+}
+interface GenerateOptions {
+    messages: ConversationMessage[];
+    systemPrompt?: string;
+    maxTokens?: number;
+    temperature?: number;
+    tools?: ToolDefinition[];
+    images?: ImageAttachment[];
+    stream?: boolean;
+}
+interface GenerateResult {
+    content: string;
+    usage: TokenUsage;
+    toolCalls?: ToolCall[];
+    finishReason: 'stop' | 'length' | 'tool_use';
+}
+interface ConversationMessage {
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: string | MessageContent[];
+    toolCallId?: string;
+    toolCalls?: ToolCall[];
+    name?: string;
+}
+type MessageContent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    image: ImageAttachment;
+} | {
+    type: 'tool_result';
+    toolCallId: string;
+    content: string;
+};
+interface ImageAttachment {
+    type: 'base64' | 'url';
+    data: string;
+    mimeType: 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';
+}
+interface McpServerConfig$1 {
+    name: string;
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+interface Message {
+    id: string;
+    role: 'user' | 'assistant' | 'error' | 'system';
+    content: string;
+    timestamp: string;
+}
+interface ToolCall {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+interface ToolResult {
+    toolCallId: string;
+    output: string;
+    isError: boolean;
+}
+interface ToolExecuteOptions {
+    tierId: string;
+    sessionId: string;
+    requireApproval: boolean;
+    saveSnapshot?: (filePath: string, content: string) => Promise<void>;
+    sendPeerSync?: (to: string, syncType: PeerSyncType, content: string | Record<string, unknown>) => void;
+    getPeerMessages?: () => Array<{
+        fromId: string;
+        content: unknown;
+        timestamp: string;
+    }>;
+}
+type TierRole = 'T1' | 'T2' | 'T3';
+type TierStatus = 'IDLE' | 'ACTIVE' | 'COMPLETED' | 'FAILED' | 'ESCALATED';
+type TaskComplexity = 'Simple' | 'Moderate' | 'Complex' | 'Highly Complex';
+interface TierConfig {
+    role: TierRole;
+    id: string;
+    model: ModelInfo;
+    parentId?: string;
+}
+type MessageType = 'TASK_ASSIGNMENT' | 'STATUS_UPDATE' | 'RESULT' | 'ESCALATION' | 'PEER_SYNC';
+type MessageStatus = 'IN_PROGRESS' | 'BLOCKED' | 'ESCALATING' | 'COMPLETED' | 'PARTIAL' | 'FAILED' | 'ESCALATED';
+interface CascadeMessage {
+    version: '1.0';
+    from: string;
+    to: string;
+    type: MessageType;
+    taskId: string;
+    timestamp: string;
+    payload: MessagePayload;
+}
+type MessagePayload = T1ToT2Assignment | T2ToT3Assignment | StatusUpdate | T2Result | T3Result | EscalationPayload | PeerSyncPayload;
+interface T1ToT2Assignment {
+    sectionId: string;
+    sectionTitle: string;
+    description: string;
+    expectedOutput: string;
+    constraints: string[];
+    t3Subtasks: T3SubtaskSpec[];
+    executionMode?: 'parallel' | 'sequential';
+    peerT2Ids?: string[];
+}
+interface T3SubtaskSpec {
+    subtaskId: string;
+    subtaskTitle: string;
+    description: string;
+    expectedOutput: string;
+    constraints: string[];
+    peerT3Ids: string[];
+    dependsOn?: string[];
+    executionMode?: 'parallel' | 'sequential';
+}
+interface T2ToT3Assignment {
+    subtaskId: string;
+    subtaskTitle: string;
+    description: string;
+    expectedOutput: string;
+    constraints: string[];
+    peerT3Ids: string[];
+    parentT2: string;
+    dependsOn?: string[];
+    executionMode?: 'parallel' | 'sequential';
+}
+interface StatusUpdate {
+    progressPct: number;
+    currentAction: string;
+    status: 'IN_PROGRESS' | 'BLOCKED' | 'ESCALATING';
+}
+interface T2Result {
+    sectionId: string;
+    sectionTitle: string;
+    status: 'COMPLETED' | 'PARTIAL' | 'FAILED' | 'ESCALATED';
+    t3Results: T3Result[];
+    sectionSummary: string;
+    issues: string[];
+}
+interface T3ResultPayload {
+    subtaskId: string;
+    status: 'COMPLETED' | 'FAILED' | 'ESCALATED';
+    output: string | Record<string, unknown>;
+    testResults: {
+        checksRun: string[];
+        passed: string[];
+        failed: string[];
+    };
+    issues: string[];
+    peerSyncsUsed: string[];
+    correctionAttempts: number;
+}
+interface T3Result extends T3ResultPayload {
+}
+interface EscalationPayload {
+    raisedBy: string;
+    sectionId?: string;
+    subtaskId?: string;
+    attempted: string[];
+    blocker: string;
+    needs: string;
+}
+interface PeerSyncPayload {
+    senderT3Id: string;
+    recipientT3Id: string;
+    syncType: PeerSyncType;
+    content: string | Record<string, unknown>;
+    subtaskId?: string;
+}
+type PeerSyncType = 'SHARE_OUTPUT' | 'RESOLVE_CONFLICT' | 'DIVIDE_WORK' | 'CHECK_ASSUMPTION' | 'SIGNAL_READY';
+interface PeerMessage {
+    fromId: string;
+    toId: string;
+    type: 'SYNC_DATA' | 'BARRIER';
+    subtaskId: string;
+    syncType?: PeerSyncType;
+    payload: unknown;
+    timestamp: string;
+}
+interface Session {
+    id: string;
+    title: string;
+    createdAt: string;
+    updatedAt: string;
+    identityId: string;
+    workspacePath: string;
+    messages: StoredMessage[];
+    metadata: SessionMetadata;
+}
+interface StoredMessage {
+    id: string;
+    sessionId: string;
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    timestamp: string;
+    tokens?: TokenUsage;
+    agentMessages?: CascadeMessage[];
+}
+interface SessionMetadata {
+    totalTokens: number;
+    totalCostUsd: number;
+    modelsUsed: string[];
+    toolsUsed: string[];
+    taskCount: number;
+    branch?: string;
+    checkpoint?: SessionCheckpoint;
+}
+interface RuntimeSession {
+    sessionId: string;
+    title: string;
+    workspacePath: string;
+    status: 'ACTIVE' | 'COMPLETED' | 'FAILED';
+    startedAt: string;
+    updatedAt: string;
+    latestPrompt?: string;
+    isGlobal?: boolean;
+}
+interface RuntimeNode {
+    tierId: string;
+    sessionId: string;
+    parentId?: string;
+    role: TierRole;
+    label: string;
+    status: TierStatus;
+    currentAction?: string;
+    progressPct?: number;
+    updatedAt: string;
+    workspacePath?: string;
+    isGlobal?: boolean;
+}
+interface RuntimeNodeLog {
+    id: string;
+    sessionId: string;
+    tierId: string;
+    role: TierRole;
+    label: string;
+    status: TierStatus;
+    currentAction?: string;
+    progressPct?: number;
+    timestamp: string;
+    workspacePath?: string;
+    isGlobal?: boolean;
+}
+type RuntimeScope = 'workspace' | 'global';
+interface RuntimeSnapshotPayload {
+    scope?: RuntimeScope;
+    source?: string;
+    fetchedAt?: string;
+    sessions: RuntimeSession[];
+    nodes: RuntimeNode[];
+    logs: RuntimeNodeLog[];
+}
+interface RuntimeRefreshPayload {
+    scope: RuntimeScope;
+}
+interface SessionSubscriptionPayload {
+    sessionId: string;
+}
+interface PermissionDecisionPayload extends PermissionDecision {
+}
+interface SessionCheckpoint {
+    taskId: string;
+    timestamp: string;
+    state: Record<string, unknown>;
+}
+interface Identity {
+    id: string;
+    name: string;
+    description?: string;
+    avatar?: string;
+    createdAt: string;
+    defaultModel?: string;
+    systemPrompt?: string;
+    isDefault: boolean;
+}
+interface CascadeConfig {
+    version: '1.0';
+    defaultIdentityId?: string;
+    providers: ProviderConfig[];
+    models: ModelOverrides;
+    tools: ToolsConfig;
+    hooks: HooksConfig;
+    dashboard: DashboardConfig;
+    telemetry: TelemetryConfig;
+    memory: MemoryConfig;
+    tierLimits: TierLimits;
+    budget: BudgetConfig;
+    theme: string;
+    workspace: WorkspaceConfig;
+}
+interface ModelOverrides {
+    t1?: string;
+    t2?: string;
+    t3?: string;
+    vision?: string;
+}
+interface ToolsConfig {
+    shellAllowlist: string[];
+    shellBlocklist: string[];
+    requireApprovalFor: string[];
+    browserEnabled: boolean;
+    mcpServers?: McpServerConfig$1[];
+    /**
+     * Names of MCP servers (matching McpServerConfig.name) that the user has
+     * explicitly trusted. Servers not in this list require interactive
+     * approval before they are spawned.
+     */
+    mcpTrusted?: string[];
+}
+interface HooksConfig {
+    preToolUse?: HookDefinition[];
+    postToolUse?: HookDefinition[];
+    preTask?: HookDefinition[];
+    postTask?: HookDefinition[];
+}
+interface HookDefinition {
+    command: string;
+    tools?: string[];
+    timeout?: number;
+}
+interface DashboardConfig {
+    port: number;
+    auth: boolean;
+    teamMode: 'single' | 'multi';
+    secret?: string;
+}
+interface TelemetryConfig {
+    enabled: boolean;
+    posthogApiKey?: string;
+    distinctId?: string;
+}
+interface MemoryConfig {
+    maxSessionMessages: number;
+    autoSummarizeAt: number;
+    retentionDays: number;
+}
+interface TierLimits {
+    t1MaxTokens?: number;
+    t2MaxTokens?: number;
+    t3MaxTokens?: number;
+}
+interface BudgetConfig {
+    dailyBudgetUsd?: number;
+    sessionBudgetUsd?: number;
+    warnAtPct: number;
+}
+interface WorkspaceConfig {
+    cascadeMdPath: string;
+    configPath: string;
+    keystorePath: string;
+    auditLogPath: string;
+}
+type ThemeName = 'cascade' | 'dark' | 'light' | 'dracula' | 'nord' | 'solarized';
+interface Theme {
+    name: ThemeName;
+    colors: ThemeColors;
+}
+interface ThemeColors {
+    primary: string;
+    secondary: string;
+    accent: string;
+    success: string;
+    warning: string;
+    error: string;
+    info: string;
+    muted: string;
+    background: string;
+    foreground: string;
+    border: string;
+    t1Color: string;
+    t2Color: string;
+    t3Color: string;
+}
+type CascadeEventType = 'task:start' | 'task:complete' | 'task:error' | 'tier:status' | 'tier:result' | 'stream:token' | 'stream:done' | 'tool:approval-request' | 'tool:approval-response' | 'tool:execute' | 'tool:result' | 'cost:update' | 'session:save' | 'escalation' | 'peer:sync';
+interface CascadeEvent<T = unknown> {
+    type: CascadeEventType;
+    taskId?: string;
+    tierId?: string;
+    data: T;
+    timestamp: string;
+}
+interface ApprovalRequest {
+    id: string;
+    tierId: string;
+    toolName: string;
+    input: Record<string, unknown>;
+    description: string;
+    isDangerous: boolean;
+}
+interface ApprovalResponse {
+    id: string;
+    approved: boolean;
+    always?: boolean;
+}
+/**
+ * A permission request raised by a T3 worker that must be evaluated
+ * by T2, then T1, and finally the user if neither tier can decide.
+ */
+interface PermissionRequest {
+    /** Unique request ID */
+    id: string;
+    /** T3 worker that requires the permission */
+    requestedBy: string;
+    /** T2 manager that owns this T3 worker */
+    parentT2Id: string;
+    /** Tool being requested */
+    toolName: string;
+    /** Tool input arguments */
+    input: Record<string, unknown>;
+    /** Whether the tool is flagged as dangerous */
+    isDangerous: boolean;
+    /** What the T3 subtask is trying to accomplish */
+    subtaskContext: string;
+    /** What the parent T2 section's goal is */
+    sectionContext: string;
+    /** What T1's overall task goal is (injected when escalated to T1) */
+    taskContext?: string;
+}
+/**
+ * A decision made at any tier (T2, T1, or USER) about a PermissionRequest.
+ */
+interface PermissionDecision {
+    /** ID of the PermissionRequest this responds to */
+    requestId: string;
+    /** Whether the tool call is approved */
+    approved: boolean;
+    /**
+     * If true, cache this decision for the session so the same tool
+     * is not asked about again (section-wide scope for T2, task-wide for T1).
+     */
+    always?: boolean;
+    /** Which tier made the decision */
+    decidedBy: 'T2' | 'T1' | 'USER';
+    /** Optional explanation from the evaluating tier */
+    reasoning?: string;
+}
+interface AuditEntry {
+    id: string;
+    sessionId: string;
+    timestamp: string;
+    tierId: string;
+    action: 'tool_call' | 'file_change' | 'agent_decision' | 'approval' | 'escalation' | 'error';
+    details: Record<string, unknown>;
+}
+interface ScheduledTask {
+    id: string;
+    name: string;
+    cronExpression: string;
+    prompt: string;
+    identityId?: string;
+    workspacePath?: string;
+    createdAt: string;
+    lastRun?: string;
+    nextRun?: string;
+    enabled: boolean;
+}
+interface WebhookConfig {
+    url: string;
+    events: CascadeEventType[];
+    secret?: string;
+    headers?: Record<string, string>;
+}
+interface CascadeRunOptions {
+    prompt: string;
+    images?: ImageAttachment[];
+    workspacePath?: string;
+    identityId?: string;
+    sessionId?: string;
+    conversationHistory?: ConversationMessage[];
+    streamCallback?: (chunk: StreamChunk) => void;
+    approvalCallback?: (request: ApprovalRequest) => Promise<boolean | {
+        approved: boolean;
+        always: boolean;
+    }>;
+}
+interface CascadeRunResult {
+    output: string;
+    sessionId: string;
+    taskId: string;
+    usage: TokenUsage;
+    t2Results: T2Result[];
+    durationMs: number;
+    /** Per-tier cost breakdown (USD). Available when the router tracked stats. */
+    costByTier?: Record<string, number>;
+    /** Per-tier total token counts. Available when the router tracked stats. */
+    tokensByTier?: Record<string, number>;
+    /** Per-tier cost as a percentage of total spend (0–100). */
+    costPercentByTier?: Record<string, number>;
+}
+
+declare class ModelSelector {
+    private availableProviders;
+    private availableModels;
+    constructor(availableProviders: Set<ProviderType>);
+    addDynamicModel(model: ModelInfo): void;
+    getAvailableModelsForProvider(provider: ProviderType): ModelInfo[];
+    selectForTier(tier: TierRole, overrideModelId?: string, requireVision?: boolean): ModelInfo | null;
+    selectVisionModel(): ModelInfo | null;
+    getNextFallback(currentModelId: string, tier: TierRole): ModelInfo | null;
+    private getPriorityList;
+    isProviderAvailable(provider: ProviderType): boolean;
+    markProviderUnavailable(provider: ProviderType): void;
+    private resolveDynamicModel;
+}
+
+interface RouterStats {
+    totalTokens: number;
+    totalCostUsd: number;
+    callsByProvider: Record<string, number>;
+    callsByTier: Record<string, number>;
+    /** Accumulated cost (USD) broken down per tier — useful for budget attribution. */
+    costByTier: Record<string, number>;
+    /** Accumulated token usage broken down per tier (input + output). */
+    tokensByTier: Record<string, number>;
+    /** Input and output token counts per tier for granular cost analysis. */
+    inputTokensByTier: Record<string, number>;
+    outputTokensByTier: Record<string, number>;
+}
+declare class CascadeRouter extends EventEmitter {
+    private selector;
+    private failover;
+    private providers;
+    private stats;
+    private tierModels;
+    private config;
+    private sessionCostUsd;
+    /**
+     * Budget state machine — guards against two concurrent `generate()` calls
+     * each firing the warning or both slipping past the hard cap. All
+     * transitions happen inside `updateBudgetState()` which is called only
+     * from `recordStats`, single-threaded per V8 event loop turn.
+     */
+    private budgetState;
+    private budgetExceededReason;
+    private tpmLimiter;
+    /** Thrown when the configured budget is exceeded. */
+    static BudgetExceededError: {
+        new (msg: string): {
+            name: string;
+            message: string;
+            stack?: string;
+            cause?: unknown;
+        };
+        captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+        prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+        stackTraceLimit: number;
+    };
+    constructor();
+    init(config: CascadeConfig): Promise<void>;
+    generate(tier: TierRole, options: GenerateOptions, onChunk?: (chunk: StreamChunk) => void, requireVision?: boolean): Promise<GenerateResult>;
+    getModelForTier(tier: TierRole): ModelInfo | undefined;
+    /**
+     * Cascade Auto: temporarily override the model for a tier.
+     * Used by TaskAnalyzer to inject task-optimal models before execution.
+     * The override is valid for the current task only — restored by restoreTierModels().
+     */
+    overrideTierModel(tier: TierRole, model: ModelInfo): void;
+    getSelector(): ModelSelector;
+    getStats(): RouterStats;
+    /**
+     * Returns a human-readable cost summary broken down by tier.
+     * Example: { T1: "$0.0120 (2 calls, 1500 tokens)", T2: "$0.0043 (6 calls, 4200 tokens)", ... }
+     */
+    getTierCostSummary(): Record<string, string>;
+    /**
+     * Returns the percentage of total cost attributed to each tier.
+     * Useful for identifying which tier is the dominant cost driver.
+     */
+    getTierCostPercentages(): Record<string, number>;
+    /**
+     * Resets all stats — useful between independent task runs in long-lived sessions.
+     */
+    resetStats(): void;
+    getFailures(): Record<string, string>;
+    /**
+     * Returns the current session budget cap (USD), or undefined if no cap is set.
+     */
+    getSessionBudget(): number | undefined;
+    /**
+     * Sets (or clears) a runtime session budget cap (USD).
+     * Pass null to remove the cap.
+     */
+    setSessionBudget(usd: number | null): void;
+    /**
+     * Returns how much of the session budget has been used (USD).
+     */
+    getSessionSpend(): number;
+    /**
+     * Returns the resolved ModelInfo for a given tier, or null if no model
+     * is available (e.g. the required provider is not configured).
+     */
+    getTierModel(tier: TierRole): ModelInfo | null;
+    /**
+     * Returns all models available for the given provider type.
+     * Useful for listing configured/usable models per provider.
+     */
+    getModelsForProvider(provider: ProviderType): ModelInfo[];
+    private detectAvailableProviders;
+    private discoverOllamaModels;
+    private ensureProvider;
+    private getProvider;
+    private createProvider;
+    private getAnyModelForProvider;
+    private recordStats;
+    /**
+     * Single point of truth for budget state transitions. Called after each
+     * recordStats() so warning and hard-stop transitions are evaluated
+     * exactly once — previous logic allowed concurrent generate() calls to
+     * both fire the warning or both miss the hard stop.
+     */
+    private updateBudgetState;
+    /**
+     * Flip the router to "exceeded" state. Subsequent `generate()` calls will
+     * throw BudgetExceededError immediately, and a `budget:exceeded` event is
+     * broadcast once so listeners (REPL, dashboard, SDK) can cancel any
+     * pending approvals and unwind the run.
+     */
+    halt(reason: string): void;
+    /** Returns current budget state — useful for tests and dashboard. */
+    getBudgetState(): 'ok' | 'warned' | 'exceeded';
+    private isRateLimitError;
+}
+
+declare abstract class BaseTool {
+    abstract readonly name: string;
+    abstract readonly description: string;
+    abstract readonly inputSchema: Record<string, unknown>;
+    protected workspaceRoot: string;
+    setWorkspaceRoot(root: string): void;
+    abstract execute(input: Record<string, unknown>, options: ToolExecuteOptions): Promise<string>;
+    isDangerous(): boolean;
+    getDefinition(): ToolDefinition;
+}
+
+interface McpServerConfig {
+    name: string;
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+/**
+ * Gate called before each MCP server is spawned. Lets the caller (REPL or
+ * SDK) prompt the user for explicit approval of a subprocess binary.
+ * Return `true` to allow, `false` to reject.
+ */
+type McpApprovalCallback = (server: McpServerConfig) => Promise<boolean> | boolean;
+interface McpClientOptions {
+    /** Names of servers the user has already trusted (config.mcp.trusted). */
+    trustedServers?: string[];
+    /** Approval gate invoked when a server is NOT in the trusted list. */
+    approvalCallback?: McpApprovalCallback;
+}
+declare class McpClient {
+    private clients;
+    private tools;
+    private trustedServers;
+    private approvalCallback;
+    constructor(options?: McpClientOptions);
+    connect(server: McpServerConfig): Promise<void>;
+    disconnect(serverName: string): Promise<void>;
+    disconnectAll(): Promise<void>;
+    callTool(serverName: string, toolName: string, input: Record<string, unknown>): Promise<string>;
+    getToolDefinitions(): ToolDefinition[];
+    getConnectedServers(): string[];
+    isConnected(serverName: string): boolean;
+}
+
+/**
+ * A ToolPlugin bundles one or more custom tools that extend Cascade's capabilities.
+ * Plugins are loaded via `registerPlugin()` and behave like built-in tools.
+ *
+ * @example
+ * const myPlugin: ToolPlugin = {
+ *   name: 'my-custom-tools',
+ *   version: '1.0.0',
+ *   tools: [new MyCustomTool()],
+ *   onRegister: (registry) => console.log('Plugin registered'),
+ * };
+ * registry.registerPlugin(myPlugin);
+ */
+interface ToolPlugin {
+    /** Unique plugin identifier */
+    name: string;
+    /** Semantic version string */
+    version: string;
+    /** One or more tools this plugin provides */
+    tools: BaseTool[];
+    /** Called once when the plugin is registered */
+    onRegister?: (registry: ToolRegistry) => void;
+}
+declare class ToolRegistry {
+    private tools;
+    private config;
+    private ignoreMatcher;
+    private workspaceRoot;
+    /** Loaded plugins, keyed by plugin name */
+    private plugins;
+    constructor(config: ToolsConfig, workspaceRoot?: string);
+    register(tool: BaseTool): void;
+    /**
+     * Register a ToolPlugin, loading all its tools into the registry.
+     * Each tool is configured with the current workspace root.
+     * Duplicate plugin names are silently ignored.
+     *
+     * @example
+     * registry.registerPlugin(myPlugin);
+     */
+    registerPlugin(plugin: ToolPlugin): void;
+    /** Returns the names of all registered plugins */
+    getRegisteredPlugins(): string[];
+    /** Registers all tools from an MCP client */
+    registerMcpTools(mcpClient: McpClient): void;
+    setIgnoredPaths(patterns: string[]): void;
+    getToolDefinitions(): ToolDefinition[];
+    getTool(name: string): BaseTool | undefined;
+    hasTool(name: string): boolean;
+    requiresApproval(toolName: string): boolean;
+    isDangerous(toolName: string): boolean;
+    execute(toolName: string, input: Record<string, unknown>, options: ToolExecuteOptions): Promise<string>;
+    private registerDefaults;
+    private isFileOperation;
+    private isIgnored;
+}
+
+declare class MemoryStore {
+    private db;
+    constructor(dbPath: string);
+    createSession(session: Session): void;
+    updateSession(id: string, updates: Partial<Session>): void;
+    getSession(id: string): Session | null;
+    listSessions(identityId?: string, limit?: number): Session[];
+    deleteSession(id: string): void;
+    deleteAllSessions(): void;
+    deleteRuntimeSession(sessionId: string): void;
+    deleteAllRuntimeNodes(): void;
+    branchSession(originalId: string, newId: string): void;
+    upsertRuntimeSession(session: RuntimeSession): void;
+    listRuntimeSessions(limit?: number): RuntimeSession[];
+    upsertRuntimeNode(node: RuntimeNode): void;
+    listRuntimeNodes(sessionId?: string, limit?: number): RuntimeNode[];
+    addRuntimeNodeLog(log: RuntimeNodeLog): void;
+    listRuntimeNodeLogs(sessionId?: string, tierId?: string, limit?: number): RuntimeNodeLog[];
+    addMessage(message: StoredMessage): void;
+    getSessionMessages(sessionId: string): StoredMessage[];
+    searchMessages(query: string, limit?: number): StoredMessage[];
+    createIdentity(identity: Identity): void;
+    updateIdentity(id: string, updates: Partial<Identity>): void;
+    getIdentity(id: string): Identity | null;
+    getDefaultIdentity(): Identity | null;
+    listIdentities(): Identity[];
+    deleteIdentity(id: string): void;
+    saveScheduledTask(task: ScheduledTask): void;
+    listScheduledTasks(): ScheduledTask[];
+    deleteScheduledTask(id: string): void;
+    addAuditEntry(entry: AuditEntry): void;
+    getAuditLog(sessionId: string, limit?: number): AuditEntry[];
+    addFileSnapshot(sessionId: string, filePath: string, content: string): void;
+    getLatestFileSnapshots(sessionId: string): Array<{
+        filePath: string;
+        content: string;
+    }>;
+    upsertCachedModel(model: ModelInfo): void;
+    getCachedModels(provider?: ProviderType): ModelInfo[];
+    clearModelCache(provider?: ProviderType): void;
+    getCacheAge(): number;
+    private toolResultCache;
+    private static CACHEABLE_TOOLS;
+    private static TOOL_TTL_MS;
+    /**
+     * Returns a cached tool result, or null if not cached / expired.
+     */
+    getToolResult(toolName: string, input: Record<string, unknown>): string | null;
+    /**
+     * Stores a tool result in the in-memory cache.
+     * Only caches read-only/safe tools (see CACHEABLE_TOOLS).
+     */
+    setToolResult(toolName: string, input: Record<string, unknown>, result: string): void;
+    /** Invalidate tool cache for a specific tool name, or all tools if omitted. */
+    invalidateToolCache(toolName?: string): void;
+    close(): void;
+    private migrate;
+    private deserializeSession;
+    private deserializeMessage;
+    private deserializeIdentity;
+    private deserializeScheduledTask;
+}
+
+declare class Cascade extends EventEmitter {
+    private router;
+    private toolRegistry;
+    private mcpClient;
+    private config;
+    private initialized;
+    private initPromise?;
+    private store?;
+    private audit?;
+    private telemetry;
+    private taskAnalyzer?;
+    private toolCreator?;
+    constructor(config: CascadeConfig, workspacePath: string, store?: MemoryStore);
+    private initOptionalFeatures;
+    setStore(store: MemoryStore): void;
+    /**
+     * Emit an `mcp:approval-required` event and wait up to 30 s for a listener
+     * to resolve it via `cascade.resolveMcpApproval(serverName, approved)`.
+     *
+     * If no listener is attached (e.g. a non-interactive SDK run), the default
+     * is to reject — safer than silently spawning an arbitrary subprocess.
+     */
+    private pendingMcpApprovals;
+    private requestMcpApproval;
+    /** Resolve a pending MCP server approval from a REPL / dashboard listener. */
+    resolveMcpApproval(serverName: string, approved: boolean): void;
+    init(): Promise<void>;
+    private looksLikeSimpleArtifactTask;
+    private determineComplexity;
+    run(options: CascadeRunOptions): Promise<CascadeRunResult>;
+    getRouter(): CascadeRouter;
+    getToolRegistry(): ToolRegistry;
+    /**
+     * Tear down MCP connections and flush any pending telemetry so long-lived
+     * hosts (REPL, SDK embedders) don't leak child processes. Safe to call
+     * multiple times.
+     */
+    close(): Promise<void>;
+}
+
+declare abstract class BaseTier extends EventEmitter {
+    readonly id: string;
+    readonly role: TierRole;
+    protected status: TierStatus;
+    protected parentId?: string;
+    protected taskId: string;
+    protected label: string;
+    protected systemPromptOverride: string;
+    protected hierarchyContext: string;
+    constructor(role: TierRole, id?: string, parentId?: string);
+    getStatus(): TierStatus;
+    protected setStatus(status: TierStatus): void;
+    protected setLabel(label: string): void;
+    setSystemPromptOverride(prompt: string): void;
+    setHierarchyContext(context: string): void;
+    protected sendStatusUpdate(update: StatusUpdate): void;
+    protected buildMessage(type: CascadeMessage['type'], to: string, payload: Record<string, unknown>): CascadeMessage;
+    protected log(message: string, data?: unknown): void;
+}
+
+type T2Evaluator = (req: PermissionRequest) => Promise<PermissionDecision | null>;
+type T1Evaluator = (req: PermissionRequest) => Promise<PermissionDecision | null>;
+/**
+ * PermissionEscalator manages the hierarchical permission flow for a single task run.
+ *
+ * Decision cascade:
+ * 1. Check session cache (section-wide key `${t2Id}:${toolName}`) → return if hit
+ * 2. Ask T2 evaluator → if decision returned, cache + return
+ * 3. Ask T1 evaluator → if decision returned, cache + return
+ * 4. Emit `permission:user-required` → wait for external decision via `resolveUserDecision()`
+ */
+declare class PermissionEscalator extends EventEmitter {
+    /**
+     * Session cache keyed by `${t2Id}:${toolName}`.
+     * All T3 workers under the same T2 share cached decisions for the same tool.
+     */
+    private sessionCache;
+    private t2Evaluator?;
+    private t1Evaluator?;
+    /** Pending user-decision resolvers keyed by request ID */
+    private pendingUserDecisions;
+    setT2Evaluator(evaluator: T2Evaluator): void;
+    setT1Evaluator(evaluator: T1Evaluator): void;
+    /**
+     * Main entry point. Called by T3Worker instead of emitting `tool:approval-request`.
+     * Returns a PermissionDecision from whichever tier was able to decide.
+     */
+    requestPermission(req: PermissionRequest): Promise<PermissionDecision>;
+    /**
+     * Called by the REPL/SDK once the user has made a decision.
+     * Only has effect when a request is actually pending.
+     */
+    resolveUserDecision(requestId: string, approved: boolean, always?: boolean): void;
+    private waitForUserDecision;
+    /** Check if there are permissions waiting for user input */
+    hasPendingUserDecisions(): boolean;
+    /** Deny all pending user decisions (used on task cancel) */
+    cancelAllPending(): void;
+}
+
+declare class ToolCreator {
+    private router;
+    private registry;
+    private createdTools;
+    constructor(router: CascadeRouter, registry: ToolRegistry);
+    /**
+     * Generate a new tool from a description and register it with the ToolRegistry.
+     * Returns the tool name if successful, null if generation failed.
+     */
+    createTool(description: string, context: string): Promise<string | null>;
+    /**
+     * Returns the names of all tools created in this session.
+     */
+    getCreatedTools(): string[];
+}
+
+declare class T1Administrator extends BaseTier {
+    private router;
+    private toolRegistry;
+    private config;
+    private t2Managers;
+    private escalations;
+    private store?;
+    private t2PeerBus;
+    private permissionEscalator?;
+    private toolCreator?;
+    /** Stored overall task goal — used when evaluating escalated permissions */
+    private taskGoal;
+    constructor(router: CascadeRouter, toolRegistry: ToolRegistry, config: CascadeConfig);
+    setStore(store: MemoryStore): void;
+    /**
+     * Inject the shared PermissionEscalator for this task run.
+     * Registers T1's evaluator so it can decide when T2 is uncertain.
+     */
+    setPermissionEscalator(escalator: PermissionEscalator): void;
+    setToolCreator(creator: ToolCreator): void;
+    execute(userPrompt: string, images?: ImageAttachment[], systemContext?: string): Promise<{
+        output: string;
+        t2Results: T2Result[];
+        taskId: string;
+        complexity: TaskComplexity;
+    }>;
+    getEscalations(): EscalationPayload[];
+    private analyzeImages;
+    private decomposeTask;
+    private validatePlan;
+    private dispatchT2Managers;
+    private compileFinalOutput;
+    /**
+     * T1-level permission evaluator.
+     * Uses T1's model with full task context.
+     * Returns null only when the model explicitly says UNSURE (triggers user prompt).
+     */
+    private evaluatePermissionAtT1;
+}
+
+interface PeerOutput {
+    subtaskId: string;
+    fromId: string;
+    output: string;
+    status: 'COMPLETED' | 'FAILED' | 'ESCALATED';
+    timestamp: string;
+}
+/**
+ * PeerBus enables T3↔T3 and T2↔T2 communication within a task.
+ * Each T2Manager creates one PeerBus and shares it with its T3Workers.
+ * T1 creates one PeerBus and shares it with its T2Managers.
+ */
+interface BroadcastMessage {
+    fromId: string;
+    payload: unknown;
+    timestamp: string;
+}
+declare class PeerBus extends EventEmitter {
+    private outputs;
+    private waiters;
+    private members;
+    private barriers;
+    private broadcastLog;
+    private fileLocks;
+    register(peerId: string): void;
+    /**
+     * Publish output — unblocks any peers waiting on this subtaskId
+     */
+    publish(fromId: string, subtaskId: string, output: string, status: PeerOutput['status']): void;
+    /**
+     * Wait for a specific subtask's output — resolves immediately if already available
+     */
+    waitFor(subtaskId: string, timeoutMs?: number): Promise<PeerOutput>;
+    /**
+     * Get output if already available (non-blocking)
+     */
+    getOutput(subtaskId: string): PeerOutput | undefined;
+    /**
+     * Broadcast a message to all registered peers except sender.
+     * Also logs to broadcastLog so collect() can retrieve recent broadcasts.
+     */
+    broadcast(fromId: string, payload: unknown): void;
+    /**
+     * Collect all broadcast messages received within a time window.
+     * Useful for T2 announcement gathering — call immediately after triggering broadcasts.
+     */
+    collect(timeoutMs: number): Promise<BroadcastMessage[]>;
+    /**
+     * Acquire an exclusive file lock — prevents concurrent T3 writes to the same file.
+     * If the file is already locked, waits until the lock is released.
+     */
+    lockFile(tierId: string, filePath: string, timeoutMs?: number): Promise<void>;
+    /**
+     * Release a file lock — unblocks the next waiter if any.
+     */
+    releaseFile(tierId: string, filePath: string): void;
+    /**
+     * Wait until a file lock is released (non-acquiring — just observes).
+     * Used by T3s that want to read after another T3 finishes writing.
+     */
+    waitForFileRelease(filePath: string, timeoutMs?: number): Promise<void>;
+    /**
+     * Check if a file is currently locked (non-blocking).
+     */
+    isFileLocked(filePath: string): boolean;
+    /**
+     * Clear broadcast log — call between phases to avoid stale announcements.
+     */
+    clearBroadcastLog(): void;
+    /**
+     * Send a targeted message to a specific peer
+     */
+    send(fromId: string, toId: string, syncType: PeerSyncType, subtaskId: string, payload: unknown): void;
+    /**
+     * Barrier — wait until N peers have all reached this point
+     * Useful for fan-in synchronization
+     */
+    barrier(peerId: string, barrierName: string, totalPeers: number): Promise<void>;
+    getAllOutputs(): PeerOutput[];
+    getMembers(): string[];
+}
+
+declare class T2Manager extends BaseTier {
+    private router;
+    private toolRegistry;
+    private assignment?;
+    private t3Workers;
+    private escalations;
+    private peerSyncBuffer;
+    private store?;
+    private t3PeerBus;
+    private t2PeerBus?;
+    private permissionEscalator?;
+    private toolCreator?;
+    setPeerBus(bus: PeerBus): void;
+    constructor(router: CascadeRouter, toolRegistry: ToolRegistry, parentId: string);
+    setStore(store: MemoryStore): void;
+    /**
+     * Inject the shared PermissionEscalator for this task run.
+     * The escalator will also be given this T2's evaluator function.
+     */
+    setPermissionEscalator(escalator: PermissionEscalator): void;
+    setToolCreator(creator: ToolCreator): void;
+    /**
+     * Phase 1 of T2 peer discussion: broadcast this section's plan so sibling T2s
+     * and T1 can detect overlaps and coordinate execution order.
+     * Called BEFORE execute() begins the agent loop.
+     */
+    announcePlan(assignment: T1ToT2Assignment): void;
+    /**
+     * Phase 2: After this section completes, share the output with sibling T2s
+     * so they can reference it in their final compilation if relevant.
+     */
+    shareCompletedOutput(sectionId: string, output: string): void;
+    private extractKeywords;
+    receivePeerSync(fromId: string, content: unknown): void;
+    execute(assignment: T1ToT2Assignment, taskId: string): Promise<T2Result>;
+    private decomposeSection;
+    private executeSubtasks;
+    /**
+     * Runs T3 workers respecting dependsOn declarations.
+     *
+     * Uses Kahn's algorithm for topological ordering:
+     *  1. Build an in-degree map from the dependency graph.
+     *  2. Detect cycles — if any exist, break them by removing the offending edge
+     *     and logging a warning (so the run degrades gracefully instead of deadlocking).
+     *  3. Execute workers in waves: start all zero-in-degree tasks in parallel,
+     *     then reduce in-degrees of their dependents and repeat.
+     */
+    private runWithDependencies;
+    /**
+     * Detects cyclic dependencies using Kahn's algorithm and breaks them
+     * by removing back-edges. Returns a sanitized copy of assignments.
+     *
+     * A cycle like t1→t2→t3→t1 is broken at the last edge (t3→t1),
+     * meaning t3 will start without waiting for t1, preventing deadlock.
+     */
+    private breakCycles;
+    private retryT3;
+    private publishSectionOutput;
+    private aggregateResults;
+    private determineStatus;
+    /**
+     * T2-level permission evaluator.
+     * - Safe / non-dangerous tools: auto-approve via rules (no LLM call).
+     * - Dangerous tools: ask T2's LLM whether the action fits the section goal.
+     * - Returns null if the LLM is uncertain (triggers T1 evaluation).
+     */
+    private evaluatePermissionAtT2;
+}
+
+declare class T3Worker extends BaseTier {
+    private router;
+    private toolRegistry;
+    private context;
+    private assignment?;
+    private peerSyncBuffer;
+    private store?;
+    private audit?;
+    private tools;
+    /** @deprecated — kept only as fallback when no escalator is attached */
+    private sessionApprovals;
+    private peerBus?;
+    private permissionEscalator?;
+    private toolCreator?;
+    setPeerBus(bus: PeerBus): void;
+    setPermissionEscalator(escalator: PermissionEscalator): void;
+    setToolCreator(creator: ToolCreator): void;
+    constructor(router: CascadeRouter, toolRegistry: ToolRegistry, parentId: string);
+    setStore(store: MemoryStore, sessionId: string): void;
+    execute(assignment: T2ToT3Assignment, taskId: string): Promise<T3Result>;
+    sendToPeer(toId: string, content: unknown): void;
+    requestFromPeer(peerId: string, subtaskId: string): Promise<string>;
+    syncWithPeers(barrierName: string): Promise<void>;
+    receivePeerSync(fromId: string, content: unknown): void;
+    private runAgentLoop;
+    private executeTool;
+    /**
+     * Announce which files this T3 plans to edit, then acquire locks on them
+     * before competing siblings can claim them. T3s working on different files
+     * proceed in full parallel; T3s on the same file serialize automatically.
+     */
+    private coordinateFileIntents;
+    private requiresArtifact;
+    private extractArtifactPaths;
+    private verifyArtifacts;
+    private selfTest;
+    private correctOutput;
+    private buildSystemPrompt;
+    private buildInitialPrompt;
+    private buildResult;
+    private isFileOperation;
+}
+
+/**
+ * High-level SDK entry point — loads config from the workspace and runs a task.
+ *
+ * Cascade automatically determines complexity and routes to the appropriate
+ * tier: T3 (simple), T2 (moderate), or the full T1→T2→T3 hierarchy (complex).
+ *
+ * @param prompt - The natural-language task description to execute.
+ * @param options - Optional overrides for run behavior, approval callbacks, etc.
+ * @returns A resolved `CascadeRunResult` with the final output and metadata.
+ *
+ * @example
+ * const result = await runCascade('Refactor the auth module to use JWT', {
+ *   workspacePath: '/path/to/my/project',
+ *   streamCallback: (chunk) => process.stdout.write(chunk.text ?? ''),
+ *   approvalCallback: async (req) => {
+ *     console.log(`Approve ${req.toolName}?`);
+ *     return { approved: true, always: false };
+ *   },
+ * });
+ * console.log(result.output);
+ */
+declare function runCascade(prompt: string, options?: Partial<CascadeRunOptions> & {
+    workspacePath?: string;
+    config?: Partial<CascadeConfig>;
+}): Promise<CascadeRunResult>;
+/**
+ * Create a `Cascade` instance with custom config — no filesystem config loading.
+ *
+ * Use this in environments where you control the config programmatically
+ * (e.g. tests, serverless, embedded usage).
+ *
+ * @param config - Partial config; missing fields use schema defaults.
+ * @param workspacePath - Workspace root (default: `process.cwd()`).
+ *
+ * @example
+ * const cascade = createCascade({
+ *   providers: [{ type: 'anthropic', apiKey: process.env.ANTHROPIC_KEY }],
+ * });
+ * cascade.on('stream:token', (e) => process.stdout.write(e.text));
+ * await cascade.init();
+ * await cascade.run({ prompt: 'Hello world', workspacePath: '.' });
+ */
+declare function createCascade(config: Partial<CascadeConfig>, workspacePath?: string): Cascade;
+/**
+ * Convenience streaming helper — runs a task and delivers tokens via callback.
+ *
+ * @param prompt - The task to execute.
+ * @param onToken - Called with each streamed text token as it arrives.
+ * @param options - Same options as `runCascade`.
+ *
+ * @example
+ * await streamCascade('Summarize this codebase', (token) => {
+ *   process.stdout.write(token);
+ * });
+ */
+declare function streamCascade(prompt: string, onToken: (text: string) => void, options?: Partial<CascadeRunOptions> & {
+    workspacePath?: string;
+}): Promise<CascadeRunResult>;
+
+/**
+ * Keystore with two backends:
+ *  1. OS keychain via `keytar` — preferred when available (macOS Keychain,
+ *     Windows Credential Vault, libsecret). No master password required.
+ *  2. AES-256-GCM encrypted file — used when keytar is unavailable or the
+ *     caller passes `{ forceFile: true }`. Requires a master password.
+ *
+ * On first successful keytar unlock we silently migrate any existing AES
+ * entries into the OS keychain. The AES file is left in place as a backup
+ * until the user explicitly deletes it via `cascade keys migrate --confirm`.
+ */
+declare class Keystore {
+    private storePath;
+    private masterKey;
+    private keytar;
+    private cache;
+    private backend;
+    constructor(storePath: string);
+    /**
+     * Unlock the keystore.
+     *
+     * If `password` is omitted we try keytar only. If keytar is unavailable and
+     * there are AES entries to read, unlock will fail — re-call with a password
+     * to decrypt the file backend.
+     */
+    unlock(password?: string, opts?: {
+        forceFile?: boolean;
+    }): Promise<void>;
+    /** Synchronous legacy unlock kept for AES-only environments. */
+    unlockSync(password: string): void;
+    lock(): void;
+    isUnlocked(): boolean;
+    /** Report the active backend (`keytar` or `file`) for diagnostics. */
+    getBackend(): 'keytar' | 'file' | null;
+    set(key: string, value: string): Promise<void>;
+    get(key: string): string | undefined;
+    delete(key: string): Promise<void>;
+    listKeys(): string[];
+    private assertUnlocked;
+    private decryptFile;
+    private saveAll;
+    private writeWithSalt;
+    private readRaw;
+    private deriveKey;
+}
+
+declare class CascadeIgnore {
+    private ig;
+    private loaded;
+    constructor();
+    load(workspacePath: string): Promise<void>;
+    isIgnored(filePath: string, workspacePath?: string): boolean;
+    getPatterns(): string[];
+}
+
+interface CascadeMdContent {
+    raw: string;
+    sections: Record<string, string>;
+    systemPrompt: string;
+}
+
+declare class ConfigManager {
+    private config;
+    private keystore;
+    private ignore;
+    private store;
+    private cascadeMd;
+    private workspacePath;
+    private globalDir;
+    constructor(workspacePath?: string);
+    load(): Promise<void>;
+    getConfig(): CascadeConfig;
+    getKeystore(): Keystore;
+    getIgnore(): CascadeIgnore;
+    getStore(): MemoryStore;
+    getCascadeMd(): CascadeMdContent | null;
+    getWorkspacePath(): string;
+    save(): Promise<void>;
+    updateConfig(updates: Partial<CascadeConfig>): Promise<void>;
+    getApiKey(provider: string): string | undefined;
+    private loadConfig;
+    private injectEnvKeys;
+    private ensureDefaultIdentity;
+}
+
+interface DashboardSocketOptions {
+    authRequired: boolean;
+    secret: string;
+    corsOrigin?: string | string[];
+}
+declare class DashboardSocket {
+    private io;
+    private authRequired;
+    private secret;
+    constructor(httpServer: Server, options: DashboardSocketOptions);
+    broadcastToRoom(room: string, event: string, data: unknown): void;
+    broadcast(event: string, data: unknown): void;
+    emitCascadeEvent(ev: CascadeEvent): void;
+    emitTierStatus(tierId: string, role: string, status: string, sessionId: string, action?: string): void;
+    emitStreamToken(tierId: string, text: string, sessionId: string): void;
+    emitApprovalRequest(request: PermissionRequest): void;
+    onApprovalResponse(callback: (data: PermissionDecisionPayload) => void): void;
+    private setupHandlers;
+    close(): void;
+}
+
+declare class DashboardServer {
+    private app;
+    private httpServer;
+    private socket;
+    private config;
+    private dashboardSecret;
+    private store;
+    private globalStore;
+    private broadcastTimer;
+    private port;
+    private workspacePath;
+    constructor(config: CascadeConfig, store: MemoryStore, workspacePath?: string);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    getSocket(): DashboardSocket;
+    /**
+     * Produce a stable dashboard JWT signing secret.
+     *
+     * Order of precedence: explicit config → env var → secret file on disk
+     * (auto-created with 0600 perms). Previously this generated a fresh UUID
+     * on every process start which invalidated all outstanding JWTs.
+     */
+    private resolveDashboardSecret;
+    /**
+     * Resolve the dashboard password as a bcrypt hash.
+     * Accepts either a pre-hashed `CASCADE_DASHBOARD_PASSWORD_HASH` or a plain
+     * `CASCADE_DASHBOARD_PASSWORD` which is hashed once at startup.
+     */
+    private resolvePasswordHash;
+    private getGlobalStore;
+    private throttledBroadcast;
+    private broadcastRuntime;
+    private broadcastSessionDetails;
+    watchRuntimeChanges(): void;
+    refreshRuntime(scope?: 'workspace' | 'global'): void;
+    private setupMiddleware;
+    private setupRoutes;
+}
+
+type TaskRunner = (task: ScheduledTask) => Promise<void>;
+declare class TaskScheduler {
+    private cronJobs;
+    private store;
+    private runner;
+    constructor(store: MemoryStore, runner: TaskRunner);
+    start(): void;
+    stop(): void;
+    schedule(task: ScheduledTask): void;
+    unschedule(taskId: string): void;
+    add(task: ScheduledTask): void;
+    remove(taskId: string): void;
+    list(): ScheduledTask[];
+    isRunning(taskId: string): boolean;
+    static validateCron(expression: string): boolean;
+}
+
+declare class HooksRunner {
+    private config;
+    constructor(config: HooksConfig);
+    runPreToolUse(toolName: string, input: Record<string, unknown>): Promise<HookResult>;
+    runPostToolUse(toolName: string, output: string): Promise<HookResult>;
+    runPreTask(prompt: string): Promise<HookResult>;
+    runPostTask(output: string, durationMs: number): Promise<HookResult>;
+    private runHooks;
+}
+interface HookResult {
+    success: boolean;
+    output: string;
+    error?: string;
+}
+
+/** Structured log levels for audit entries */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/** Extended audit entry with log level */
+interface AuditEntryWithLevel extends AuditEntry {
+    level: LogLevel;
+}
+declare class AuditLogger {
+    private store;
+    private sessionId;
+    private minLevel;
+    constructor(store: MemoryStore, sessionId: string, minLevel?: LogLevel);
+    debug(tierId: string, action: AuditEntry['action'], details: Record<string, unknown>): void;
+    info(tierId: string, action: AuditEntry['action'], details: Record<string, unknown>): void;
+    warn(tierId: string, action: AuditEntry['action'], details: Record<string, unknown>): void;
+    error(tierId: string, err: Error | unknown, context?: Record<string, unknown>): void;
+    /** Backward-compatible generic log (defaults to info level) */
+    log(tierId: string, action: AuditEntry['action'], details: Record<string, unknown>): void;
+    toolCall(tierId: string, toolName: string, input: Record<string, unknown>): void;
+    fileChange(tierId: string, filePath: string, operation: string): void;
+    agentDecision(tierId: string, decision: string, reasoning?: string): void;
+    approval(tierId: string, toolName: string, approved: boolean, decidedBy?: string): void;
+    escalation(tierId: string, blocker: string, needs: string): void;
+    getLog(limit?: number): AuditEntry[];
+    /**
+     * Formats an audit entry as a single-line JSON string (e.g. for log aggregation).
+     */
+    formatStructured(entry: AuditEntryWithLevel): string;
+    private logAt;
+    private shouldLog;
+}
+
+interface TelemetryEvents {
+    'cascade:session_start': {
+        complexity?: TaskComplexity;
+        providerCount: number;
+        cascadeAutoEnabled: boolean;
+        toolCreationEnabled: boolean;
+    };
+    'cascade:session_end': {
+        durationMs: number;
+        taskCount: number;
+        totalTokens: number;
+        totalCostUsd: number;
+    };
+    'cascade:task_complete': {
+        complexity: TaskComplexity;
+        tier: TierRole | 'simple';
+        durationMs: number;
+        tokenCount: number;
+        costUsd: number;
+        t2Count: number;
+        t3Count: number;
+    };
+    'cascade:task_failed': {
+        tier: TierRole;
+        errorType: string;
+        complexity?: TaskComplexity;
+    };
+    'cascade:tool_executed': {
+        toolName: string;
+        tier: TierRole;
+        success: boolean;
+        durationMs?: number;
+    };
+    'cascade:tool_created': {
+        name: string;
+        description: string;
+    };
+    'cascade:model_selected': {
+        tier: TierRole;
+        modelId: string;
+        provider: string;
+        reason: 'config_override' | 'cascade_auto' | 'priority_list' | 'fallback';
+        complexity?: number;
+    };
+    'cascade:peer_sync': {
+        syncType: string;
+        tier: 'T2' | 'T3';
+        participantCount: number;
+    };
+    'cascade:escalation': {
+        fromTier: TierRole;
+        toTier: TierRole | 'user';
+        toolName: string;
+        approved: boolean;
+    };
+    'cascade:provider_failover': {
+        from: string;
+        to: string;
+        reason: string;
+    };
+    'cascade:t2_overlap_detected': {
+        sectionCount: number;
+        overlapCount: number;
+        switchedToSequential: boolean;
+    };
+    'cascade:file_lock_contention': {
+        filePath: string;
+        waitMs: number;
+    };
+}
+type TelemetryEventName = keyof TelemetryEvents;
+declare class Telemetry {
+    private client;
+    private enabled;
+    private distinctId;
+    constructor(config: TelemetryConfig, distinctId: string);
+    private init;
+    /**
+     * Capture a typed telemetry event. Silently no-ops if telemetry is disabled.
+     */
+    capture<E extends TelemetryEventName>(event: E, properties: TelemetryEvents[E]): void;
+    capture(event: string, properties?: Record<string, unknown>): void;
+    shutdown(): Promise<void>;
+}
+
+declare const CASCADE_VERSION = "0.1.2";
+declare const CASCADE_CONFIG_DIR = ".cascade";
+declare const CASCADE_MD_FILE = "CASCADE.md";
+declare const CASCADE_IGNORE_FILE = ".cascadeignore";
+declare const CASCADE_CONFIG_FILE = ".cascade/config.json";
+declare const CASCADE_KEYSTORE_FILE = ".cascade/keystore.enc";
+declare const CASCADE_AUDIT_FILE = ".cascade/audit.log";
+declare const CASCADE_DB_FILE = ".cascade/memory.db";
+declare const CASCADE_DASHBOARD_SECRET_FILE = ".cascade/dashboard-secret";
+declare const GLOBAL_CONFIG_DIR = ".cascade-ai";
+declare const GLOBAL_DB_FILE = "memory.db";
+declare const GLOBAL_KEYSTORE_FILE = "keystore.enc";
+declare const GLOBAL_RUNTIME_DB_FILE = "runtime.db";
+declare const DEFAULT_DASHBOARD_PORT = 4891;
+declare const DEFAULT_API_PORT = 4892;
+declare const DEFAULT_CONTEXT_LIMIT = 200000;
+declare const DEFAULT_AUTO_SUMMARIZE_AT = 150000;
+declare const DEFAULT_MAX_SESSION_MESSAGES = 1000;
+declare const DEFAULT_RETENTION_DAYS = 90;
+declare const MODELS: Record<string, ModelInfo>;
+declare const T1_MODEL_PRIORITY: string[];
+declare const T2_MODEL_PRIORITY: string[];
+declare const T3_MODEL_PRIORITY: string[];
+declare const VISION_MODEL_PRIORITY: string[];
+declare const COMPLEXITY_T2_COUNT: Record<string, [number, number]>;
+declare const THEME_NAMES: ThemeName[];
+declare const DEFAULT_THEME: ThemeName;
+declare const OLLAMA_BASE_URL = "http://localhost:11434";
+declare const LM_STUDIO_BASE_URL = "http://localhost:1234";
+declare const AZURE_BASE_URL_TEMPLATE = "https://{resource}.openai.azure.com";
+declare const TOOL_NAMES: {
+    readonly SHELL: "shell";
+    readonly FILE_READ: "file_read";
+    readonly FILE_WRITE: "file_write";
+    readonly FILE_EDIT: "file_edit";
+    readonly FILE_DELETE: "file_delete";
+    readonly FILE_LIST: "file_list";
+    readonly GIT: "git";
+    readonly GITHUB: "github";
+    readonly BROWSER: "browser";
+    readonly IMAGE_ANALYZE: "image_analyze";
+    readonly PDF_CREATE: "pdf_create";
+    readonly RUN_CODE: "run_code";
+    readonly PEER_MESSAGE: "peer_message";
+};
+declare const DEFAULT_APPROVAL_REQUIRED: string[];
+declare const PROVIDER_DISPLAY_NAMES: Record<ProviderType, string>;
+
+export { AZURE_BASE_URL_TEMPLATE, type ApprovalRequest, type ApprovalResponse, type AuditEntry, AuditLogger, 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, type CascadeConfig, type CascadeEvent, type CascadeEventType, CascadeIgnore, type CascadeMessage, CascadeRouter, type CascadeRunOptions, type CascadeRunResult, ConfigManager, type ConversationMessage, DEFAULT_API_PORT, DEFAULT_APPROVAL_REQUIRED, DEFAULT_AUTO_SUMMARIZE_AT, DEFAULT_CONTEXT_LIMIT, DEFAULT_DASHBOARD_PORT, DEFAULT_MAX_SESSION_MESSAGES, DEFAULT_RETENTION_DAYS, DEFAULT_THEME, type DashboardConfig, DashboardServer, type EscalationPayload, GLOBAL_CONFIG_DIR, GLOBAL_DB_FILE, GLOBAL_KEYSTORE_FILE, GLOBAL_RUNTIME_DB_FILE, type GenerateOptions, type GenerateResult, type HookDefinition, type HooksConfig, HooksRunner, type Identity, type ImageAttachment, Keystore, LM_STUDIO_BASE_URL, 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 PeerSyncPayload, type PeerSyncType, type PermissionDecision, type PermissionDecisionPayload, type PermissionRequest, 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 WebhookConfig, type WorkspaceConfig, createCascade, runCascade, streamCascade };