@superatomai/sdk-node 0.0.1-s → 0.0.2-dsp

package/dist/index.d.ts

@@ -777,6 +777,14 @@ declare const ToolSchema: z.ZodObject<{
             description: string;
         }[];
     }>>;
+    /** Cache policy. `false` = never cache (live data, write ops). Mirrors HTTP `Cache-Control: no-store`. */
+    cache: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<false>, z.ZodObject<{
+        ttlMs: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        ttlMs?: number | undefined;
+    }, {
+        ttlMs?: number | undefined;
+    }>]>>;
 }, "strip", z.ZodTypeAny, {
     id: string;
     params: Record<string, string>;
@@ -793,6 +801,9 @@ declare const ToolSchema: z.ZodObject<{
             description: string;
         }[];
     } | undefined;
+    cache?: false | {
+        ttlMs?: number | undefined;
+    } | undefined;
 }, {
     id: string;
     params: Record<string, string>;
@@ -809,6 +820,9 @@ declare const ToolSchema: z.ZodObject<{
             description: string;
         }[];
     } | undefined;
+    cache?: false | {
+        ttlMs?: number | undefined;
+    } | undefined;
 }>;
 type Tool$1 = z.infer<typeof ToolSchema>;
 type CollectionOperation = 'getMany' | 'getOne' | 'query' | 'mutation' | 'updateOne' | 'deleteOne' | 'createOne';
@@ -1306,1824 +1320,2163 @@ declare class ReportManager {
     getReportCount(): number;
 }
 
-type SystemPrompt = string | Anthropic.Messages.TextBlockParam[];
-interface LLMMessages {
-    sys: SystemPrompt;
-    user: string;
-    prefill?: string;
-}
-interface LLMOptions {
-    model?: string;
-    maxTokens?: number;
-    temperature?: number;
-    topP?: number;
-    apiKey?: string;
-    partial?: (chunk: string) => void;
-}
-interface Tool {
-    name: string;
-    description: string;
-    input_schema: {
-        type: string;
-        properties: Record<string, any>;
-        required?: string[];
-    };
-}
-declare class LLM {
-    static text(messages: LLMMessages, options?: LLMOptions): Promise<string>;
-    static stream<T = string>(messages: LLMMessages, options?: LLMOptions, json?: boolean): Promise<T extends string ? string : any>;
-    static streamWithTools(messages: LLMMessages, tools: Tool[], toolHandler: (toolName: string, toolInput: any) => Promise<any>, options?: LLMOptions, maxIterations?: number): Promise<string>;
+/**
+ * StreamBuffer - Buffered streaming utility for smoother text delivery
+ * Batches small chunks together and flushes at regular intervals
+ */
+type StreamCallback = (chunk: string) => void;
+/**
+ * StreamBuffer class for managing buffered streaming output
+ * Provides smooth text delivery by batching small chunks
+ */
+declare class StreamBuffer {
+    private buffer;
+    private flushTimer;
+    private callback;
+    private fullText;
+    constructor(callback?: StreamCallback);
     /**
-     * Normalize system prompt to Anthropic format
-     * Converts string to array format if needed
-     * @param sys - System prompt (string or array of blocks)
-     * @returns Normalized system prompt for Anthropic API
+     * Check if the buffer has a callback configured
      */
-    private static _normalizeSystemPrompt;
+    hasCallback(): boolean;
     /**
-     * Log cache usage metrics from Anthropic API response
-     * Shows cache hits, costs, and savings
+     * Get all text that has been written (including already flushed)
      */
-    private static _logCacheUsage;
+    getFullText(): string;
     /**
-     * Parse model string to extract provider and model name
-     * @param modelString - Format: "provider/model-name" or just "model-name"
-     * @returns [provider, modelName]
+     * Write a chunk to the buffer
+     * Large chunks or chunks with newlines are flushed immediately
+     * Small chunks are batched and flushed after a short interval
      *
-     * @example
-     * "anthropic/claude-sonnet-4-5" → ["anthropic", "claude-sonnet-4-5"]
-     * "groq/openai/gpt-oss-120b" → ["groq", "openai/gpt-oss-120b"]
-     * "claude-sonnet-4-5" → ["anthropic", "claude-sonnet-4-5"] (default)
+     * @param chunk - Text chunk to write
      */
-    private static _parseModel;
-    private static _anthropicText;
-    private static _anthropicStream;
-    private static _anthropicStreamWithTools;
-    private static _groqText;
-    private static _groqStream;
-    private static _geminiText;
-    private static _geminiStream;
+    write(chunk: string): void;
     /**
-     * Recursively strip unsupported JSON Schema properties for Gemini
-     * Gemini doesn't support: additionalProperties, $schema, etc.
+     * Flush the buffer immediately
+     * Call this before tool execution or other operations that need clean output
      */
-    private static _cleanSchemaForGemini;
-    private static _geminiStreamWithTools;
-    private static _openaiText;
-    private static _openaiStream;
-    private static _openaiStreamWithTools;
+    flush(): void;
     /**
-     * Parse JSON string, handling markdown code blocks and surrounding text
-     * Enhanced version with jsonrepair to handle malformed JSON from LLMs
-     * @param text - Text that may contain JSON wrapped in ```json...``` or with surrounding text
-     * @returns Parsed JSON object or array
+     * Internal flush implementation
      */
-    private static _parseJSON;
+    private flushNow;
+    /**
+     * Clean up resources
+     * Call this when done with the buffer
+     */
+    dispose(): void;
 }
 
-interface CapturedLog {
-    timestamp: number;
-    level: 'info' | 'error' | 'warn' | 'debug';
-    message: string;
-    type?: 'explanation' | 'query' | 'general';
-    data?: Record<string, any>;
+/**
+ * ToolExecutorService - Handles execution of SQL queries and external tools
+ * Extracted from BaseLLM.generateTextResponse for better separation of concerns
+ */
+
+/**
+ * External tool definition
+ */
+interface ExternalTool {
+    id: string;
+    name: string;
+    description?: string;
+    /** Tool type: "source" = routed through SourceAgent, "direct" = called directly by MainAgent */
+    toolType?: 'source' | 'direct';
+    /** Full untruncated schema for source agent (all columns visible) */
+    fullSchema?: string;
+    /** Schema size tier: small (≤50 tables), medium (51-200), large (201-500), very_large (500+) */
+    schemaTier?: string;
+    /** Schema search function for very_large tier — keyword search over entities */
+    schemaSearchFn?: (keywords: string[]) => string;
+    fn: (input: any) => Promise<any>;
+    limit?: number;
+    outputSchema?: any;
+    executionType?: 'immediate' | 'deferred';
+    userProvidedData?: any;
+    params?: Record<string, any>;
 }
 /**
- * UILogCollector captures logs during user prompt processing
- * and sends them to runtime via ui_logs message with uiBlockId as the message id
- * Logs are sent in real-time for streaming effect in the UI
- * Respects the global log level configuration
+ * Executed tool tracking info
  */
-declare class UILogCollector {
-    private logs;
-    private uiBlockId;
-    private clientId;
-    private sendMessage;
-    private currentLogLevel;
-    constructor(clientId: string, sendMessage: (message: Message) => void, uiBlockId?: string);
-    /**
-     * Check if logging is enabled (uiBlockId is provided)
-     */
-    isEnabled(): boolean;
-    /**
-     * Check if a message should be logged based on current log level
-     */
-    private shouldLog;
-    /**
-     * Add a log entry with timestamp and immediately send to runtime
-     * Only logs that pass the log level filter are captured and sent
-     */
-    private addLog;
-    /**
-     * Send a single log to runtime immediately
-     */
-    private sendLogImmediately;
-    /**
-     * Log info message
-     */
-    info(message: string, type?: 'explanation' | 'query' | 'general', data?: Record<string, any>): void;
-    /**
-     * Log error message
-     */
-    error(message: string, type?: 'explanation' | 'query' | 'general', data?: Record<string, any>): void;
-    /**
-     * Log warning message
-     */
-    warn(message: string, type?: 'explanation' | 'query' | 'general', data?: Record<string, any>): void;
-    /**
-     * Log debug message
-     */
-    debug(message: string, type?: 'explanation' | 'query' | 'general', data?: Record<string, any>): void;
-    /**
-     * Log LLM explanation with typed metadata
-     */
-    logExplanation(message: string, explanation: string, data?: Record<string, any>): void;
-    /**
-     * Log generated query with typed metadata
-     */
-    logQuery(message: string, query: string, data?: Record<string, any>): void;
-    /**
-     * Send all collected logs at once (optional, for final summary)
-     */
-    sendAllLogs(): void;
-    /**
-     * Get all collected logs
-     */
-    getLogs(): CapturedLog[];
-    /**
-     * Clear all logs
-     */
-    clearLogs(): void;
-    /**
-     * Set uiBlockId (in case it's provided later)
-     */
-    setUIBlockId(uiBlockId: string): void;
+interface ExecutedToolInfo {
+    id: string;
+    name: string;
+    params: any;
+    result: {
+        _totalRecords: number;
+        _recordsShown: number;
+        _metadata?: any;
+        _sampleData: any[];
+        /** Bounded summary over the FULL fetched result (complete structure). */
+        _summary?: any;
+        /** Up to MAIN_AGENT_COMPLETE_ROWS rows — the complete result when small. */
+        _mainAgentRows?: any[];
+    };
+    outputSchema?: any;
+    sourceSchema?: string;
+    sourceType?: string;
 }
 
 /**
- * Represents an action that can be performed on a UIBlock
+ * Multi-Agent Architecture Types
+ *
+ * Defines interfaces for the hierarchical agent system:
+ * - Main Agent: ONE LLM.streamWithTools() call with source agent tools
+ * - Source Agents: independent agents that query individual data sources
+ *
+ * The main agent sees only source summaries. When it calls a source tool,
+ * the SourceAgent runs independently (own LLM, own retries) and returns clean data.
  */
-interface Action {
+
+/**
+ * Per-entity detail: name, row count, and column names.
+ * Gives the main agent enough context to route to the right source.
+ */
+interface EntityDetail {
+    /** Entity name (table, sheet, endpoint) */
+    name: string;
+    /** Approximate row count */
+    rowCount?: number;
+    /** Column/field names */
+    columns: string[];
+}
+/**
+ * Representation of a data source for the main agent.
+ * Contains entity names WITH column names so the LLM can route accurately.
+ */
+interface SourceSummary {
+    /** Source ID (matches tool ID prefix) */
     id: string;
+    /** Human-readable source name */
     name: string;
+    /** Source type: postgres, excel, rest_api, etc. */
     type: string;
-    [key: string]: any;
+    /** Brief description of what data this source contains */
+    description: string;
+    /** Detailed entity info with column names for routing */
+    entityDetails: EntityDetail[];
+    /** The tool ID associated with this source */
+    toolId: string;
 }
-
 /**
- * UIBlock represents a single user and assistant message block in a thread
- * Contains user question, component metadata, component data, text response, and available actions
- */
-declare class UIBlock {
-    private id;
-    private userQuestion;
-    private generatedComponentMetadata;
-    private componentData;
-    private textResponse;
-    private actions;
-    private createdAt;
-    /**
-     * Creates a new UIBlock instance
-     * @param userQuestion - The user's question or input
-     * @param componentData - The component data object
-     * @param generatedComponentMetadata - Optional metadata about the generated component
-     * @param actions - Optional array of available actions
-     * @param id - Optional custom ID, generates UUID if not provided
-     * @param textResponse - Optional text response from LLM
-     */
-    constructor(userQuestion: string, componentData?: Record<string, any>, generatedComponentMetadata?: Record<string, any>, actions?: Action[], id?: string, textResponse?: string | null);
+ * What a source agent returns after querying its data source.
+ * The main agent uses this to analyze and compose the final response.
+ */
+interface SourceAgentResult {
+    /** Source ID */
+    sourceId: string;
+    /** Source name */
+    sourceName: string;
+    /** Whether the query succeeded */
+    success: boolean;
+    /** Result data rows */
+    data: any[];
+    /** Metadata about the query execution */
+    metadata: SourceAgentMetadata;
+    /** Tool execution info for the last successful query (backward compat) */
+    executedTool: ExecutedToolInfo;
+    /** All successful tool executions (primary + follow-up queries) */
+    allExecutedTools?: ExecutedToolInfo[];
+    /** Error message if failed */
+    error?: string;
+}
+interface SourceAgentMetadata {
+    /** Total rows that matched the query (before limit) */
+    totalRowsMatched: number;
+    /** Rows actually returned (after limit) */
+    rowsReturned: number;
+    /** Whether the result was truncated by the row limit */
+    isLimited: boolean;
+    /** The query/params that were executed */
+    queryExecuted?: string;
+    /** Execution time in milliseconds */
+    executionTimeMs: number;
+}
+/**
+ * A pre-built, multi-step UI flow registered with the SDK.
+ *
+ * When the main agent decides a user's question matches a workflow's whenToUse
+ * trigger, it picks the workflow instead of running source agents / generating
+ * dashboard components. The LLM extracts the workflow's required props from the
+ * prompt (using `propsSchema` as the tool input_schema) and the SDK returns the
+ * workflow component directly — no analysis text, no chart generation. The
+ * frontend renders the registered workflow component with the LLM-extracted
+ * props.
+ */
+interface WorkflowDescriptor {
+    /** Unique workflow id (used as the LLM tool name) */
+    id: string;
+    /** Component name on the frontend (matches the registered React component) */
+    name: string;
+    /** Short human-readable description of what this workflow does */
+    description: string;
     /**
-     * Get the UIBlock ID
+     * 1–2 sentence trigger condition. The LLM uses this to decide if the
+     * user's prompt matches this workflow. Be specific — e.g.
+     * "User wants to *initiate* an inventory transfer (review + submit POs),
+     * not just see analysis or charts."
      */
-    getId(): string;
+    whenToUse: string;
     /**
-     * Get the user question
+     * JSON-schema-style description of the props the workflow needs. Becomes
+     * the LLM tool's input_schema, so the model fills these from the prompt.
+     * Use the same shape as `params` on direct tools — string descriptors with
+     * an optional "(optional)" suffix.
+     *
+     * Example:
+     * ```
+     * {
+     *   selectedStore: 'object — { id, name } of the source branch',
+     *   minROI: 'number (optional) — only show transfers with ROI ≥ this',
+     * }
+     * ```
      */
-    getUserQuestion(): string;
+    propsSchema: Record<string, string>;
     /**
-     * Set or update the user question
+     * Optional: static prop defaults merged with LLM-extracted props before
+     * the component is returned. Useful for things like the embedded
+     * `externalTool` config that the workflow uses to fetch its own data.
      */
-    setUserQuestion(question: string): void;
+    defaultProps?: Record<string, any>;
+}
+/**
+ * The workflow selection captured during a routing call.
+ * Set on AgentResponse when the LLM picks a workflow tool.
+ */
+interface SelectedWorkflow {
+    /** Component name (matches WorkflowDescriptor.name) */
+    name: string;
+    /** Props extracted from the prompt + merged with workflow.defaultProps */
+    props: Record<string, any>;
+}
+/**
+ * The complete response from the multi-agent system.
+ * Contains everything needed for text display + component generation.
+ */
+interface AgentResponse {
+    /** Generated text response (analysis of the data) */
+    text: string;
+    /** All executed tools across all source agents (for component generation) */
+    executedTools: ExecutedToolInfo[];
+    /** Individual results from each source agent */
+    sourceResults: SourceAgentResult[];
     /**
-     * Get component metadata
+     * Populated when MainAgent wrote AND successfully executed a script during its turn.
+     * Caller (agent-user-response.ts) persists it via ScriptStore.save().
+     * Absent when MainAgent didn't write one (trivial question / all attempts failed).
      */
-    getComponentMetadata(): Record<string, any>;
-    getTextResponse(): string;
+    savedScript?: AgentWrittenScript;
     /**
-     * Set or update component metadata
+     * Set when the LLM routed the question to a registered workflow component.
+     * When present, the upstream caller should skip component generation and
+     * return this workflow as the response.
      */
-    setComponentMetadata(metadata: Record<string, any>): void;
+    workflow?: SelectedWorkflow;
+}
+/**
+ * A script MainAgent authored + verified during its turn. Shape aligns with
+ * what ScriptStore.save() needs — minus store-assigned fields (id, timestamps, counts).
+ */
+interface AgentWrittenScript {
     /**
-     * Get component data
+     * `ScriptRecipe.id` of the draft that was authored + verified during this turn.
+     * The caller passes this to `ScriptStore.promoteToVerified(recipeId, …)` to
+     * flip the draft to verified status and (when possible) drop the turn-suffix
+     * from its filename.
      */
-    getComponentData(): Record<string, any>;
+    recipeId: string;
+    name: string;
+    intentDescription: string;
+    tags: string[];
+    parameters: Array<{
+        name: string;
+        type: 'string' | 'number' | 'date' | 'date_range' | 'enum' | 'boolean';
+        required: boolean;
+        default?: any;
+        enumValues?: Record<string, string>;
+        description: string;
+    }>;
+    scriptBody: string;
+    /** Source IDs referenced by the script (extracted from ctx.query calls) */
+    sourceIds: string[];
+    /** Tables referenced in the script's SQL (regex-extracted) */
+    tables: string[];
+    /** Executed queries from the verified run — fed to component generation */
+    executedQueries: Array<{
+        sourceId: string;
+        sourceName: string;
+        sql: string;
+        data: any[];
+        count: number;
+        totalCount?: number;
+        executionTimeMs: number;
+        /**
+         * True for synthetic entries (ctx.emit datasets, the computed:_final
+         * post-JS data). The component generator routes virtual sources through
+         * the script_dataset sentinel toolId so the frontend resolves them via
+         * queryCache instead of attempting to re-execute SQL.
+         */
+        virtual?: boolean;
+    }>;
+}
+/**
+ * Configuration for the multi-agent system.
+ * Controls limits, models, and behavior.
+ */
+interface AgentConfig {
+    /** Max rows shown to the UI preview / inlined per source (default: 10) */
+    maxRowsPerSource: number;
     /**
-     * Calculate size of data in bytes
+     * Max rows a source query may FETCH from the DB server-side (default: 2000).
+     * Decoupled from what the main agent is shown: the full result is fetched and
+     * summarized (bounded), but only a small/complete slice enters LLM context.
+     * This lets small lookups (benchmark maps) arrive COMPLETE without letting
+     * large results blow up context.
      */
-    private getDataSizeInBytes;
+    maxRowsFetched: number;
+    /** Model for the main agent (routing + analysis in one LLM call) */
+    mainAgentModel: string;
+    /** Model for source agent query generation */
+    sourceAgentModel: string;
+    /** API key for LLM calls */
+    apiKey?: string;
+    /** Max retry attempts per source agent */
+    maxRetries: number;
+    /** Max tool calling iterations for the main agent loop */
+    maxIterations: number;
+    /** Global knowledge base context (static, same for all users/questions — cached in system prompt) */
+    globalKnowledgeBase?: string;
+    /** Per-request knowledge base context (user-specific + query-matched — dynamic, not cached) */
+    knowledgeBaseContext?: string;
+    /** Collections registry (ChromaDB search hooks) for embedding-based schema + source search */
+    collections?: any;
+    /** Optional project ID for scoping embedding searches */
+    projectId?: string;
+}
+/**
+ * Default agent configuration
+ */
+declare const DEFAULT_AGENT_CONFIG: AgentConfig;
+
+/**
+ * Script Flow Types
+ *
+ * Defines interfaces for the script-based query architecture:
+ * - ScriptRecipe: metadata for matching, validation, and quality tracking
+ * - ScriptResult: output from executing a script
+ * - ScriptMatch: result from the LLM-based script matcher
+ */
+/**
+ * Recipe metadata stored alongside each script.
+ * Used for matching, validation, and quality tracking.
+ */
+interface ScriptRecipe {
+    /** Unique script identifier */
+    id: string;
+    /** Version number (incremented on regeneration) */
+    version: number;
+    /** Human-readable name (e.g., "Revenue by Dimension") */
+    name: string;
+    /** Natural language description of what this script does */
+    intentDescription: string;
+    /** Keyword tags for quick filtering */
+    tags: string[];
+    /** Source tool IDs this script queries (e.g., ["mssql-abc123_query"]) */
+    sourceIds: string[];
+    /** Table names used (for future schema drift detection) */
+    tables: string[];
+    /** Parameter definitions — what can vary */
+    parameters: ScriptParameter[];
+    /** The script function body as a string. Loaded from disk (scripts-store/<fileBase>.ts). */
+    scriptBody: string;
     /**
-     * Limit array data to maximum rows
+     * On-disk filename stem for the body: scripts-store/<fileBase>.ts.
+     * Editable in the IDE. Decided at authoring time (slug of `name`, with a
+     * short id suffix on collision) and stable across promotion.
      */
-    private limitArrayData;
+    fileBase?: string;
+    /** sha256 of the on-disk body — lets the runtime detect manual edits. */
+    bodyHash?: string;
+    /** Project scope (single-VM deployments may leave this undefined). */
+    projectId?: string;
+    /** Times this script was used successfully */
+    successCount: number;
+    /** Times this script failed */
+    failureCount: number;
+    /** ISO timestamp of last usage */
+    lastUsed: string;
+    /** Original user question that created this script */
+    createdFrom: string;
+    /** ISO timestamp */
+    createdAt: string;
+    /** ISO timestamp */
+    updatedAt: string;
     /**
-     * Check if data exceeds size limit
+     * `recipe.id` of the parent this script was forked from.
+     * Undefined for root scripts (those written from scratch by MainAgent).
+     * See backend/docs/SCRIPT-FLOW-FORK-ADAPT.md.
      */
-    private exceedsSizeLimit;
+    parentId?: string;
+    /** 0 for root scripts; `parent.forkDepth + 1` for forks. Capped at 3. */
+    forkDepth?: number;
     /**
-     * Process and limit data before storing
+     * Brief description of what this fork changed vs its parent
+     * (sourced from the matcher's `modificationHint`).
      */
-    private processDataForStorage;
+    forkReason?: string;
     /**
-     * Set or update component data with size and row limits
+     * Validated component specs captured at authoring time. On a tier-high
+     * replay these are rebound to fresh queryIds deterministically — no
+     * component-generation LLM call, and the rendered columns can't drift from
+     * what was validated when the script was authored. Absent on recipes
+     * authored before this landed; those fall back to LLM component generation.
+     * See backend/docs/SCRIPT-COMPONENT-CONSISTENCY.md.
      */
-    setComponentData(data: Record<string, any>): void;
+    components?: ScriptComponentSpec[];
     /**
-     * Set or update text response
+     * Lifecycle stage of this recipe on disk.
+     * - 'draft':    written by MainAgent's write_script during a turn; filtered out
+     *               of FTS results (status='verified' only) so the matcher never picks it.
+     *               Filename is suffixed with `turnId` to keep concurrent turns
+     *               from clobbering each other's drafts.
+     * - 'verified': promoted after `execute_script` succeeded; the matcher sees it.
+     *               Filename drops the turn suffix unless a verified file with
+     *               the same slug already exists (collision case keeps the suffix).
+     *
+     * Recipes loaded from disk without this field default to 'verified' so
+     * existing scripts keep working unchanged.
      */
-    setTextResponse(textResponse: string | null): void;
+    status?: 'draft' | 'verified';
     /**
-     * Get all actions (only if they are resolved, not if fetching)
+     * Per-turn unique suffix used for draft filenames (e.g. `1714745623-x9k2`).
+     * Set when the draft is saved; carried until the recipe is promoted.
      */
-    getActions(): Action[] | null | Promise<Action[]>;
+    turnId?: string;
     /**
-     * Get or fetch actions
-     * If actions don't exist or are a Promise, calls the generateFn and stores the promise
-     * If actions already exist, returns them
-     * @param generateFn - Async function to generate actions
-     * @returns Promise resolving to Action[]
+     * Last execution error captured by `recordDraftError` while the recipe was
+     * still a draft. Lets users open the draft .json file and see why it failed
+     * without grepping logs. Cleared on promotion to 'verified'.
      */
-    getOrFetchActions(generateFn: () => Promise<Action[]>): Promise<Action[]>;
-    /**
-     * Set or replace all actions
-     */
-    setActions(actions: Action[]): void;
-    /**
-     * Add a single action (only if actions are resolved)
-     */
-    addAction(action: Action): void;
-    /**
-     * Add multiple actions (only if actions are resolved)
-     */
-    addActions(actions: Action[]): void;
-    /**
-     * Remove an action by ID (only if actions are resolved)
-     */
-    removeAction(actionId: string): boolean;
-    /**
-     * Clear all actions
-     */
-    clearActions(): void;
+    lastError?: {
+        phase: 'compile' | 'runtime' | 'timeout' | 'ipc';
+        message: string;
+        at: string;
+        attempt: number;
+    };
+}
+interface ScriptParameter {
+    /** Parameter name (used in script body as params.name) */
+    name: string;
+    /** Parameter type */
+    type: 'string' | 'number' | 'date' | 'date_range' | 'enum' | 'boolean';
+    /** Whether this parameter is required */
+    required: boolean;
+    /** Default value if not provided */
+    default?: any;
+    /** For enum type — maps user-facing values to internal values */
+    enumValues?: Record<string, string>;
+    /** Human-readable description (used in the matcher LLM prompt) */
+    description: string;
+}
+/**
+ * A reusable component binding captured when a script is authored. Stored on
+ * the recipe so tier-high replays rebuild components deterministically (rebind
+ * to fresh queryIds) instead of re-running the component-picker LLM.
+ */
+interface ScriptComponentSpec {
+    /** Registered component name (e.g. "DynamicBarChart") — matched against the available component library. */
+    componentType: string;
+    /** `executedQuery.sourceId` to bind to (e.g. a tool id or 'computed:_final'), 'federation' for a cross-source component, or 'markdown' for a content-only narrative block (no data source). */
+    sourceRef: string;
+    /** Present only when sourceRef === 'federation' — the DuckDB SQL to re-execute on replay. */
+    federationSql?: string;
+    /** Present only when sourceRef === 'markdown' — the narrative text to render on replay (markdown has no data source, so its content must be persisted). */
+    content?: string;
+    title?: string;
+    description?: string;
+    /** Validated axis/value keys + aggregation — all referencing real columns of the bound source. */
+    config: Record<string, any>;
+}
+/**
+ * Result from executing a script via ScriptRunner.
+ */
+interface ScriptResult {
+    /** Whether the script executed successfully */
+    success: boolean;
+    /** Combined data from all queries */
+    data: any[];
+    /** Individual query results tracked during execution */
+    executedQueries: ScriptQueryResult[];
+    /** Error message if failed */
+    error?: string;
     /**
-     * Get creation timestamp
+     * Where in the lifecycle the error occurred. Lets MainAgent's fix-loop
+     * decide between "rewrite the whole draft" (compile) and "patch the
+     * specific line" (runtime).
      */
-    getCreatedAt(): Date;
+    errorPhase?: 'compile' | 'runtime' | 'timeout' | 'ipc';
+    /** Total execution time in milliseconds */
+    executionTimeMs: number;
+}
+/**
+ * A single query executed during script runtime.
+ * Tracked by ScriptContext for component generation and debugging.
+ */
+interface ScriptQueryResult {
+    /** Source tool ID */
+    sourceId: string;
+    /** Human-readable source name */
+    sourceName: string;
+    /** The SQL that was executed */
+    sql: string;
+    /** Result data rows */
+    data: any[];
+    /** Number of rows returned */
+    count: number;
+    /** Total rows that matched before limit (if available) */
+    totalCount?: number;
+    /** Query execution time in milliseconds */
+    executionTimeMs: number;
     /**
-     * Convert UIBlock to JSON-serializable object
+     * True for rows that did NOT come from a real SQL execution — either a
+     * ctx.emit() dataset or the synthesized "computed:_final" entry that
+     * carries the script's post-JS returned data. The component generator
+     * uses this to route the resulting component through the script_dataset
+     * sentinel toolId so the frontend resolves it via the queryCache short-circuit.
      */
-    toJSON(): Record<string, any>;
+    virtual?: boolean;
+}
+/**
+ * Match tier returned by the LLM script matcher.
+ *
+ * - 'high': the script answers the question directly; only parameter values
+ *   may differ. The runtime replays it with extracted params (cheapest path).
+ * - 'near': the script answers a STRUCTURALLY similar question but needs
+ *   body modification (different metric, dimension, table, filter shape).
+ *   The runtime forks the parent and adapts the body via MainAgent's normal
+ *   write_script + execute_script loop — no SourceAgent dispatch needed.
+ *   See backend/docs/SCRIPT-FLOW-FORK-ADAPT.md for the full design.
+ * - 'none': no script is relevant; full agent flow runs.
+ */
+type MatchTier = 'high' | 'near' | 'none';
+/**
+ * Result from the LLM-based script matcher.
+ *
+ * For `tier: 'high'`, `extractedParams` carries the values to pass to the
+ * existing script. For `tier: 'near'`, `gaps` and `modificationHint` describe
+ * what the fork-author needs to change in the parent body.
+ */
+interface ScriptMatch {
+    /** The matched script recipe */
+    recipe: ScriptRecipe;
+    /** Match tier — see MatchTier docs */
+    tier: MatchTier;
+    /** Similarity score (0-1, derived from LLM tier) */
+    similarity: number;
+    /**
+     * Legacy confidence level. Mirrors `tier === 'high'`/`'near'` for now;
+     * kept so existing callers compile while we migrate to tier-based logic.
+     */
+    confidence: 'high' | 'medium';
+    /** Parameters extracted from the user question by the LLM (tier='high') */
+    extractedParams?: Record<string, any>;
+    /** What the user question needs that the parent doesn't cover (tier='near') */
+    gaps?: string[];
+    /** One-sentence description of the change the fork-author should make (tier='near') */
+    modificationHint?: string;
+    /** Why the matcher made this choice (for logs and telemetry) */
+    reasoning?: string;
 }
 
 /**
- * Thread represents a conversation thread containing multiple UIBlocks
- * Each UIBlock in a thread represents a user question and assistant response pair
+ * ScriptRecipeStore — injected metadata backend for the script flow.
+ *
+ * The SDK is standalone (no DB dependency). The backend implements this
+ * interface over Postgres (full-text search + atomic counters) and injects it
+ * via `collections['script-recipes']`, exactly like `collections['source-embeddings']`.
+ * `ScriptStore` consumes it for all METADATA operations while keeping the
+ * executable body on disk as scripts-store/<fileBase>.ts.
+ *
+ * All metadata rows are plain JSON (no scriptBody — that lives on disk).
+ * See backend/docs/SCRIPT-FLOW-SCALING-ISSUES.md (#1, #3, #7).
  */
-declare class Thread {
-    private id;
-    private uiblocks;
-    private createdAt;
+
+/** One recipe's metadata as stored in Postgres (mirrors the script_recipes table). */
+interface ScriptRecipeMetaRow {
+    id: string;
+    projectId?: string | null;
+    version: number;
+    name: string;
+    intentDescription: string;
+    tags: string[] | null;
+    createdFrom: string | null;
+    sourceIds: string[] | null;
+    tables: string[] | null;
+    parameters: ScriptParameter[] | null;
+    components?: ScriptComponentSpec[] | null;
+    fileBase: string;
+    bodyHash?: string | null;
+    successCount: number;
+    failureCount: number;
+    lastUsed: string | null;
+    parentId?: string | null;
+    forkDepth?: number | null;
+    forkReason?: string | null;
+    status: 'draft' | 'verified' | string;
+    turnId?: string | null;
+    lastError?: {
+        phase: 'compile' | 'runtime' | 'timeout' | 'ipc';
+        message: string;
+        at: string;
+        attempt: number;
+    } | null;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+}
+interface ScriptRecipeStore {
+    /** FTS shortlist of healthy verified recipes for the matcher (metadata only). */
+    search(params: {
+        prompt: string;
+        projectId?: string;
+        limit?: number;
+    }): Promise<ScriptRecipeMetaRow[]>;
+    /** Fetch one recipe by id (any status). */
+    getById(id: string): Promise<ScriptRecipeMetaRow | null>;
+    /** Count healthy verified recipes (drives the "any scripts?" gate). */
+    count(params?: {
+        projectId?: string;
+    }): Promise<number>;
+    /** Insert or update a recipe row (keyed by id). */
+    upsert(row: ScriptRecipeMetaRow): Promise<void>;
+    /** Atomically bump counters / last-used. */
+    updateStats(id: string, patch: {
+        successDelta?: number;
+        failureDelta?: number;
+        lastUsed?: string;
+    }): Promise<void>;
+    /** Flip a draft to verified, applying provenance + optional fork lineage. */
+    promote(id: string, patch: {
+        sourceIds: string[];
+        tables: string[];
+        fileBase?: string;
+        parentId?: string;
+        forkDepth?: number;
+        forkReason?: string;
+        components?: ScriptComponentSpec[];
+    }): Promise<ScriptRecipeMetaRow | null>;
+    /** Stamp a draft's last execution error. */
+    recordDraftError(id: string, err: {
+        phase: string;
+        message: string;
+        attempt: number;
+        at: string;
+    }): Promise<void>;
+    /** Delete a recipe row (body file removed separately). */
+    remove(id: string): Promise<void>;
+    /** True if `fileBase` is taken by a different recipe in this project. */
+    fileBaseTaken(fileBase: string, excludeId: string, projectId?: string): Promise<boolean>;
+}
+/** Pull the injected store off the collections bag (or null if not wired). */
+declare function resolveScriptRecipeStore(collections: any): ScriptRecipeStore | null;
+
+/**
+ * ScriptStore — Postgres metadata + on-disk body for script recipes.
+ *
+ * Split of responsibilities:
+ *   - METADATA  → injected `ScriptRecipeStore` (Postgres FTS + atomic counters),
+ *                 resolved from `collections['script-recipes']`.
+ *   - BODY      → scripts-store/<fileBase>.ts, editable in your IDE. Written
+ *                 atomically (temp + rename); `bodyHash` (sha256) detects edits.
+ *
+ * The old "read every file every turn + send the whole catalog to the LLM"
+ * matcher is gone — matching is `store.search(prompt)` (FTS shortlist). The
+ * draft/verified filename dance is gone too: `status` is a DB column and the
+ * file keeps a stable `<fileBase>.ts` name across promotion.
+ *
+ * When no metadata store is injected, the store degrades to a safe no-op
+ * (count 0 → script flow disabled) instead of crashing.
+ *
+ * See backend/docs/SCRIPT-FLOW-SCALING-ISSUES.md.
+ */
+
+interface SaveDraftInput {
+    /** Reuse an existing draft (retry); omit to mint a new one. */
+    recipeId?: string;
+    /** Per-turn unique suffix, stable across retries within the turn. */
+    turnId: string;
+    name: string;
+    intentDescription: string;
+    tags: string[];
+    parameters: ScriptParameter[];
+    scriptBody: string;
+    createdFrom: string;
+}
+interface PromoteToVerifiedInput {
+    sourceIds: string[];
+    tables: string[];
+    parentId?: string;
+    forkDepth?: number;
+    forkReason?: string;
+    components?: ScriptComponentSpec[];
+}
+interface ScriptStoreOptions {
+    /** Explicit metadata store, or resolved from `collections['script-recipes']`. */
+    store?: ScriptRecipeStore | null;
+    collections?: any;
+    /** Body directory (defaults to <cwd>/scripts-store). */
+    baseDir?: string;
+    /** Project scope stamped on every row. */
+    projectId?: string;
+}
+/**
+ * Normalize a scriptBody into the on-disk form (strip a leading comment block,
+ * ensure `export async function getData`). Exported for MainAgent.
+ */
+declare function normalizeScriptBody(scriptBody: string): string;
+declare class ScriptStore {
+    private store;
+    private storeDir;
+    private projectId?;
+    constructor(opts?: ScriptStoreOptions);
+    /** Whether a metadata store is wired (matcher / authoring are gated on this). */
+    hasStore(): boolean;
+    /** Number of healthy verified recipes (gates the script-matching path). */
+    count(): Promise<number>;
+    /**
+     * FTS shortlist for the matcher (metadata only — bodies are loaded lazily by
+     * `get()` once the LLM picks one). Returns verified, healthy recipes ranked
+     * by relevance.
+     */
+    search(prompt: string, limit?: number): Promise<ScriptRecipe[]>;
+    /** Fetch one recipe by id with its body loaded from disk. */
+    get(id: string): Promise<ScriptRecipe | null>;
+    /** Create or update a recipe (metadata upsert + body write when changed). */
+    save(recipe: ScriptRecipe): Promise<void>;
+    /**
+     * Persist (or update) a draft. Within a turn, retries that pass the same
+     * `recipeId` overwrite the same row + file; a fresh `recipeId` mints a new
+     * draft. The body is visible at scripts-store/<fileBase>.ts immediately.
+     */
+    saveDraft(input: SaveDraftInput): Promise<ScriptRecipe>;
+    /** Stamp a draft's last execution error (metadata only). */
+    recordDraftError(recipeId: string, err: {
+        phase: 'compile' | 'runtime' | 'timeout' | 'ipc';
+        message: string;
+        attempt: number;
+    }): Promise<void>;
     /**
-     * Creates a new Thread instance
-     * @param id - Optional custom ID, generates UUID if not provided
-     */
-    constructor(id?: string);
+     * Promote a successfully-executed draft into a verified script.
+     * The on-disk body already exists at <fileBase>.ts (written at write_script
+     * time) and keeps its name — only the DB row flips status + provenance.
+     */
+    promoteToVerified(recipeId: string, input: PromoteToVerifiedInput): Promise<ScriptRecipe | null>;
+    /**
+     * Drop a draft (row + body file). MainAgent calls this at end-of-turn when a
+     * draft was authored but never verified — failed drafts are never matched, so
+     * deleting them immediately avoids unbounded accumulation (#5). No-op if the
+     * recipe isn't a draft (so a promoted/verified script is never removed here).
+     */
+    discardDraft(recipeId: string): Promise<void>;
+    /** Delete a recipe (row + body file). */
+    delete(id: string): Promise<void>;
+    /** Record a successful execution (atomic counter bump). */
+    recordSuccess(id: string): Promise<void>;
+    /** Record a failed execution (atomic counter bump). */
+    recordFailure(id: string): Promise<void>;
+    /** Absolute path to the .ts body for a recipe (used by the runner/MainAgent). */
+    getScriptPath(recipe: ScriptRecipe): string;
+    private removeById;
+    private rowToRecipe;
+    private recipeToRow;
+    /** slug of name, with a short id suffix when the bare slug is already taken. */
+    private computeFileBase;
+    private toSlug;
+    private hash;
+    private bodyPath;
+    private readBody;
+    /** Atomic body write (temp + rename) so concurrent reads never see a partial file. */
+    private writeBody;
+    private unlinkBody;
+}
+
+/**
+ * Main Agent (Orchestrator)
+ *
+ * A single LLM.streamWithTools() call that handles everything:
+ * - Routing: decides which source(s) to query based on summaries
+ * - Querying: calls source tools (each wraps an independent SourceAgent)
+ * - Direct tools: calls pre-built function tools directly with LLM-provided params
+ * - Re-querying: if data is wrong/incomplete, calls tools again with modified intent
+ * - Analysis: generates final text response from the data
+ *
+ * Two tool types:
+ * - "source" tools: main agent sees summaries, SourceAgent handles SQL generation independently
+ * - "direct" tools: main agent calls fn() directly with structured params (no SourceAgent)
+ */
+
+declare class MainAgent {
+    private externalTools;
+    private workflows;
+    private config;
+    private streamBuffer;
     /**
-     * Get the thread ID
+     * Optional: when provided, MainAgent exposes the `write_script` /
+     * `execute_script` tools to the LLM and persists drafts to disk via the
+     * store. Headless callers (alert analyzer, metric resolver) omit these to
+     * suppress script authoring entirely — drafts would otherwise leak onto
+     * disk with no caller to promote or clean them up.
      */
-    getId(): string;
+    private scriptStore;
+    private turnId;
+    private createdFromPrompt;
+    private scriptState;
+    constructor(externalTools: ExternalTool[], config: AgentConfig, scriptStore?: ScriptStore, turnId?: string, streamBuffer?: StreamBuffer, workflows?: WorkflowDescriptor[]);
+    private get scriptingEnabled();
     /**
-     * Add a UIBlock to the thread
+     * Handle a user question using the multi-agent system.
+     *
+     * This is ONE LLM.streamWithTools() call. The LLM:
+     * 1. Sees source summaries + direct tool descriptions in system prompt
+     * 2. Decides which tool(s) to call (routing)
+     * 3. Source tools → SourceAgent runs independently → returns data
+     * 4. Direct tools → fn() called directly with LLM params → returns data
+     * 5. Generates final analysis text
      */
-    addUIBlock(uiblock: UIBlock): void;
+    handleQuestion(userPrompt: string, apiKey?: string, conversationHistory?: string, streamCallback?: (chunk: string) => void): Promise<AgentResponse>;
+    private handleWriteScript;
+    private handleExecuteScript;
     /**
-     * Get a UIBlock by ID
+     * Build the AgentWrittenScript payload the caller will hand to
+     * `ScriptStore.promoteToVerified()`. Only returned when a verified
+     * successful execution is on record.
      */
-    getUIBlock(id: string): UIBlock | undefined;
+    private buildSavedScript;
+    private normalizeParameterList;
     /**
-     * Get all UIBlocks in the thread
+     * Use the schema embedding collection to pre-select relevant tables for
+     * this source + intent. Returns a formatted schema block if confidence is
+     * high (top match ≥ 0.55 and ≥3 candidates), otherwise null.
+     *
+     * When this returns a block, we can skip the SourceAgent's `search_schema`
+     * loop and reduce iteration budget. When it returns null, the SourceAgent
+     * falls back to the existing LLM-driven keyword search (same as today).
      */
-    getUIBlocks(): UIBlock[];
+    private preResolveSchema;
     /**
-     * Get UIBlocks as a Map
+     * Execute a direct tool — call fn() with LLM-provided params, no SourceAgent.
      */
-    getUIBlocksMap(): Map<string, UIBlock>;
+    private handleDirectTool;
     /**
-     * Remove a UIBlock by ID
+     * Build the main agent's system prompt with source summaries, direct tool descriptions,
+     * and workflow component descriptions.
      */
-    removeUIBlock(id: string): boolean;
+    private buildSystemPrompt;
     /**
-     * Check if UIBlock exists
+     * Build tool definitions for source tools — summary-only descriptions.
+     * The full schema is inside the SourceAgent which runs independently.
      */
-    hasUIBlock(id: string): boolean;
+    private buildSourceToolDefinitions;
     /**
-     * Get number of UIBlocks in the thread
+     * Build tool definitions for direct tools — expose their actual params.
+     * These are called directly by the main agent LLM, no SourceAgent.
      */
-    getUIBlockCount(): number;
+    private buildDirectToolDefinitions;
     /**
-     * Clear all UIBlocks from the thread
+     * Capture a workflow selection. We do NOT execute anything — the LLM has
+     * already extracted the props it wants the workflow rendered with. We
+     * record the selection (via the capture callback) and return a short
+     * acknowledgement so the LLM ends its turn cleanly without writing
+     * analysis text or calling more tools.
      */
-    clear(): void;
+    private handleWorkflow;
     /**
-     * Get creation timestamp
+     * Build LLM tool definitions for workflow components. The workflow's
+     * propsSchema becomes the tool's input_schema so the LLM extracts props
+     * directly from the prompt — same mechanic as direct tools.
      */
-    getCreatedAt(): Date;
+    private buildWorkflowToolDefinitions;
     /**
-     * Get conversation context from recent UIBlocks (excluding current one)
-     * Returns formatted string with previous questions and component summaries
-     * @param limit - Maximum number of previous UIBlocks to include (default: 5)
-     * @param currentUIBlockId - ID of current UIBlock to exclude from context (optional)
-     * @returns Formatted conversation history string
+     * Format a source agent's result as a clean string for the main agent LLM.
      */
-    getConversationContext(limit?: number, currentUIBlockId?: string): string;
+    private formatResultForMainAgent;
     /**
-     * Convert Thread to JSON-serializable object
+     * Get source summaries (for external inspection/debugging).
      */
-    toJSON(): Record<string, any>;
+    getSourceSummaries(): SourceSummary[];
 }
 
 /**
- * ThreadManager manages all threads globally
- * Provides methods to create, retrieve, and delete threads.
- * Includes automatic cleanup to prevent unbounded memory growth.
+ * Represents an action that can be performed on a UIBlock
  */
-declare class ThreadManager {
-    private static instance;
-    private threads;
-    private cleanupInterval;
-    private readonly threadTtlMs;
-    private constructor();
-    /**
-     * Periodically remove threads older than 7 days.
-     * Runs every hour to avoid frequent iteration over the map.
-     */
-    private startCleanup;
-    /**
-     * Get singleton instance of ThreadManager
-     */
-    static getInstance(): ThreadManager;
+interface Action {
+    id: string;
+    name: string;
+    type: string;
+    [key: string]: any;
+}
+
+type SystemPrompt = string | Anthropic.Messages.TextBlockParam[];
+interface LLMMessages {
+    sys: SystemPrompt;
+    user: string;
+    prefill?: string;
+}
+interface LLMOptions {
+    model?: string;
+    maxTokens?: number;
+    temperature?: number;
+    topP?: number;
+    apiKey?: string;
+    partial?: (chunk: string) => void;
+}
+interface Tool {
+    name: string;
+    description: string;
+    input_schema: {
+        type: string;
+        properties: Record<string, any>;
+        required?: string[];
+    };
+}
+declare class LLM {
+    static text(messages: LLMMessages, options?: LLMOptions): Promise<string>;
+    static stream<T = string>(messages: LLMMessages, options?: LLMOptions, json?: boolean): Promise<T extends string ? string : any>;
+    static streamWithTools(messages: LLMMessages, tools: Tool[], toolHandler: (toolName: string, toolInput: any) => Promise<any>, options?: LLMOptions, maxIterations?: number): Promise<string>;
     /**
-     * Create a new thread
-     * @param id - Optional custom ID, generates UUID if not provided
-     * @returns The created Thread instance
+     * Normalize system prompt to Anthropic format
+     * Converts string to array format if needed
+     * @param sys - System prompt (string or array of blocks)
+     * @returns Normalized system prompt for Anthropic API
      */
-    createThread(id?: string): Thread;
+    private static _normalizeSystemPrompt;
     /**
-     * Get a thread by ID
+     * Strip unpaired UTF-16 surrogates from every text field of a message set.
+     *
+     * A lone surrogate (from mid-pair string slicing or corrupt source data)
+     * serializes to a bare `\udXXX` escape that strict JSON parsers — including
+     * the one on Anthropic's API — reject with "no low surrogate in string",
+     * failing the whole request. Sanitizing here, at the single boundary every
+     * provider call flows through, guarantees no request can carry one.
      */
-    getThread(id: string): Thread | undefined;
+    private static _sanitizeMessages;
     /**
-     * Get all threads
+     * Log cache usage metrics from Anthropic API response
+     * Shows cache hits, costs, and savings
      */
-    getAllThreads(): Thread[];
+    private static _logCacheUsage;
     /**
-     * Get threads as a Map
+     * Parse model string to extract provider and model name
+     * @param modelString - Format: "provider/model-name" or just "model-name"
+     * @returns [provider, modelName]
+     *
+     * @example
+     * "anthropic/claude-sonnet-4-5" → ["anthropic", "claude-sonnet-4-5"]
+     * "groq/openai/gpt-oss-120b" → ["groq", "openai/gpt-oss-120b"]
+     * "claude-sonnet-4-5" → ["anthropic", "claude-sonnet-4-5"] (default)
      */
-    getThreadsMap(): Map<string, Thread>;
+    private static _parseModel;
+    private static _anthropicText;
+    private static _anthropicStream;
+    private static _anthropicStreamWithTools;
+    private static _groqText;
+    private static _groqStream;
+    private static _geminiText;
+    private static _geminiStream;
     /**
-     * Delete a thread by ID
+     * Recursively strip unsupported JSON Schema properties for Gemini
+     * Gemini doesn't support: additionalProperties, $schema, etc.
      */
-    deleteThread(id: string): boolean;
+    private static _cleanSchemaForGemini;
+    private static _geminiStreamWithTools;
+    private static _openaiText;
+    private static _openaiStream;
+    private static _openaiStreamWithTools;
     /**
-     * Check if thread exists
+     * Parse JSON string, handling markdown code blocks and surrounding text
+     * Enhanced version with jsonrepair to handle malformed JSON from LLMs
+     * @param text - Text that may contain JSON wrapped in ```json...``` or with surrounding text
+     * @returns Parsed JSON object or array
      */
-    hasThread(id: string): boolean;
+    private static _parseJSON;
+}
+
+interface CapturedLog {
+    timestamp: number;
+    level: 'info' | 'error' | 'warn' | 'debug';
+    message: string;
+    type?: 'explanation' | 'query' | 'general';
+    data?: Record<string, any>;
+}
+/**
+ * UILogCollector captures logs during user prompt processing
+ * and sends them to runtime via ui_logs message with uiBlockId as the message id
+ * Logs are sent in real-time for streaming effect in the UI
+ * Respects the global log level configuration
+ */
+declare class UILogCollector {
+    private logs;
+    private uiBlockId;
+    private clientId;
+    private sendMessage;
+    private currentLogLevel;
+    constructor(clientId: string, sendMessage: (message: Message) => void, uiBlockId?: string);
     /**
-     * Get number of threads
+     * Check if logging is enabled (uiBlockId is provided)
      */
-    getThreadCount(): number;
+    isEnabled(): boolean;
     /**
-     * Clear all threads
+     * Check if a message should be logged based on current log level
      */
-    clearAll(): void;
+    private shouldLog;
     /**
-     * Find a UIBlock by ID across all threads
-     * @param uiBlockId - The UIBlock ID to search for
-     * @returns Object with thread and uiBlock if found, undefined otherwise
+     * Add a log entry with timestamp and immediately send to runtime
+     * Only logs that pass the log level filter are captured and sent
      */
-    findUIBlockById(uiBlockId: string): {
-        thread: Thread;
-        uiBlock: UIBlock;
-    } | undefined;
+    private addLog;
     /**
-     * Convert all threads to JSON-serializable object
+     * Send a single log to runtime immediately
      */
-    toJSON(): Record<string, any>;
-}
-
-/**
- * CleanupService handles cleanup of old threads and UIBlocks
- * to prevent memory bloat and maintain optimal performance
- */
-declare class CleanupService {
-    private static instance;
-    private cleanupInterval;
-    private constructor();
+    private sendLogImmediately;
     /**
-     * Get singleton instance of CleanupService
+     * Log info message
      */
-    static getInstance(): CleanupService;
+    info(message: string, type?: 'explanation' | 'query' | 'general', data?: Record<string, any>): void;
     /**
-     * Clean up old threads based on retention period
-     * @param retentionDays - Number of days to keep threads (defaults to config)
-     * @returns Number of threads deleted
+     * Log error message
      */
-    cleanupOldThreads(retentionDays?: number): number;
+    error(message: string, type?: 'explanation' | 'query' | 'general', data?: Record<string, any>): void;
     /**
-     * Clean up old UIBlocks within threads based on retention period
-     * @param retentionDays - Number of days to keep UIBlocks (defaults to config)
-     * @returns Object with number of UIBlocks deleted per thread
+     * Log warning message
      */
-    cleanupOldUIBlocks(retentionDays?: number): {
-        [threadId: string]: number;
-    };
+    warn(message: string, type?: 'explanation' | 'query' | 'general', data?: Record<string, any>): void;
     /**
-     * Clear all component data from UIBlocks to free memory
-     * Keeps metadata but removes the actual data
-     * @param retentionDays - Number of days to keep full data (defaults to config)
-     * @returns Number of UIBlocks whose data was cleared
+     * Log debug message
      */
-    clearOldUIBlockData(retentionDays?: number): number;
+    debug(message: string, type?: 'explanation' | 'query' | 'general', data?: Record<string, any>): void;
     /**
-     * Run full cleanup (threads, UIBlocks, and data)
-     * @returns Cleanup statistics
+     * Log LLM explanation with typed metadata
      */
-    runFullCleanup(): {
-        threadsDeleted: number;
-        uiblocksDeleted: {
-            [threadId: string]: number;
-        };
-        dataCleared: number;
-    };
+    logExplanation(message: string, explanation: string, data?: Record<string, any>): void;
     /**
-     * Start automatic cleanup at regular intervals
-     * @param intervalHours - Hours between cleanup runs (default: 24)
+     * Log generated query with typed metadata
      */
-    startAutoCleanup(intervalHours?: number): void;
+    logQuery(message: string, query: string, data?: Record<string, any>): void;
     /**
-     * Stop automatic cleanup
+     * Send all collected logs at once (optional, for final summary)
      */
-    stopAutoCleanup(): void;
+    sendAllLogs(): void;
     /**
-     * Check if auto cleanup is running
+     * Get all collected logs
      */
-    isAutoCleanupRunning(): boolean;
+    getLogs(): CapturedLog[];
     /**
-     * Get current memory usage statistics
+     * Clear all logs
      */
-    getMemoryStats(): {
-        threadCount: number;
-        totalUIBlocks: number;
-        avgUIBlocksPerThread: number;
-    };
+    clearLogs(): void;
+    /**
+     * Set uiBlockId (in case it's provided later)
+     */
+    setUIBlockId(uiBlockId: string): void;
 }
 
 /**
- * Configuration for data storage limits in UIBlocks
+ * UIBlock represents a single user and assistant message block in a thread
+ * Contains user question, component metadata, component data, text response, and available actions
  */
-declare const STORAGE_CONFIG: {
+declare class UIBlock {
+    private id;
+    private userQuestion;
+    private generatedComponentMetadata;
+    private componentData;
+    private textResponse;
+    private actions;
+    private createdAt;
     /**
-     * Maximum number of rows to store in UIBlock data
+     * Creates a new UIBlock instance
+     * @param userQuestion - The user's question or input
+     * @param componentData - The component data object
+     * @param generatedComponentMetadata - Optional metadata about the generated component
+     * @param actions - Optional array of available actions
+     * @param id - Optional custom ID, generates UUID if not provided
+     * @param textResponse - Optional text response from LLM
      */
-    MAX_ROWS_PER_BLOCK: number;
+    constructor(userQuestion: string, componentData?: Record<string, any>, generatedComponentMetadata?: Record<string, any>, actions?: Action[], id?: string, textResponse?: string | null);
     /**
-     * Maximum size in bytes per UIBlock (500KB - reduced to save memory)
+     * Get the UIBlock ID
      */
-    MAX_SIZE_PER_BLOCK_BYTES: number;
+    getId(): string;
     /**
-     * Number of days to keep threads before cleanup
-     * Note: This is for in-memory storage. Conversations are also persisted to database.
+     * Get the user question
      */
-    THREAD_RETENTION_DAYS: number;
+    getUserQuestion(): string;
     /**
-     * Number of days to keep UIBlocks before cleanup
-     * Note: This is for in-memory storage. Data is also persisted to database.
+     * Set or update the user question
      */
-    UIBLOCK_RETENTION_DAYS: number;
-};
-
-/**
- * Configuration for conversation context and history management
- */
-declare const CONTEXT_CONFIG: {
+    setUserQuestion(question: string): void;
     /**
-     * Maximum number of previous UIBlocks to include as conversation context
-     * Set to 0 to disable conversation history
-     * Higher values provide more context but may increase token usage
+     * Get component metadata
      */
-    MAX_CONVERSATION_CONTEXT_BLOCKS: number;
-};
-
-/**
- * LLM Usage Logger - Tracks token usage, costs, and timing for all LLM API calls
- */
-interface LLMUsageEntry {
-    timestamp: string;
-    requestId: string;
-    provider: string;
-    model: string;
-    method: string;
-    inputTokens: number;
-    outputTokens: number;
-    cacheReadTokens?: number;
-    cacheWriteTokens?: number;
-    totalTokens: number;
-    costUSD: number;
-    durationMs: number;
-    toolCalls?: number;
-    success: boolean;
-    error?: string;
-}
-declare class LLMUsageLogger {
-    private logStream;
-    private logPath;
-    private enabled;
-    private sessionStats;
-    constructor();
-    private initLogStream;
-    private writeHeader;
+    getComponentMetadata(): Record<string, any>;
+    getTextResponse(): string;
     /**
-     * Calculate cost based on token usage and model
+     * Set or update component metadata
      */
-    calculateCost(model: string, inputTokens: number, outputTokens: number, cacheReadTokens?: number, cacheWriteTokens?: number): number;
+    setComponentMetadata(metadata: Record<string, any>): void;
     /**
-     * Log an LLM API call
+     * Get component data
      */
-    log(entry: LLMUsageEntry): void;
+    getComponentData(): Record<string, any>;
     /**
-     * Log session summary (call at end of request)
+     * Calculate size of data in bytes
      */
-    logSessionSummary(requestContext?: string): void;
+    private getDataSizeInBytes;
     /**
-     * Reset session stats (call at start of new user request)
+     * Limit array data to maximum rows
      */
-    resetSession(): void;
+    private limitArrayData;
     /**
-     * Reset the log file for a new request (clears previous logs)
-     * Call this at the start of each USER_PROMPT_REQ
+     * Check if data exceeds size limit
      */
-    resetLogFile(requestContext?: string): void;
+    private exceedsSizeLimit;
     /**
-     * Get current session stats
+     * Process and limit data before storing
      */
-    getSessionStats(): {
-        totalCalls: number;
-        totalInputTokens: number;
-        totalOutputTokens: number;
-        totalCacheReadTokens: number;
-        totalCacheWriteTokens: number;
-        totalCostUSD: number;
-        totalDurationMs: number;
-    };
+    private processDataForStorage;
     /**
-     * Generate a unique request ID
+     * Set or update component data with size and row limits
      */
-    generateRequestId(): string;
+    setComponentData(data: Record<string, any>): void;
+    /**
+     * Set or update text response
+     */
+    setTextResponse(textResponse: string | null): void;
+    /**
+     * Get all actions (only if they are resolved, not if fetching)
+     */
+    getActions(): Action[] | null | Promise<Action[]>;
+    /**
+     * Get or fetch actions
+     * If actions don't exist or are a Promise, calls the generateFn and stores the promise
+     * If actions already exist, returns them
+     * @param generateFn - Async function to generate actions
+     * @returns Promise resolving to Action[]
+     */
+    getOrFetchActions(generateFn: () => Promise<Action[]>): Promise<Action[]>;
+    /**
+     * Set or replace all actions
+     */
+    setActions(actions: Action[]): void;
+    /**
+     * Add a single action (only if actions are resolved)
+     */
+    addAction(action: Action): void;
+    /**
+     * Add multiple actions (only if actions are resolved)
+     */
+    addActions(actions: Action[]): void;
+    /**
+     * Remove an action by ID (only if actions are resolved)
+     */
+    removeAction(actionId: string): boolean;
+    /**
+     * Clear all actions
+     */
+    clearActions(): void;
+    /**
+     * Get creation timestamp
+     */
+    getCreatedAt(): Date;
+    /**
+     * Convert UIBlock to JSON-serializable object
+     */
+    toJSON(): Record<string, any>;
 }
-declare const llmUsageLogger: LLMUsageLogger;
 
 /**
- * User Prompt Error Logger - Captures detailed errors for USER_PROMPT_REQ
- * Logs full error details including raw strings for parse failures
+ * Thread represents a conversation thread containing multiple UIBlocks
+ * Each UIBlock in a thread represents a user question and assistant response pair
  */
-declare class UserPromptErrorLogger {
-    private logStream;
-    private logPath;
-    private enabled;
-    private hasErrors;
-    constructor();
+declare class Thread {
+    private id;
+    private uiblocks;
+    private createdAt;
     /**
-     * Reset the error log file for a new request
+     * Creates a new Thread instance
+     * @param id - Optional custom ID, generates UUID if not provided
      */
-    resetLogFile(requestContext?: string): void;
+    constructor(id?: string);
     /**
-     * Log a JSON parse error with the raw string that failed
+     * Get the thread ID
      */
-    logJsonParseError(context: string, rawString: string, error: Error): void;
+    getId(): string;
     /**
-     * Log a general error with full details
+     * Add a UIBlock to the thread
      */
-    logError(context: string, error: Error | string, additionalData?: Record<string, any>): void;
+    addUIBlock(uiblock: UIBlock): void;
     /**
-     * Log a SQL query error with the full query
+     * Get a UIBlock by ID
      */
-    logSqlError(query: string, error: Error | string, params?: any[]): void;
+    getUIBlock(id: string): UIBlock | undefined;
     /**
-     * Log an LLM API error
+     * Get all UIBlocks in the thread
      */
-    logLlmError(provider: string, model: string, method: string, error: Error | string, requestData?: any): void;
+    getUIBlocks(): UIBlock[];
     /**
-     * Log tool execution error
+     * Get UIBlocks as a Map
      */
-    logToolError(toolName: string, toolInput: any, error: Error | string): void;
+    getUIBlocksMap(): Map<string, UIBlock>;
     /**
-     * Write final summary if there were errors
+     * Remove a UIBlock by ID
      */
-    writeSummary(): void;
+    removeUIBlock(id: string): boolean;
     /**
-     * Check if any errors were logged
+     * Check if UIBlock exists
      */
-    hadErrors(): boolean;
-    private write;
+    hasUIBlock(id: string): boolean;
+    /**
+     * Get number of UIBlocks in the thread
+     */
+    getUIBlockCount(): number;
+    /**
+     * Clear all UIBlocks from the thread
+     */
+    clear(): void;
+    /**
+     * Get creation timestamp
+     */
+    getCreatedAt(): Date;
+    /**
+     * Get conversation context from recent UIBlocks (excluding current one)
+     * Returns formatted string with previous questions and component summaries
+     * @param limit - Maximum number of previous UIBlocks to include (default: 5)
+     * @param currentUIBlockId - ID of current UIBlock to exclude from context (optional)
+     * @returns Formatted conversation history string
+     */
+    getConversationContext(limit?: number, currentUIBlockId?: string): string;
+    /**
+     * Convert Thread to JSON-serializable object
+     */
+    toJSON(): Record<string, any>;
 }
-declare const userPromptErrorLogger: UserPromptErrorLogger;
 
 /**
- * BM25L Reranker for hybrid semantic search
- *
- * BM25L is an improved variant of BM25 that provides better handling of
- * long documents and term frequency saturation. This implementation is
- * designed to rerank semantic search results from ChromaDB.
- *
- * The hybrid approach combines:
- * 1. Semantic similarity from ChromaDB embeddings (dense vectors)
- * 2. Lexical matching from BM25L (sparse, keyword-based)
- *
- * This addresses the weakness of pure semantic search which may miss
- * exact keyword matches that are important for user intent.
- */
-interface BM25LOptions {
-    /** Term frequency saturation parameter (default: 1.5) */
-    k1?: number;
-    /** Length normalization parameter (default: 0.75) */
-    b?: number;
-    /** Lower-bound adjustment from BM25L paper (default: 0.5) */
-    delta?: number;
-}
-interface RerankedResult<T> {
-    item: T;
-    originalIndex: number;
-    semanticScore: number;
-    bm25Score: number;
-    hybridScore: number;
-}
-interface HybridSearchOptions extends BM25LOptions {
-    /** Weight for semantic score (0-1, default: 0.7) */
-    semanticWeight?: number;
-    /** Weight for BM25 score (0-1, default: 0.3) */
-    bm25Weight?: number;
-    /** Minimum hybrid score threshold (0-1, default: 0) */
-    minScore?: number;
-}
-/**
- * BM25L implementation for lexical scoring
+ * ThreadManager manages all threads globally
+ * Provides methods to create, retrieve, and delete threads.
+ * Includes automatic cleanup to prevent unbounded memory growth.
  */
-declare class BM25L {
-    private k1;
-    private b;
-    private delta;
-    private documents;
-    private docLengths;
-    private avgDocLength;
-    private termDocFreq;
+declare class ThreadManager {
+    private static instance;
+    private threads;
+    private cleanupInterval;
+    private readonly threadTtlMs;
+    private constructor();
     /**
-     * @param documents - Array of raw documents (strings)
-     * @param opts - Optional BM25L parameters
+     * Periodically remove threads older than 7 days.
+     * Runs every hour to avoid frequent iteration over the map.
      */
-    constructor(documents?: string[], opts?: BM25LOptions);
+    private startCleanup;
     /**
-     * Tokenize text into lowercase alphanumeric tokens
+     * Get singleton instance of ThreadManager
      */
-    tokenize(text: string): string[];
+    static getInstance(): ThreadManager;
     /**
-     * Compute IDF (Inverse Document Frequency) with smoothing
+     * Create a new thread
+     * @param id - Optional custom ID, generates UUID if not provided
+     * @returns The created Thread instance
      */
-    private idf;
+    createThread(id?: string): Thread;
     /**
-     * Compute BM25L score for a single document
+     * Get a thread by ID
      */
-    score(query: string, docIndex: number): number;
+    getThread(id: string): Thread | undefined;
     /**
-     * Search and rank all documents
+     * Get all threads
      */
-    search(query: string): Array<{
-        index: number;
-        score: number;
-    }>;
-}
-/**
- * Hybrid reranker that combines semantic and BM25L scores
- *
- * @param query - The search query
- * @param items - Array of items to rerank
- * @param getDocument - Function to extract document text from an item
- * @param getSemanticScore - Function to extract semantic similarity score from an item
- * @param options - Hybrid search options
- * @returns Reranked items with hybrid scores
- */
-declare function hybridRerank<T>(query: string, items: T[], getDocument: (item: T) => string, getSemanticScore: (item: T) => number, options?: HybridSearchOptions): RerankedResult<T>[];
-/**
- * Simple reranking function for ChromaDB results
- *
- * This is a convenience wrapper for reranking ChromaDB query results
- * that follow the standard { ids, documents, metadatas, distances } format.
- *
- * @param query - The search query
- * @param chromaResults - ChromaDB query results
- * @param options - Hybrid search options
- * @returns Reranked results with hybrid scores
- */
-declare function rerankChromaResults(query: string, chromaResults: {
-    ids: string[][];
-    documents: (string | null)[][];
-    metadatas: Record<string, any>[][];
-    distances: number[][];
-}, options?: HybridSearchOptions): Array<{
-    id: string;
-    document: string | null;
-    metadata: Record<string, any>;
-    distance: number;
-    semanticScore: number;
-    bm25Score: number;
-    hybridScore: number;
-}>;
-/**
- * Rerank conversation search results specifically
- *
- * This function is designed to work with the conversation-history.search collection
- * where we need to fetch more results initially and then rerank them.
- *
- * @param query - The user's search query
- * @param results - Array of conversation search results from ChromaDB
- * @param options - Hybrid search options
- * @returns Reranked results sorted by hybrid score
- */
-declare function rerankConversationResults<T extends {
-    userPrompt?: string;
-    similarity?: number;
-}>(query: string, results: T[], options?: HybridSearchOptions): Array<T & {
-    hybridScore: number;
-    bm25Score: number;
-}>;
-
-/**
- * QueryExecutionService - Handles all query execution, validation, and retry logic
- * Extracted from BaseLLM for better separation of concerns
- */
-
-/**
- * Context for component when requesting query fix
- */
-interface ComponentContext {
-    name: string;
-    type: string;
-    title?: string;
-}
-/**
- * Result of query validation
- */
-interface QueryValidationResult {
-    component: Component | null;
-    queryKey: string;
-    result: any;
-    validated: boolean;
-}
-/**
- * Result of batch query validation
- */
-interface BatchValidationResult {
-    components: Component[];
-    queryResults: Map<string, any>;
-}
-/**
- * Configuration for QueryExecutionService
- */
-interface QueryExecutionServiceConfig {
-    defaultLimit: number;
-    getModelForTask: (taskType: 'simple' | 'complex') => string;
-    getApiKey: (apiKey?: string) => string | undefined;
-    providerName: string;
-}
-/**
- * QueryExecutionService handles all query-related operations
- */
-declare class QueryExecutionService {
-    private config;
-    constructor(config: QueryExecutionServiceConfig);
+    getAllThreads(): Thread[];
     /**
-     * Get the cache key for a query
-     * This ensures the cache key matches what the frontend will send
+     * Get threads as a Map
      */
-    getQueryCacheKey(query: any): string;
+    getThreadsMap(): Map<string, Thread>;
     /**
-     * Execute a query against the database
-     * @param query - The SQL query to execute (string or object with sql/values)
-     * @param collections - Collections object containing database execute function
-     * @returns Object with result data and cache key
+     * Delete a thread by ID
      */
-    executeQuery(query: any, collections: any): Promise<{
-        result: any;
-        cacheKey: string;
-    }>;
+    deleteThread(id: string): boolean;
     /**
-     * Request the LLM to fix a failed SQL query
-     * @param failedQuery - The query that failed execution
-     * @param errorMessage - The error message from the failed execution
-     * @param componentContext - Context about the component
-     * @param apiKey - Optional API key
-     * @returns Fixed query string
+     * Check if thread exists
      */
-    requestQueryFix(failedQuery: string, errorMessage: string, componentContext: ComponentContext, apiKey?: string): Promise<string>;
+    hasThread(id: string): boolean;
     /**
-     * Validate a single component's query with retry logic
-     * @param component - The component to validate
-     * @param collections - Collections object containing database execute function
-     * @param apiKey - Optional API key for LLM calls
-     * @returns Validation result with component, query key, and result
+     * Get number of threads
      */
-    validateSingleQuery(component: Component, collections: any, apiKey?: string): Promise<QueryValidationResult>;
+    getThreadCount(): number;
     /**
-     * Validate multiple component queries in parallel
-     * @param components - Array of components with potential queries
-     * @param collections - Collections object containing database execute function
-     * @param apiKey - Optional API key for LLM calls
-     * @returns Object with validated components and query results map
+     * Clear all threads
      */
-    validateComponentQueries(components: Component[], collections: any, apiKey?: string): Promise<BatchValidationResult>;
+    clearAll(): void;
+    /**
+     * Find a UIBlock by ID across all threads
+     * @param uiBlockId - The UIBlock ID to search for
+     * @returns Object with thread and uiBlock if found, undefined otherwise
+     */
+    findUIBlockById(uiBlockId: string): {
+        thread: Thread;
+        uiBlock: UIBlock;
+    } | undefined;
+    /**
+     * Convert all threads to JSON-serializable object
+     */
+    toJSON(): Record<string, any>;
 }
 
 /**
- * StreamBuffer - Buffered streaming utility for smoother text delivery
- * Batches small chunks together and flushes at regular intervals
- */
-type StreamCallback = (chunk: string) => void;
-/**
- * StreamBuffer class for managing buffered streaming output
- * Provides smooth text delivery by batching small chunks
+ * CleanupService handles cleanup of old threads and UIBlocks
+ * to prevent memory bloat and maintain optimal performance
  */
-declare class StreamBuffer {
-    private buffer;
-    private flushTimer;
-    private callback;
-    private fullText;
-    constructor(callback?: StreamCallback);
+declare class CleanupService {
+    private static instance;
+    private cleanupInterval;
+    private constructor();
     /**
-     * Check if the buffer has a callback configured
+     * Get singleton instance of CleanupService
      */
-    hasCallback(): boolean;
+    static getInstance(): CleanupService;
     /**
-     * Get all text that has been written (including already flushed)
+     * Clean up old threads based on retention period
+     * @param retentionDays - Number of days to keep threads (defaults to config)
+     * @returns Number of threads deleted
      */
-    getFullText(): string;
+    cleanupOldThreads(retentionDays?: number): number;
     /**
-     * Write a chunk to the buffer
-     * Large chunks or chunks with newlines are flushed immediately
-     * Small chunks are batched and flushed after a short interval
-     *
-     * @param chunk - Text chunk to write
+     * Clean up old UIBlocks within threads based on retention period
+     * @param retentionDays - Number of days to keep UIBlocks (defaults to config)
+     * @returns Object with number of UIBlocks deleted per thread
      */
-    write(chunk: string): void;
+    cleanupOldUIBlocks(retentionDays?: number): {
+        [threadId: string]: number;
+    };
     /**
-     * Flush the buffer immediately
-     * Call this before tool execution or other operations that need clean output
+     * Clear all component data from UIBlocks to free memory
+     * Keeps metadata but removes the actual data
+     * @param retentionDays - Number of days to keep full data (defaults to config)
+     * @returns Number of UIBlocks whose data was cleared
      */
-    flush(): void;
+    clearOldUIBlockData(retentionDays?: number): number;
     /**
-     * Internal flush implementation
+     * Run full cleanup (threads, UIBlocks, and data)
+     * @returns Cleanup statistics
      */
-    private flushNow;
+    runFullCleanup(): {
+        threadsDeleted: number;
+        uiblocksDeleted: {
+            [threadId: string]: number;
+        };
+        dataCleared: number;
+    };
     /**
-     * Clean up resources
-     * Call this when done with the buffer
+     * Start automatic cleanup at regular intervals
+     * @param intervalHours - Hours between cleanup runs (default: 24)
      */
-    dispose(): void;
+    startAutoCleanup(intervalHours?: number): void;
+    /**
+     * Stop automatic cleanup
+     */
+    stopAutoCleanup(): void;
+    /**
+     * Check if auto cleanup is running
+     */
+    isAutoCleanupRunning(): boolean;
+    /**
+     * Get current memory usage statistics
+     */
+    getMemoryStats(): {
+        threadCount: number;
+        totalUIBlocks: number;
+        avgUIBlocksPerThread: number;
+    };
 }
 
 /**
- * ToolExecutorService - Handles execution of SQL queries and external tools
- * Extracted from BaseLLM.generateTextResponse for better separation of concerns
- */
-
-/**
- * External tool definition
+ * Configuration for data storage limits in UIBlocks
  */
-interface ExternalTool {
-    id: string;
-    name: string;
-    description?: string;
-    /** Tool type: "source" = routed through SourceAgent, "direct" = called directly by MainAgent */
-    toolType?: 'source' | 'direct';
-    /** Full untruncated schema for source agent (all columns visible) */
-    fullSchema?: string;
-    /** Schema size tier: small (≤50 tables), medium (51-200), large (201-500), very_large (500+) */
-    schemaTier?: string;
-    /** Schema search function for very_large tier — keyword search over entities */
-    schemaSearchFn?: (keywords: string[]) => string;
-    fn: (input: any) => Promise<any>;
-    limit?: number;
-    outputSchema?: any;
-    executionType?: 'immediate' | 'deferred';
-    userProvidedData?: any;
-    params?: Record<string, any>;
-}
-/**
- * Executed tool tracking info
- */
-interface ExecutedToolInfo {
-    id: string;
-    name: string;
-    params: any;
-    result: {
-        _totalRecords: number;
-        _recordsShown: number;
-        _metadata?: any;
-        _sampleData: any[];
-    };
-    outputSchema?: any;
-    sourceSchema?: string;
-    sourceType?: string;
-}
+declare const STORAGE_CONFIG: {
+    /**
+     * Maximum number of rows to store in UIBlock data
+     */
+    MAX_ROWS_PER_BLOCK: number;
+    /**
+     * Maximum size in bytes per UIBlock (500KB - reduced to save memory)
+     */
+    MAX_SIZE_PER_BLOCK_BYTES: number;
+    /**
+     * Number of days to keep threads before cleanup
+     * Note: This is for in-memory storage. Conversations are also persisted to database.
+     */
+    THREAD_RETENTION_DAYS: number;
+    /**
+     * Number of days to keep UIBlocks before cleanup
+     * Note: This is for in-memory storage. Data is also persisted to database.
+     */
+    UIBLOCK_RETENTION_DAYS: number;
+};
 
 /**
- * Task types for model selection
- * - 'complex': Text generation, component matching, parameter adaptation (uses best model in balanced mode)
- * - 'simple': Classification, action generation (uses fast model in balanced mode)
+ * Configuration for conversation context and history management
  */
-type TaskType = 'complex' | 'simple';
-interface BaseLLMConfig {
-    model?: string;
-    fastModel?: string;
-    defaultLimit?: number;
-    apiKey?: string;
+declare const CONTEXT_CONFIG: {
     /**
-     * Model selection strategy:
-     * - 'best': Use best model for all tasks (highest quality, higher cost)
-     * - 'fast': Use fast model for all tasks (lower quality, lower cost)
-     * - 'balanced': Use best model for complex tasks, fast model for simple tasks (default)
+     * Maximum number of previous UIBlocks to include as conversation context
+     * Set to 0 to disable conversation history
+     * Higher values provide more context but may increase token usage
      */
-    modelStrategy?: ModelStrategy;
-    conversationSimilarityThreshold?: number;
-}
+    MAX_CONVERSATION_CONTEXT_BLOCKS: number;
+};
+
 /**
- * BaseLLM abstract class for AI-powered component generation and matching
- * Provides common functionality for all LLM providers
+ * LLM Usage Logger - Tracks token usage, costs, and timing for all LLM API calls
  */
-declare abstract class BaseLLM {
-    protected model: string;
-    protected fastModel: string;
-    protected defaultLimit: number;
-    protected apiKey?: string;
-    protected modelStrategy: ModelStrategy;
-    protected conversationSimilarityThreshold: number;
-    protected queryService: QueryExecutionService;
-    constructor(config?: BaseLLMConfig);
-    /**
-     * Get the appropriate model based on task type and model strategy
-     * @param taskType - 'complex' for text generation/matching, 'simple' for classification/actions
-     * @returns The model string to use for this task
-     */
-    protected getModelForTask(taskType: TaskType): string;
-    /**
-     * Set the model strategy at runtime
-     * @param strategy - 'best', 'fast', or 'balanced'
-     */
-    setModelStrategy(strategy: ModelStrategy): void;
+interface LLMUsageEntry {
+    timestamp: string;
+    requestId: string;
+    provider: string;
+    model: string;
+    method: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    totalTokens: number;
+    costUSD: number;
+    durationMs: number;
+    toolCalls?: number;
+    success: boolean;
+    error?: string;
+}
+declare class LLMUsageLogger {
+    private logStream;
+    private logPath;
+    private enabled;
+    private sessionStats;
+    constructor();
+    private initLogStream;
+    private writeHeader;
     /**
-     * Get the current model strategy
-     * @returns The current model strategy
+     * Calculate cost based on token usage and model
      */
-    getModelStrategy(): ModelStrategy;
+    calculateCost(model: string, inputTokens: number, outputTokens: number, cacheReadTokens?: number, cacheWriteTokens?: number): number;
     /**
-     * Set the conversation similarity threshold at runtime
-     * @param threshold - Value between 0 and 1 (e.g., 0.8 = 80% similarity required)
+     * Log an LLM API call
      */
-    setConversationSimilarityThreshold(threshold: number): void;
+    log(entry: LLMUsageEntry): void;
     /**
-     * Get the current conversation similarity threshold
-     * @returns The current threshold value
+     * Log session summary (call at end of request)
      */
-    getConversationSimilarityThreshold(): number;
+    logSessionSummary(requestContext?: string): void;
     /**
-     * Get the default model for this provider (used for complex tasks like text generation)
+     * Reset session stats (call at start of new user request)
      */
-    protected abstract getDefaultModel(): string;
+    resetSession(): void;
     /**
-     * Get the default fast model for this provider (used for simple tasks: classification, matching, actions)
-     * Should return a cheaper/faster model like Haiku for Anthropic
+     * Reset the log file for a new request (clears previous logs)
+     * Call this at the start of each USER_PROMPT_REQ
      */
-    protected abstract getDefaultFastModel(): string;
+    resetLogFile(requestContext?: string): void;
     /**
-     * Get the default API key from environment
+     * Get current session stats
      */
-    protected abstract getDefaultApiKey(): string | undefined;
+    getSessionStats(): {
+        totalCalls: number;
+        totalInputTokens: number;
+        totalOutputTokens: number;
+        totalCacheReadTokens: number;
+        totalCacheWriteTokens: number;
+        totalCostUSD: number;
+        totalDurationMs: number;
+    };
     /**
-     * Get the provider name (for logging)
+     * Generate a unique request ID
      */
-    protected abstract getProviderName(): string;
+    generateRequestId(): string;
+}
+declare const llmUsageLogger: LLMUsageLogger;
+
+/**
+ * User Prompt Error Logger - Captures detailed errors for USER_PROMPT_REQ
+ * Logs full error details including raw strings for parse failures
+ */
+declare class UserPromptErrorLogger {
+    private logStream;
+    private logPath;
+    private enabled;
+    private hasErrors;
+    constructor();
     /**
-     * Get the API key (from instance, parameter, or environment)
+     * Reset the error log file for a new request
      */
-    protected getApiKey(apiKey?: string): string | undefined;
+    resetLogFile(requestContext?: string): void;
     /**
-     * Check if a component contains a Form (data_modification component)
-     * Forms have hardcoded defaultValues that become stale when cached
-     * This checks both single Form components and Forms inside MultiComponentContainer
+     * Log a JSON parse error with the raw string that failed
      */
-    protected containsFormComponent(component: any): boolean;
+    logJsonParseError(context: string, rawString: string, error: Error): void;
     /**
-     * Match components from text response suggestions and generate follow-up questions
-     * Takes a text response with component suggestions (c1:type format) and matches with available components
-     * Also generates title, description, and intelligent follow-up questions (actions) based on the analysis
-     * All components are placed in a default MultiComponentContainer layout
-     * @param analysisContent - The text response containing component suggestions
-     * @param components - List of available components
-     * @param apiKey - Optional API key
-     * @param componentStreamCallback - Optional callback to stream primary KPI component as soon as it's identified
-     * @returns Object containing matched components, layout title/description, and follow-up actions
+     * Log a general error with full details
      */
-    matchComponentsFromAnalysis(analysisContent: string, components: Component[], userPrompt: string, apiKey?: string, componentStreamCallback?: (component: Component) => void, deferredTools?: any[], executedTools?: any[], collections?: any, userId?: string): Promise<{
-        components: Component[];
-        layoutTitle: string;
-        layoutDescription: string;
-        actions: Action[];
-    }>;
+    logError(context: string, error: Error | string, additionalData?: Record<string, any>): void;
     /**
-     * Classify user question into category and detect external tools needed
-     * Determines if question is for data analysis, requires external tools, or needs text response
+     * Log a SQL query error with the full query
      */
-    classifyQuestionCategory(userPrompt: string, apiKey?: string, conversationHistory?: string, externalTools?: any[]): Promise<{
-        category: 'data_analysis' | 'data_modification' | 'general';
-        externalTools: Array<{
-            type: string;
-            name: string;
-            description: string;
-            parameters: Record<string, any>;
-        }>;
-        dataAnalysisType?: 'visualization' | 'calculation' | 'comparison' | 'trend';
-        reasoning: string;
-        confidence: number;
-    }>;
+    logSqlError(query: string, error: Error | string, params?: any[]): void;
     /**
-     * Adapt UI block parameters based on current user question
-     * Takes a matched UI block from semantic search and modifies its props to answer the new question
-     * Also adapts the cached text response to match the new question
+     * Log an LLM API error
      */
-    adaptUIBlockParameters(currentUserPrompt: string, originalUserPrompt: string, matchedUIBlock: any, apiKey?: string, cachedTextResponse?: string): Promise<{
-        success: boolean;
-        adaptedComponent?: Component;
-        adaptedTextResponse?: string;
-        parametersChanged?: Array<{
-            field: string;
-            reason: string;
-        }>;
-        explanation: string;
-    }>;
+    logLlmError(provider: string, model: string, method: string, error: Error | string, requestData?: any): void;
     /**
-     * Generate text-based response for user question
-     * This provides conversational text responses instead of component generation
-     * Supports tool calling for query execution with automatic retry on errors (max 3 attempts)
-     * After generating text response, if components are provided, matches suggested components
+     * Log tool execution error
      */
-    generateTextResponse(userPrompt: string, apiKey?: string, conversationHistory?: string, streamCallback?: (chunk: string) => void, collections?: any, components?: Component[], externalTools?: any[], category?: 'data_analysis' | 'data_modification' | 'general', userId?: string): Promise<T_RESPONSE>;
+    logToolError(toolName: string, toolInput: any, error: Error | string): void;
     /**
-     * Main orchestration function with semantic search and multi-step classification
-     * NEW FLOW (Recommended):
-     * 1. Semantic search: Check previous conversations (>60% match)
-     *    - If match found → Adapt UI block parameters and return
-     * 2. Category classification: Determine if data_analysis, requires_external_tools, or text_response
-     * 3. Route appropriately based on category and response mode
+     * Write final summary if there were errors
      */
-    handleUserRequest(userPrompt: string, components: Component[], apiKey?: string, conversationHistory?: string, responseMode?: 'component' | 'text', streamCallback?: (chunk: string) => void, collections?: any, externalTools?: any[], userId?: string): Promise<T_RESPONSE>;
+    writeSummary(): void;
     /**
-     * Generate next questions that the user might ask based on the original prompt and generated component
-     * This helps provide intelligent suggestions for follow-up queries
-     * For general/conversational questions without components, pass textResponse instead
+     * Check if any errors were logged
      */
-    generateNextQuestions(originalUserPrompt: string, component?: Component | null, componentData?: Record<string, unknown>, apiKey?: string, conversationHistory?: string, textResponse?: string): Promise<string[]>;
+    hadErrors(): boolean;
+    private write;
 }
+declare const userPromptErrorLogger: UserPromptErrorLogger;
 
-interface AnthropicLLMConfig extends BaseLLMConfig {
-}
 /**
- * AnthropicLLM class for handling AI-powered component generation and matching using Anthropic Claude
+ * BM25L Reranker for hybrid semantic search
+ *
+ * BM25L is an improved variant of BM25 that provides better handling of
+ * long documents and term frequency saturation. This implementation is
+ * designed to rerank semantic search results from ChromaDB.
+ *
+ * The hybrid approach combines:
+ * 1. Semantic similarity from ChromaDB embeddings (dense vectors)
+ * 2. Lexical matching from BM25L (sparse, keyword-based)
+ *
+ * This addresses the weakness of pure semantic search which may miss
+ * exact keyword matches that are important for user intent.
  */
-declare class AnthropicLLM extends BaseLLM {
-    constructor(config?: AnthropicLLMConfig);
-    protected getDefaultModel(): string;
-    protected getDefaultFastModel(): string;
-    protected getDefaultApiKey(): string | undefined;
-    protected getProviderName(): string;
+interface BM25LOptions {
+    /** Term frequency saturation parameter (default: 1.5) */
+    k1?: number;
+    /** Length normalization parameter (default: 0.75) */
+    b?: number;
+    /** Lower-bound adjustment from BM25L paper (default: 0.5) */
+    delta?: number;
 }
-declare const anthropicLLM: AnthropicLLM;
-
-interface GroqLLMConfig extends BaseLLMConfig {
+interface RerankedResult<T> {
+    item: T;
+    originalIndex: number;
+    semanticScore: number;
+    bm25Score: number;
+    hybridScore: number;
+}
+interface HybridSearchOptions extends BM25LOptions {
+    /** Weight for semantic score (0-1, default: 0.7) */
+    semanticWeight?: number;
+    /** Weight for BM25 score (0-1, default: 0.3) */
+    bm25Weight?: number;
+    /** Minimum hybrid score threshold (0-1, default: 0) */
+    minScore?: number;
 }
 /**
- * GroqLLM class for handling AI-powered component generation and matching using Groq
+ * BM25L implementation for lexical scoring
  */
-declare class GroqLLM extends BaseLLM {
-    constructor(config?: GroqLLMConfig);
-    protected getDefaultModel(): string;
-    protected getDefaultFastModel(): string;
-    protected getDefaultApiKey(): string | undefined;
-    protected getProviderName(): string;
+declare class BM25L {
+    private k1;
+    private b;
+    private delta;
+    private documents;
+    private docLengths;
+    private avgDocLength;
+    private termDocFreq;
+    /**
+     * @param documents - Array of raw documents (strings)
+     * @param opts - Optional BM25L parameters
+     */
+    constructor(documents?: string[], opts?: BM25LOptions);
+    /**
+     * Tokenize text into lowercase alphanumeric tokens
+     */
+    tokenize(text: string): string[];
+    /**
+     * Compute IDF (Inverse Document Frequency) with smoothing
+     */
+    private idf;
+    /**
+     * Compute BM25L score for a single document
+     */
+    score(query: string, docIndex: number): number;
+    /**
+     * Search and rank all documents
+     */
+    search(query: string): Array<{
+        index: number;
+        score: number;
+    }>;
 }
-declare const groqLLM: GroqLLM;
+/**
+ * Hybrid reranker that combines semantic and BM25L scores
+ *
+ * @param query - The search query
+ * @param items - Array of items to rerank
+ * @param getDocument - Function to extract document text from an item
+ * @param getSemanticScore - Function to extract semantic similarity score from an item
+ * @param options - Hybrid search options
+ * @returns Reranked items with hybrid scores
+ */
+declare function hybridRerank<T>(query: string, items: T[], getDocument: (item: T) => string, getSemanticScore: (item: T) => number, options?: HybridSearchOptions): RerankedResult<T>[];
+/**
+ * Simple reranking function for ChromaDB results
+ *
+ * This is a convenience wrapper for reranking ChromaDB query results
+ * that follow the standard { ids, documents, metadatas, distances } format.
+ *
+ * @param query - The search query
+ * @param chromaResults - ChromaDB query results
+ * @param options - Hybrid search options
+ * @returns Reranked results with hybrid scores
+ */
+declare function rerankChromaResults(query: string, chromaResults: {
+    ids: string[][];
+    documents: (string | null)[][];
+    metadatas: Record<string, any>[][];
+    distances: number[][];
+}, options?: HybridSearchOptions): Array<{
+    id: string;
+    document: string | null;
+    metadata: Record<string, any>;
+    distance: number;
+    semanticScore: number;
+    bm25Score: number;
+    hybridScore: number;
+}>;
+/**
+ * Rerank conversation search results specifically
+ *
+ * This function is designed to work with the conversation-history.search collection
+ * where we need to fetch more results initially and then rerank them.
+ *
+ * @param query - The user's search query
+ * @param results - Array of conversation search results from ChromaDB
+ * @param options - Hybrid search options
+ * @returns Reranked results sorted by hybrid score
+ */
+declare function rerankConversationResults<T extends {
+    userPrompt?: string;
+    similarity?: number;
+}>(query: string, results: T[], options?: HybridSearchOptions): Array<T & {
+    hybridScore: number;
+    bm25Score: number;
+}>;
 
-interface GeminiLLMConfig extends BaseLLMConfig {
+/**
+ * QueryExecutionService - Handles all query execution, validation, and retry logic
+ * Extracted from BaseLLM for better separation of concerns
+ */
+
+/**
+ * Context for component when requesting query fix
+ */
+interface ComponentContext {
+    name: string;
+    type: string;
+    title?: string;
 }
 /**
- * GeminiLLM class for handling AI-powered component generation and matching using Google Gemini
+ * Result of query validation
  */
-declare class GeminiLLM extends BaseLLM {
-    constructor(config?: GeminiLLMConfig);
-    protected getDefaultModel(): string;
-    protected getDefaultFastModel(): string;
-    protected getDefaultApiKey(): string | undefined;
-    protected getProviderName(): string;
+interface QueryValidationResult {
+    component: Component | null;
+    queryKey: string;
+    result: any;
+    validated: boolean;
 }
-declare const geminiLLM: GeminiLLM;
-
-interface OpenAILLMConfig extends BaseLLMConfig {
+/**
+ * Result of batch query validation
+ */
+interface BatchValidationResult {
+    components: Component[];
+    queryResults: Map<string, any>;
 }
 /**
- * OpenAILLM class for handling AI-powered component generation and matching using OpenAI GPT models
+ * Configuration for QueryExecutionService
  */
-declare class OpenAILLM extends BaseLLM {
-    constructor(config?: OpenAILLMConfig);
-    protected getDefaultModel(): string;
-    protected getDefaultFastModel(): string;
-    protected getDefaultApiKey(): string | undefined;
-    protected getProviderName(): string;
+interface QueryExecutionServiceConfig {
+    defaultLimit: number;
+    getModelForTask: (taskType: 'simple' | 'complex') => string;
+    getApiKey: (apiKey?: string) => string | undefined;
+    providerName: string;
 }
-declare const openaiLLM: OpenAILLM;
-
 /**
- * Query Cache — Two mechanisms:
- *
- * 1. `cache` (query string → result data) — TTL-based with max size, for avoiding re-execution
- *    of recently validated queries. LRU eviction when max size exceeded.
- *
- * 2. Encrypted queryId tokens — SQL is encrypted into the queryId itself (self-contained).
- *    No server-side storage needed for SQL mappings. The token is decrypted on each request.
- *    This eliminates the unbounded queryIdCache that previously grew forever and caused
- *    memory bloat (hundreds of MBs after thousands of queries).
- *
- *    Result data can still be cached temporarily via the data cache (mechanism 1).
+ * QueryExecutionService handles all query-related operations
  */
-declare class QueryCache {
-    private cache;
-    private ttlMs;
-    private maxCacheSize;
-    private cleanupInterval;
-    private readonly algorithm;
-    private encryptionKey;
-    constructor();
-    /**
-     * Set the cache TTL (Time To Live)
-     * @param minutes - TTL in minutes (default: 10)
-     */
-    setTTL(minutes: number): void;
-    /**
-     * Get the current TTL in minutes
-     */
-    getTTL(): number;
+declare class QueryExecutionService {
+    private config;
+    constructor(config: QueryExecutionServiceConfig);
     /**
-     * Store query result in data cache
+     * Get the cache key for a query
+     * This ensures the cache key matches what the frontend will send
      */
-    set(query: string, data: any): void;
+    getQueryCacheKey(query: any): string;
     /**
-     * Get cached result if exists and not expired
+     * Execute a query against the database
+     * @param query - The SQL query to execute (string or object with sql/values)
+     * @param collections - Collections object containing database execute function
+     * @returns Object with result data and cache key
      */
-    get(query: string): any | null;
+    executeQuery(query: any, collections: any): Promise<{
+        result: any;
+        cacheKey: string;
+    }>;
     /**
-     * Check if query exists in cache (not expired)
+     * Request the LLM to fix a failed SQL query
+     * @param failedQuery - The query that failed execution
+     * @param errorMessage - The error message from the failed execution
+     * @param componentContext - Context about the component
+     * @param apiKey - Optional API key
+     * @returns Fixed query string
      */
-    has(query: string): boolean;
+    requestQueryFix(failedQuery: string, errorMessage: string, componentContext: ComponentContext, apiKey?: string): Promise<string>;
     /**
-     * Remove a specific query from cache
+     * Validate a single component's query with retry logic
+     * @param component - The component to validate
+     * @param collections - Collections object containing database execute function
+     * @param apiKey - Optional API key for LLM calls
+     * @returns Validation result with component, query key, and result
      */
-    delete(query: string): void;
+    validateSingleQuery(component: Component, collections: any, apiKey?: string): Promise<QueryValidationResult>;
     /**
-     * Clear all cached entries
+     * Validate multiple component queries in parallel
+     * @param components - Array of components with potential queries
+     * @param collections - Collections object containing database execute function
+     * @param apiKey - Optional API key for LLM calls
+     * @returns Object with validated components and query results map
      */
-    clear(): void;
-    /**
-     * Get cache statistics
-     */
-    getStats(): {
-        size: number;
-        queryIdCount: number;
-        oldestEntryAge: number | null;
-    };
-    /**
-     * Start periodic cleanup of expired data cache entries.
-     */
-    private startCleanup;
-    /**
-     * Encrypt a payload into a self-contained token.
-     */
-    private encrypt;
-    /**
-     * Decrypt a token back to the original payload.
-     */
-    private decrypt;
-    /**
-     * Store a query by generating an encrypted token as queryId.
-     * The SQL is encrypted INTO the token — nothing stored in memory.
-     * If data is provided, it's cached temporarily in the data cache.
-     */
-    storeQuery(query: any, data?: any): string;
+    validateComponentQueries(components: Component[], collections: any, apiKey?: string): Promise<BatchValidationResult>;
+}
+
+/**
+ * Task types for model selection
+ * - 'complex': Text generation, component matching, parameter adaptation (uses best model in balanced mode)
+ * - 'simple': Classification, action generation (uses fast model in balanced mode)
+ */
+type TaskType = 'complex' | 'simple';
+interface BaseLLMConfig {
+    model?: string;
+    fastModel?: string;
+    defaultLimit?: number;
+    apiKey?: string;
     /**
-     * Get a stored query by decrypting its token.
-     * Returns the SQL + any cached result data.
+     * Model selection strategy:
+     * - 'best': Use best model for all tasks (highest quality, higher cost)
+     * - 'fast': Use fast model for all tasks (lower quality, lower cost)
+     * - 'balanced': Use best model for complex tasks, fast model for simple tasks (default)
      */
-    getQuery(queryId: string): {
-        query: any;
-        data: any;
-    } | null;
+    modelStrategy?: ModelStrategy;
+    conversationSimilarityThreshold?: number;
+}
+/**
+ * BaseLLM abstract class for AI-powered component generation and matching
+ * Provides common functionality for all LLM providers
+ */
+declare abstract class BaseLLM {
+    protected model: string;
+    protected fastModel: string;
+    protected defaultLimit: number;
+    protected apiKey?: string;
+    protected modelStrategy: ModelStrategy;
+    protected conversationSimilarityThreshold: number;
+    protected queryService: QueryExecutionService;
+    constructor(config?: BaseLLMConfig);
     /**
-     * Update cached data for a queryId token
+     * Get the appropriate model based on task type and model strategy
+     * @param taskType - 'complex' for text generation/matching, 'simple' for classification/actions
+     * @returns The model string to use for this task
      */
-    setQueryData(queryId: string, data: any): void;
+    protected getModelForTask(taskType: TaskType): string;
     /**
-     * Stop cleanup interval (for graceful shutdown)
+     * Set the model strategy at runtime
+     * @param strategy - 'best', 'fast', or 'balanced'
      */
-    destroy(): void;
-}
-declare const queryCache: QueryCache;
-
-/**
- * Manages conversation history scoped per user + dashboard.
- * Each user-dashboard pair has its own isolated history that expires after a configurable TTL.
- */
-declare class DashboardConversationHistory {
-    private histories;
-    private ttlMs;
-    private maxEntries;
-    private cleanupInterval;
-    constructor();
+    setModelStrategy(strategy: ModelStrategy): void;
     /**
-     * Set the TTL for dashboard histories
-     * @param minutes - TTL in minutes
+     * Get the current model strategy
+     * @returns The current model strategy
      */
-    setTTL(minutes: number): void;
+    getModelStrategy(): ModelStrategy;
     /**
-     * Set max entries per dashboard
+     * Set the conversation similarity threshold at runtime
+     * @param threshold - Value between 0 and 1 (e.g., 0.8 = 80% similarity required)
      */
-    setMaxEntries(max: number): void;
+    setConversationSimilarityThreshold(threshold: number): void;
     /**
-     * Add a conversation entry for a user's dashboard
+     * Get the current conversation similarity threshold
+     * @returns The current threshold value
      */
-    addEntry(dashboardId: string, userPrompt: string, componentSummary: string, userId?: string): void;
+    getConversationSimilarityThreshold(): number;
     /**
-     * Get formatted conversation history for a user's dashboard
+     * Get the default model for this provider (used for complex tasks like text generation)
      */
-    getHistory(dashboardId: string, userId?: string): string;
+    protected abstract getDefaultModel(): string;
     /**
-     * Clear history for a specific user's dashboard
+     * Get the default fast model for this provider (used for simple tasks: classification, matching, actions)
+     * Should return a cheaper/faster model like Haiku for Anthropic
      */
-    clearDashboard(dashboardId: string, userId?: string): void;
+    protected abstract getDefaultFastModel(): string;
     /**
-     * Clear all dashboard histories
+     * Get the default API key from environment
      */
-    clearAll(): void;
+    protected abstract getDefaultApiKey(): string | undefined;
     /**
-     * Start periodic cleanup of expired histories
+     * Get the provider name (for logging)
      */
-    private startCleanup;
+    protected abstract getProviderName(): string;
     /**
-     * Stop cleanup interval (for graceful shutdown)
+     * Get the API key (from instance, parameter, or environment)
      */
-    destroy(): void;
-}
-declare const dashboardConversationHistory: DashboardConversationHistory;
-
-/**
- * Multi-Agent Architecture Types
- *
- * Defines interfaces for the hierarchical agent system:
- * - Main Agent: ONE LLM.streamWithTools() call with source agent tools
- * - Source Agents: independent agents that query individual data sources
- *
- * The main agent sees only source summaries. When it calls a source tool,
- * the SourceAgent runs independently (own LLM, own retries) and returns clean data.
- */
-
-/**
- * Per-entity detail: name, row count, and column names.
- * Gives the main agent enough context to route to the right source.
- */
-interface EntityDetail {
-    /** Entity name (table, sheet, endpoint) */
-    name: string;
-    /** Approximate row count */
-    rowCount?: number;
-    /** Column/field names */
-    columns: string[];
-}
-/**
- * Representation of a data source for the main agent.
- * Contains entity names WITH column names so the LLM can route accurately.
- */
-interface SourceSummary {
-    /** Source ID (matches tool ID prefix) */
-    id: string;
-    /** Human-readable source name */
-    name: string;
-    /** Source type: postgres, excel, rest_api, etc. */
-    type: string;
-    /** Brief description of what data this source contains */
-    description: string;
-    /** Detailed entity info with column names for routing */
-    entityDetails: EntityDetail[];
-    /** The tool ID associated with this source */
-    toolId: string;
-}
-/**
- * What a source agent returns after querying its data source.
- * The main agent uses this to analyze and compose the final response.
- */
-interface SourceAgentResult {
-    /** Source ID */
-    sourceId: string;
-    /** Source name */
-    sourceName: string;
-    /** Whether the query succeeded */
-    success: boolean;
-    /** Result data rows */
-    data: any[];
-    /** Metadata about the query execution */
-    metadata: SourceAgentMetadata;
-    /** Tool execution info for the last successful query (backward compat) */
-    executedTool: ExecutedToolInfo;
-    /** All successful tool executions (primary + follow-up queries) */
-    allExecutedTools?: ExecutedToolInfo[];
-    /** Error message if failed */
-    error?: string;
-}
-interface SourceAgentMetadata {
-    /** Total rows that matched the query (before limit) */
-    totalRowsMatched: number;
-    /** Rows actually returned (after limit) */
-    rowsReturned: number;
-    /** Whether the result was truncated by the row limit */
-    isLimited: boolean;
-    /** The query/params that were executed */
-    queryExecuted?: string;
-    /** Execution time in milliseconds */
-    executionTimeMs: number;
-}
-/**
- * The complete response from the multi-agent system.
- * Contains everything needed for text display + component generation.
- */
-interface AgentResponse {
-    /** Generated text response (analysis of the data) */
-    text: string;
-    /** All executed tools across all source agents (for component generation) */
-    executedTools: ExecutedToolInfo[];
-    /** Individual results from each source agent */
-    sourceResults: SourceAgentResult[];
+    protected getApiKey(apiKey?: string): string | undefined;
     /**
-     * Populated when MainAgent wrote AND successfully executed a script during its turn.
-     * Caller (agent-user-response.ts) persists it via ScriptStore.save().
-     * Absent when MainAgent didn't write one (trivial question / all attempts failed).
+     * Check if a component contains a Form (data_modification component)
+     * Forms have hardcoded defaultValues that become stale when cached
+     * This checks both single Form components and Forms inside MultiComponentContainer
      */
-    savedScript?: AgentWrittenScript;
-}
-/**
- * A script MainAgent authored + verified during its turn. Shape aligns with
- * what ScriptStore.save() needs — minus store-assigned fields (id, timestamps, counts).
- */
-interface AgentWrittenScript {
+    protected containsFormComponent(component: any): boolean;
     /**
-     * `ScriptRecipe.id` of the draft that was authored + verified during this turn.
-     * The caller passes this to `ScriptStore.promoteToVerified(recipeId, …)` to
-     * flip the draft to verified status and (when possible) drop the turn-suffix
-     * from its filename.
+     * Match components from text response suggestions and generate follow-up questions
+     * Takes a text response with component suggestions (c1:type format) and matches with available components
+     * Also generates title, description, and intelligent follow-up questions (actions) based on the analysis
+     * All components are placed in a default MultiComponentContainer layout
+     * @param analysisContent - The text response containing component suggestions
+     * @param components - List of available components
+     * @param apiKey - Optional API key
+     * @param componentStreamCallback - Optional callback to stream primary KPI component as soon as it's identified
+     * @returns Object containing matched components, layout title/description, and follow-up actions
      */
-    recipeId: string;
-    name: string;
-    intentDescription: string;
-    tags: string[];
-    parameters: Array<{
-        name: string;
-        type: 'string' | 'number' | 'date' | 'date_range' | 'enum' | 'boolean';
-        required: boolean;
-        default?: any;
-        enumValues?: Record<string, string>;
-        description: string;
-    }>;
-    scriptBody: string;
-    /** Source IDs referenced by the script (extracted from ctx.query calls) */
-    sourceIds: string[];
-    /** Tables referenced in the script's SQL (regex-extracted) */
-    tables: string[];
-    /** Executed queries from the verified run — fed to component generation */
-    executedQueries: Array<{
-        sourceId: string;
-        sourceName: string;
-        sql: string;
-        data: any[];
-        count: number;
-        totalCount?: number;
-        executionTimeMs: number;
-        /**
-         * True for synthetic entries (ctx.emit datasets, the computed:_final
-         * post-JS data). The component generator routes virtual sources through
-         * the script_dataset sentinel toolId so the frontend resolves them via
-         * queryCache instead of attempting to re-execute SQL.
-         */
-        virtual?: boolean;
+    matchComponentsFromAnalysis(analysisContent: string, components: Component[], userPrompt: string, apiKey?: string, componentStreamCallback?: (component: Component) => void, deferredTools?: any[], executedTools?: any[], collections?: any, userId?: string): Promise<{
+        components: Component[];
+        layoutTitle: string;
+        layoutDescription: string;
+        actions: Action[];
     }>;
-}
-/**
- * Configuration for the multi-agent system.
- * Controls limits, models, and behavior.
- */
-interface AgentConfig {
-    /** Max rows a source agent can return (default: 50) */
-    maxRowsPerSource: number;
-    /** Model for the main agent (routing + analysis in one LLM call) */
-    mainAgentModel: string;
-    /** Model for source agent query generation */
-    sourceAgentModel: string;
-    /** API key for LLM calls */
-    apiKey?: string;
-    /** Max retry attempts per source agent */
-    maxRetries: number;
-    /** Max tool calling iterations for the main agent loop */
-    maxIterations: number;
-    /** Global knowledge base context (static, same for all users/questions — cached in system prompt) */
-    globalKnowledgeBase?: string;
-    /** Per-request knowledge base context (user-specific + query-matched — dynamic, not cached) */
-    knowledgeBaseContext?: string;
-    /** Collections registry (ChromaDB search hooks) for embedding-based schema + source search */
-    collections?: any;
-    /** Optional project ID for scoping embedding searches */
-    projectId?: string;
-}
-/**
- * Default agent configuration
- */
-declare const DEFAULT_AGENT_CONFIG: AgentConfig;
-
-/**
- * Script Flow Types
- *
- * Defines interfaces for the script-based query architecture:
- * - ScriptRecipe: metadata for matching, validation, and quality tracking
- * - ScriptResult: output from executing a script
- * - ScriptMatch: result from the LLM-based script matcher
- */
-/**
- * Recipe metadata stored alongside each script.
- * Used for matching, validation, and quality tracking.
- */
-interface ScriptRecipe {
-    /** Unique script identifier */
-    id: string;
-    /** Version number (incremented on regeneration) */
-    version: number;
-    /** Human-readable name (e.g., "Revenue by Dimension") */
-    name: string;
-    /** Natural language description of what this script does */
-    intentDescription: string;
-    /** Keyword tags for quick filtering */
-    tags: string[];
-    /** Source tool IDs this script queries (e.g., ["mssql-abc123_query"]) */
-    sourceIds: string[];
-    /** Table names used (for future schema drift detection) */
-    tables: string[];
-    /** Parameter definitions — what can vary */
-    parameters: ScriptParameter[];
-    /** The script function body as a string */
-    scriptBody: string;
-    /** Times this script was used successfully */
-    successCount: number;
-    /** Times this script failed */
-    failureCount: number;
-    /** ISO timestamp of last usage */
-    lastUsed: string;
-    /** Original user question that created this script */
-    createdFrom: string;
-    /** ISO timestamp */
-    createdAt: string;
-    /** ISO timestamp */
-    updatedAt: string;
     /**
-     * `recipe.id` of the parent this script was forked from.
-     * Undefined for root scripts (those written from scratch by MainAgent).
-     * See backend/docs/SCRIPT-FLOW-FORK-ADAPT.md.
+     * Classify user question into category and detect external tools needed
+     * Determines if question is for data analysis, requires external tools, or needs text response
      */
-    parentId?: string;
-    /** 0 for root scripts; `parent.forkDepth + 1` for forks. Capped at 3. */
-    forkDepth?: number;
+    classifyQuestionCategory(userPrompt: string, apiKey?: string, conversationHistory?: string, externalTools?: any[]): Promise<{
+        category: 'data_analysis' | 'data_modification' | 'general';
+        externalTools: Array<{
+            type: string;
+            name: string;
+            description: string;
+            parameters: Record<string, any>;
+        }>;
+        dataAnalysisType?: 'visualization' | 'calculation' | 'comparison' | 'trend';
+        reasoning: string;
+        confidence: number;
+    }>;
     /**
-     * Brief description of what this fork changed vs its parent
-     * (sourced from the matcher's `modificationHint`).
+     * Adapt UI block parameters based on current user question
+     * Takes a matched UI block from semantic search and modifies its props to answer the new question
+     * Also adapts the cached text response to match the new question
      */
-    forkReason?: string;
+    adaptUIBlockParameters(currentUserPrompt: string, originalUserPrompt: string, matchedUIBlock: any, apiKey?: string, cachedTextResponse?: string): Promise<{
+        success: boolean;
+        adaptedComponent?: Component;
+        adaptedTextResponse?: string;
+        parametersChanged?: Array<{
+            field: string;
+            reason: string;
+        }>;
+        explanation: string;
+    }>;
     /**
-     * Lifecycle stage of this recipe on disk.
-     * - 'draft':    written by MainAgent's write_script during a turn; filtered out
-     *               of `ScriptStore.getAll()` so the matcher never picks it.
-     *               Filename is suffixed with `turnId` to keep concurrent turns
-     *               from clobbering each other's drafts.
-     * - 'verified': promoted after `execute_script` succeeded; the matcher sees it.
-     *               Filename drops the turn suffix unless a verified file with
-     *               the same slug already exists (collision case keeps the suffix).
-     *
-     * Recipes loaded from disk without this field default to 'verified' so
-     * existing scripts keep working unchanged.
+     * Generate text-based response for user question
+     * This provides conversational text responses instead of component generation
+     * Supports tool calling for query execution with automatic retry on errors (max 3 attempts)
+     * After generating text response, if components are provided, matches suggested components
      */
-    status?: 'draft' | 'verified';
+    generateTextResponse(userPrompt: string, apiKey?: string, conversationHistory?: string, streamCallback?: (chunk: string) => void, collections?: any, components?: Component[], externalTools?: any[], category?: 'data_analysis' | 'data_modification' | 'general', userId?: string): Promise<T_RESPONSE>;
     /**
-     * Per-turn unique suffix used for draft filenames (e.g. `1714745623-x9k2`).
-     * Set when the draft is saved; carried until the recipe is promoted.
+     * Main orchestration function with semantic search and multi-step classification
+     * NEW FLOW (Recommended):
+     * 1. Semantic search: Check previous conversations (>60% match)
+     *    - If match found → Adapt UI block parameters and return
+     * 2. Category classification: Determine if data_analysis, requires_external_tools, or text_response
+     * 3. Route appropriately based on category and response mode
      */
-    turnId?: string;
+    handleUserRequest(userPrompt: string, components: Component[], apiKey?: string, conversationHistory?: string, responseMode?: 'component' | 'text', streamCallback?: (chunk: string) => void, collections?: any, externalTools?: any[], userId?: string): Promise<T_RESPONSE>;
     /**
-     * Last execution error captured by `recordDraftError` while the recipe was
-     * still a draft. Lets users open the draft .json file and see why it failed
-     * without grepping logs. Cleared on promotion to 'verified'.
+     * Generate next questions that the user might ask based on the original prompt and generated component
+     * This helps provide intelligent suggestions for follow-up queries
+     * For general/conversational questions without components, pass textResponse instead
      */
-    lastError?: {
-        phase: 'compile' | 'runtime' | 'timeout' | 'ipc';
-        message: string;
-        at: string;
-        attempt: number;
-    };
+    generateNextQuestions(originalUserPrompt: string, component?: Component | null, componentData?: Record<string, unknown>, apiKey?: string, conversationHistory?: string, textResponse?: string): Promise<string[]>;
 }
-interface ScriptParameter {
-    /** Parameter name (used in script body as params.name) */
-    name: string;
-    /** Parameter type */
-    type: 'string' | 'number' | 'date' | 'date_range' | 'enum' | 'boolean';
-    /** Whether this parameter is required */
-    required: boolean;
-    /** Default value if not provided */
-    default?: any;
-    /** For enum type — maps user-facing values to internal values */
-    enumValues?: Record<string, string>;
-    /** Human-readable description (used in the matcher LLM prompt) */
-    description: string;
+
+interface AnthropicLLMConfig extends BaseLLMConfig {
+}
+/**
+ * AnthropicLLM class for handling AI-powered component generation and matching using Anthropic Claude
+ */
+declare class AnthropicLLM extends BaseLLM {
+    constructor(config?: AnthropicLLMConfig);
+    protected getDefaultModel(): string;
+    protected getDefaultFastModel(): string;
+    protected getDefaultApiKey(): string | undefined;
+    protected getProviderName(): string;
 }
+declare const anthropicLLM: AnthropicLLM;
 
+interface GroqLLMConfig extends BaseLLMConfig {
+}
 /**
- * ScriptStore — Persistent Storage for Script Recipes
- *
- * Layout:
- *   scripts-store/
- *     metadata/<name>.json   ← recipe metadata (params, tables, counts, ...)
- *     <name>.ts              ← the getData() function body, editable in your IDE
- *
- * Each VM deployment is a single project, so no project ID prefix needed.
- * Legacy single-file format (JSON with embedded scriptBody) is still loadable
- * for backwards compatibility and auto-migrated to the split format on next save.
+ * GroqLLM class for handling AI-powered component generation and matching using Groq
  */
+declare class GroqLLM extends BaseLLM {
+    constructor(config?: GroqLLMConfig);
+    protected getDefaultModel(): string;
+    protected getDefaultFastModel(): string;
+    protected getDefaultApiKey(): string | undefined;
+    protected getProviderName(): string;
+}
+declare const groqLLM: GroqLLM;
 
+interface GeminiLLMConfig extends BaseLLMConfig {
+}
 /**
- * Input for `ScriptStore.saveDraft()`. Identifies the draft by `recipeId` so
- * retries within the same turn overwrite the same files (or omit `recipeId`
- * on the first call to mint a fresh draft).
+ * GeminiLLM class for handling AI-powered component generation and matching using Google Gemini
  */
-interface SaveDraftInput {
-    /** Reuse an existing draft (retry); omit to mint a new one. */
-    recipeId?: string;
-    /** Per-turn unique suffix, stable across retries within the turn. */
-    turnId: string;
-    name: string;
-    intentDescription: string;
-    tags: string[];
-    parameters: ScriptParameter[];
-    scriptBody: string;
-    createdFrom: string;
+declare class GeminiLLM extends BaseLLM {
+    constructor(config?: GeminiLLMConfig);
+    protected getDefaultModel(): string;
+    protected getDefaultFastModel(): string;
+    protected getDefaultApiKey(): string | undefined;
+    protected getProviderName(): string;
+}
+declare const geminiLLM: GeminiLLM;
+
+interface OpenAILLMConfig extends BaseLLMConfig {
 }
 /**
- * Lineage + provenance fields applied when a draft is promoted to verified.
- * MainAgent gathers `sourceIds` and `tables` from the verified execution; the
- * caller (agent-user-response.ts) supplies the optional fork lineage.
+ * OpenAILLM class for handling AI-powered component generation and matching using OpenAI GPT models
  */
-interface PromoteToVerifiedInput {
-    sourceIds: string[];
-    tables: string[];
-    parentId?: string;
-    forkDepth?: number;
-    forkReason?: string;
+declare class OpenAILLM extends BaseLLM {
+    constructor(config?: OpenAILLMConfig);
+    protected getDefaultModel(): string;
+    protected getDefaultFastModel(): string;
+    protected getDefaultApiKey(): string | undefined;
+    protected getProviderName(): string;
 }
-declare class ScriptStore {
-    private recipes;
-    private storeDir;
-    private loaded;
-    constructor(baseDir?: string);
-    private metadataDir;
-    /**
-     * Filename base for a recipe. Drafts include the per-turn suffix so two
-     * concurrent turns can never clobber each other's draft files; verified
-     * recipes use the bare slug.
-     */
-    private fileBaseName;
-    /**
-     * Absolute path to the .ts file for a recipe. Callers (e.g. ScriptRunner,
-     * MainAgent's execute_script) use this to hand off the path to the tsx child.
-     */
-    getScriptPath(recipe: ScriptRecipe): string;
-    /**
-     * Absolute path to the metadata JSON for a recipe.
-     */
-    private getMetadataPath;
-    /**
-     * Get all VERIFIED recipes — drafts are filtered out so the matcher never
-     * considers an unverified script. Loads from disk on first access.
-     */
-    getAll(): ScriptRecipe[];
+declare const openaiLLM: OpenAILLM;
+
+/**
+ * Query Cache — Two mechanisms:
+ *
+ * 1. `cache` (query string → result data) — TTL-based with max size, for avoiding re-execution
+ *    of recently validated queries. True LRU eviction: reads bubble entries to the back via
+ *    delete+re-set so the oldest *unused* entry is evicted, not the oldest *inserted*.
+ *
+ * 2. Encrypted queryId tokens — SQL is encrypted into the queryId itself (self-contained).
+ *    No server-side storage needed for SQL mappings. The token is decrypted on each request.
+ *    This eliminates the unbounded queryIdCache that previously grew forever and caused
+ *    memory bloat (hundreds of MBs after thousands of queries).
+ *
+ *    Result data can still be cached temporarily via the data cache (mechanism 1).
+ */
+declare class QueryCache {
+    private cache;
+    private ttlMs;
+    private maxCacheSize;
+    private cleanupInterval;
+    private readonly algorithm;
+    private encryptionKey;
+    constructor();
     /**
-     * Get a recipe by ID — returns drafts as well as verified scripts.
-     * Used by MainAgent and the promotion path.
+     * Set the cache TTL (Time To Live)
+     * @param minutes - TTL in minutes (default: 10)
      */
-    get(id: string): ScriptRecipe | null;
+    setTTL(minutes: number): void;
     /**
-     * Number of verified recipes (matches `getAll().length`).
+     * Get the current TTL in minutes
      */
-    count(): number;
+    getTTL(): number;
     /**
-     * Save a recipe (create or update).
-     * File is named after the script: "order-status-distribution.json"
+     * Store query result in data cache.
+     * If the key already exists, it's removed first so the re-insert places it
+     * at the back of the iteration order (LRU). Eviction only fires when adding
+     * a genuinely new key past the size limit.
      */
-    save(recipe: ScriptRecipe): void;
+    set(query: string, data: any): void;
     /**
-     * Persist (or update) a draft recipe to disk. Always writes immediately so
-     * the `.ts` body is visible in the IDE the moment MainAgent calls
-     * `write_script`. Within one turn, retries that pass the same `recipeId`
-     * overwrite the same files (the LLM rewriting itself); a fresh `recipeId`
-     * is minted only on the first call of the turn.
-     *
-     * Filename includes the `turnId` suffix so concurrent turns never collide.
+     * Get cached result if exists and not expired.
+     * On hit, re-inserts the entry so it moves to the back of the Map's
+     * iteration order — turning FIFO eviction into true LRU.
      */
-    saveDraft(input: SaveDraftInput): ScriptRecipe;
+    get(query: string): any | null;
     /**
-     * Stamp the draft with the most recent execution failure so it is visible
-     * in the metadata JSON without grepping logs. No-op if the recipe doesn't
-     * exist or has already been promoted.
+     * Check if query exists in cache (not expired)
      */
-    recordDraftError(recipeId: string, err: {
-        phase: 'compile' | 'runtime' | 'timeout' | 'ipc';
-        message: string;
-        attempt: number;
-    }): void;
+    has(query: string): boolean;
     /**
-     * Promote a successfully-executed draft into a verified script.
-     *
-     * - Renames the on-disk files from `<slug>-<turnId>.{ts,json}` to the bare
-     *   `<slug>.{ts,json}`. If a verified file with the same slug already exists
-     *   (concurrent turn won the race, or a prior session has it), the recipe
-     *   keeps its turn-suffixed filename so we never overwrite verified work —
-     *   the matcher keys on `recipe.id`, so two siblings with similar slugs is fine.
-     * - Flips `status: 'verified'`, clears `lastError`, applies provenance
-     *   (`sourceIds`, `tables`) and optional fork lineage.
+     * Remove a specific query from cache
      */
-    promoteToVerified(recipeId: string, input: PromoteToVerifiedInput): ScriptRecipe | null;
+    delete(query: string): void;
     /**
-     * Drop a draft from disk + memory (e.g. when an outer error path wants to
-     * clean up). Per the agreed policy, MainAgent's normal failure path does
-     * NOT call this — failed drafts are kept on disk for the user to inspect.
+     * Clear all cached entries
      */
-    discardDraft(recipeId: string): void;
+    clear(): void;
     /**
-     * Delete a recipe by ID.
+     * Get cache statistics
      */
-    delete(id: string): void;
+    getStats(): {
+        size: number;
+        queryIdCount: number;
+        oldestEntryAge: number | null;
+    };
     /**
-     * Record a successful execution for a recipe.
+     * Start periodic cleanup of expired data cache entries.
      */
-    recordSuccess(id: string): void;
+    private startCleanup;
     /**
-     * Record a failed execution for a recipe.
+     * Encrypt a payload into a self-contained token.
      */
-    recordFailure(id: string): void;
+    private encrypt;
     /**
-     * Get the failure rate for a recipe (0 to 1).
-     * Returns 0 if the recipe has fewer than 5 total uses.
+     * Decrypt a token back to the original payload.
      */
-    getFailureRate(id: string): number;
-    private ensureLoaded;
+    private decrypt;
     /**
-     * Convert a script name to a safe filename.
-     * "Order Status Distribution" → "order-status-distribution"
+     * Store a query by generating an encrypted token as queryId.
+     * The SQL is encrypted INTO the token — nothing stored in memory.
+     * If data is provided, it's cached temporarily in the data cache.
      */
-    private toFileName;
+    storeQuery(query: any, data?: any): string;
     /**
-     * Load all script files from disk.
-     *
-     * Supports two layouts:
-     *   - New (preferred): metadata/<name>.json + <name>.ts
-     *   - Legacy: <name>.json with embedded scriptBody (auto-migrated on next save)
+     * Get a stored query by decrypting its token.
+     * Returns the SQL + any cached result data.
      */
-    private loadAllFromDisk;
+    getQuery(queryId: string): {
+        query: any;
+        data: any;
+    } | null;
     /**
-     * Save a recipe to disk in split format:
-     *   metadata/<name>.json  (metadata, no scriptBody)
-     *   <name>.ts             (just the function body)
-     *
-     * If a legacy top-level <name>.json exists for the same recipe, remove it
-     * so we don't end up with duplicate sources of truth.
+     * Update cached data for a queryId token
      */
-    private saveRecipeToDisk;
+    setQueryData(queryId: string, data: any): void;
     /**
-     * Delete a recipe's files from disk (both metadata + body, plus any legacy file).
+     * Stop cleanup interval (for graceful shutdown)
      */
-    private deleteRecipeFromDisk;
+    destroy(): void;
 }
+declare const queryCache: QueryCache;
 
 /**
- * Main Agent (Orchestrator)
- *
- * A single LLM.streamWithTools() call that handles everything:
- * - Routing: decides which source(s) to query based on summaries
- * - Querying: calls source tools (each wraps an independent SourceAgent)
- * - Direct tools: calls pre-built function tools directly with LLM-provided params
- * - Re-querying: if data is wrong/incomplete, calls tools again with modified intent
- * - Analysis: generates final text response from the data
- *
- * Two tool types:
- * - "source" tools: main agent sees summaries, SourceAgent handles SQL generation independently
- * - "direct" tools: main agent calls fn() directly with structured params (no SourceAgent)
+ * Manages conversation history scoped per user + dashboard.
+ * Each user-dashboard pair has its own isolated history that expires after a configurable TTL.
  */
-
-declare class MainAgent {
-    private externalTools;
-    private config;
-    private streamBuffer;
+declare class DashboardConversationHistory {
+    private histories;
+    private ttlMs;
+    private maxEntries;
+    private cleanupInterval;
+    constructor();
     /**
-     * Optional: when provided, MainAgent exposes the `write_script` /
-     * `execute_script` tools to the LLM and persists drafts to disk via the
-     * store. Headless callers (alert analyzer, metric resolver) omit these to
-     * suppress script authoring entirely — drafts would otherwise leak onto
-     * disk with no caller to promote or clean them up.
+     * Set the TTL for dashboard histories
+     * @param minutes - TTL in minutes
      */
-    private scriptStore;
-    private turnId;
-    private createdFromPrompt;
-    private scriptState;
-    constructor(externalTools: ExternalTool[], config: AgentConfig, scriptStore?: ScriptStore, turnId?: string, streamBuffer?: StreamBuffer);
-    private get scriptingEnabled();
+    setTTL(minutes: number): void;
     /**
-     * Handle a user question using the multi-agent system.
-     *
-     * This is ONE LLM.streamWithTools() call. The LLM:
-     * 1. Sees source summaries + direct tool descriptions in system prompt
-     * 2. Decides which tool(s) to call (routing)
-     * 3. Source tools → SourceAgent runs independently → returns data
-     * 4. Direct tools → fn() called directly with LLM params → returns data
-     * 5. Generates final analysis text
+     * Set max entries per dashboard
      */
-    handleQuestion(userPrompt: string, apiKey?: string, conversationHistory?: string, streamCallback?: (chunk: string) => void): Promise<AgentResponse>;
-    private handleWriteScript;
-    private handleExecuteScript;
+    setMaxEntries(max: number): void;
     /**
-     * Build the AgentWrittenScript payload the caller will hand to
-     * `ScriptStore.promoteToVerified()`. Only returned when a verified
-     * successful execution is on record.
+     * Add a conversation entry for a user's dashboard
      */
-    private buildSavedScript;
-    private normalizeParameterList;
+    addEntry(dashboardId: string, userPrompt: string, componentSummary: string, userId?: string): void;
     /**
-     * Use the schema embedding collection to pre-select relevant tables for
-     * this source + intent. Returns a formatted schema block if confidence is
-     * high (top match ≥ 0.55 and ≥3 candidates), otherwise null.
-     *
-     * When this returns a block, we can skip the SourceAgent's `search_schema`
-     * loop and reduce iteration budget. When it returns null, the SourceAgent
-     * falls back to the existing LLM-driven keyword search (same as today).
+     * Get formatted conversation history for a user's dashboard
      */
-    private preResolveSchema;
+    getHistory(dashboardId: string, userId?: string): string;
     /**
-     * Execute a direct tool — call fn() with LLM-provided params, no SourceAgent.
+     * Clear history for a specific user's dashboard
      */
-    private handleDirectTool;
+    clearDashboard(dashboardId: string, userId?: string): void;
     /**
-     * Build the main agent's system prompt with source summaries and direct tool descriptions.
+     * Clear all dashboard histories
      */
-    private buildSystemPrompt;
+    clearAll(): void;
     /**
-     * Build tool definitions for source tools — summary-only descriptions.
-     * The full schema is inside the SourceAgent which runs independently.
+     * Start periodic cleanup of expired histories
      */
-    private buildSourceToolDefinitions;
+    private startCleanup;
     /**
-     * Build tool definitions for direct tools — expose their actual params.
-     * These are called directly by the main agent LLM, no SourceAgent.
+     * Stop cleanup interval (for graceful shutdown)
      */
-    private buildDirectToolDefinitions;
+    destroy(): void;
+}
+declare const dashboardConversationHistory: DashboardConversationHistory;
+
+/**
+ * ScriptMatcher — LLM-Based Script Matching + Parameter Extraction
+ *
+ * Uses ONE LLM call to:
+ * 1. Pick the best matching script from the library (or "none")
+ * 2. Extract parameter values from the user question
+ *
+ * Why LLM over embeddings:
+ * - Embeddings capture topic similarity ("overstock" ≈ "inventory" ≈ "revenue")
+ *   but can't distinguish structurally different questions about the same domain
+ * - LLM understands that "overstock by warehouse" needs a different script than
+ *   "revenue by warehouse" even though they're semantically close
+ * - One call does both matching AND parameter extraction
+ *
+ * When script library grows past ~50, add an embedding pre-filter
+ * (ChromaDB narrows to top 10 → LLM picks from those 10).
+ */
+
+declare class ScriptMatcher {
+    private store;
+    constructor(store: ScriptStore);
     /**
-     * Format a source agent's result as a clean string for the main agent LLM.
+     * Find the best matching script for a user question.
+     * Uses ONE LLM call that picks the script AND extracts parameters.
+     * Returns null if no script matches.
      */
-    private formatResultForMainAgent;
+    match(userPrompt: string, apiKey?: string, model?: string): Promise<ScriptMatch | null>;
     /**
-     * Get source summaries (for external inspection/debugging).
+     * Build the script catalog string for the LLM prompt.
+     * Each script gets: index, ID, name, description, and parameter definitions.
      */
-    getSourceSummaries(): SourceSummary[];
+    private buildScriptCatalog;
+}
+
+/**
+ * ScriptRunner — Execute scripts in an isolated tsx subprocess.
+ *
+ * The subprocess approach replaces the earlier `new Function()` eval and gives us:
+ *   - Real sandbox (separate process, SIGKILL on timeout).
+ *   - Real TypeScript (tsx transpiles on the fly).
+ *   - npm imports available to scripts (clustering, stats, geo, etc.).
+ *
+ * Protocol: NDJSON over the child's stdin/stdout. See script-ipc.ts + backend/docs/SCRIPT-FLOW-IMPLEMENTATION.md.
+ */
+
+interface RunScriptOptions {
+    /** Data sources the script is allowed to query via ctx.query */
+    externalTools: ExternalTool[];
+    /** Optional — for propagating per-query UI progress to the user */
+    streamBuffer?: StreamBuffer;
+    /** Override the wall-clock timeout (default `SCRIPT_TIMEOUT_MS`, 60s). */
+    timeoutMs?: number;
 }
+/**
+ * Execute a recipe by spawning a tsx child on the script's .ts file.
+ * `scriptPath` is the absolute path to the saved `.ts` body.
+ */
+declare function runScript(recipe: ScriptRecipe, scriptPath: string, params: Record<string, any>, options: RunScriptOptions): Promise<ScriptResult>;
 
 type MessageTypeHandler = (message: IncomingMessage) => void | Promise<void>;
 declare class SuperatomSDK {
@@ -3141,6 +3494,7 @@ declare class SuperatomSDK {
     private collections;
     private components;
     private tools;
+    private workflows;
     private anthropicApiKey;
     private groqApiKey;
     private geminiApiKey;
@@ -3250,6 +3604,19 @@ declare class SuperatomSDK {
      * Get the stored tools
      */
     getTools(): Tool$1[];
+    /**
+     * Register workflow components for the SDK instance.
+     *
+     * Workflows are pre-built multi-step UI flows the main agent can pick when
+     * the user's prompt matches a workflow's `whenToUse` trigger. Picking a
+     * workflow short-circuits analysis text + dashboard component generation —
+     * the workflow component is returned directly, with the LLM-extracted props.
+     */
+    setWorkflows(workflows: WorkflowDescriptor[]): void;
+    /**
+     * Get the registered workflow components.
+     */
+    getWorkflows(): WorkflowDescriptor[];
     /**
      * Apply model strategy to all LLM provider singletons
      * @param strategy - 'best', 'fast', or 'balanced'
@@ -3280,4 +3647,4 @@ declare class SuperatomSDK {
     getConversationSimilarityThreshold(): number;
 }
 
-export { type Action, type AgentConfig, type AgentResponse, BM25L, type BM25LOptions, type BaseLLMConfig, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CollectionHandler, type CollectionOperation, type DBUIBlock, DEFAULT_AGENT_CONFIG, type DatabaseType, type HybridSearchOptions, type IncomingMessage, type KbNodesQueryFilters, type KbNodesRequestPayload, LLM, type LLMUsageEntry, type LogLevel, MainAgent, type Message, type ModelStrategy, type OutputField, type RerankedResult, STORAGE_CONFIG, SuperatomSDK, type SuperatomSDKConfig, type TaskType, Thread, ThreadManager, type Tool$1 as Tool, type ToolOutputSchema, UIBlock, UILogCollector, type User, UserManager, type UsersData, anthropicLLM, dashboardConversationHistory, geminiLLM, groqLLM, hybridRerank, llmUsageLogger, logger, openaiLLM, queryCache, rerankChromaResults, rerankConversationResults, userPromptErrorLogger };
+export { type Action, type AgentConfig, type AgentResponse, BM25L, type BM25LOptions, type BaseLLMConfig, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CollectionHandler, type CollectionOperation, type DBUIBlock, DEFAULT_AGENT_CONFIG, type DatabaseType, type HybridSearchOptions, type IncomingMessage, type KbNodesQueryFilters, type KbNodesRequestPayload, LLM, type LLMUsageEntry, type LogLevel, MainAgent, type Message, type ModelStrategy, type OutputField, type RerankedResult, STORAGE_CONFIG, type ScriptComponentSpec, ScriptMatcher, type ScriptParameter, type ScriptRecipe, type ScriptRecipeMetaRow, type ScriptRecipeStore, type ScriptResult, ScriptStore, type ScriptStoreOptions, type SelectedWorkflow, SuperatomSDK, type SuperatomSDKConfig, type TaskType, Thread, ThreadManager, type Tool$1 as Tool, type ToolOutputSchema, UIBlock, UILogCollector, type User, UserManager, type UsersData, type WorkflowDescriptor, anthropicLLM, dashboardConversationHistory, geminiLLM, groqLLM, hybridRerank, llmUsageLogger, logger, normalizeScriptBody, openaiLLM, queryCache, rerankChromaResults, rerankConversationResults, resolveScriptRecipeStore, runScript, userPromptErrorLogger };