@superatomai/sdk-node 0.0.12-mds → 0.0.12-s

package/dist/index.d.mts

@@ -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';
@@ -860,6 +874,18 @@ interface SuperatomSDKConfig {
      * - 'balanced': Use best model for complex tasks, fast model for simple tasks (default)
      */
     modelStrategy?: ModelStrategy;
+    /**
+     * Model for the main agent (routing + analysis).
+     * Format: "provider/model-name" (e.g., "anthropic/claude-haiku-4-5-20251001")
+     * If not set, uses the provider's default model.
+     */
+    mainAgentModel?: string;
+    /**
+     * Model for source agents (per-source query generation).
+     * Format: "provider/model-name" (e.g., "anthropic/claude-haiku-4-5-20251001")
+     * If not set, uses the provider's default model.
+     */
+    sourceAgentModel?: string;
     /**
      * Separate model configuration for DASH_COMP flow (dashboard component picking)
      * If not provided, falls back to provider-based model selection
@@ -878,6 +904,12 @@ interface SuperatomSDKConfig {
      * Default: 5 minutes
      */
     queryCacheTTL?: number;
+    /**
+     * Dashboard conversation history TTL (Time To Live) in minutes
+     * Per-dashboard conversation histories expire after this duration
+     * Default: 30 minutes
+     */
+    dashboardHistoryTTL?: number;
 }
 
 declare const KbNodesQueryFiltersSchema: z.ZodObject<{
@@ -1288,6 +1320,888 @@ declare class ReportManager {
     getReportCount(): number;
 }
 
+/**
+ * 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);
+    /**
+     * Check if the buffer has a callback configured
+     */
+    hasCallback(): boolean;
+    /**
+     * Get all text that has been written (including already flushed)
+     */
+    getFullText(): string;
+    /**
+     * 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
+     */
+    write(chunk: string): void;
+    /**
+     * Flush the buffer immediately
+     * Call this before tool execution or other operations that need clean output
+     */
+    flush(): void;
+    /**
+     * Internal flush implementation
+     */
+    private flushNow;
+    /**
+     * Clean up resources
+     * Call this when done with the buffer
+     */
+    dispose(): void;
+}
+
+/**
+ * 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>;
+}
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+/**
+ * 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;
+    /**
+     * 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."
+     */
+    whenToUse: string;
+    /**
+     * 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',
+     * }
+     * ```
+     */
+    propsSchema: Record<string, string>;
+    /**
+     * 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.
+     */
+    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[];
+    /**
+     * 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).
+     */
+    savedScript?: AgentWrittenScript;
+    /**
+     * 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.
+     */
+    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 {
+    /**
+     * `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.
+     */
+    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 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. Loaded from disk (scripts-store/<fileBase>.ts). */
+    scriptBody: string;
+    /**
+     * 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.
+     */
+    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;
+    /**
+     * `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.
+     */
+    parentId?: string;
+    /** 0 for root scripts; `parent.forkDepth + 1` for forks. Capped at 3. */
+    forkDepth?: number;
+    /**
+     * Brief description of what this fork changed vs its parent
+     * (sourced from the matcher's `modificationHint`).
+     */
+    forkReason?: string;
+    /**
+     * 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.
+     */
+    components?: ScriptComponentSpec[];
+    /**
+     * 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.
+     */
+    status?: 'draft' | 'verified';
+    /**
+     * Per-turn unique suffix used for draft filenames (e.g. `1714745623-x9k2`).
+     * Set when the draft is saved; carried until the recipe is promoted.
+     */
+    turnId?: string;
+    /**
+     * 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'.
+     */
+    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;
+    /**
+     * 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).
+     */
+    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;
+    /**
+     * 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.
+     */
+    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;
+}
+
+/**
+ * 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).
+ */
+
+/** 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>;
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    private scriptStore;
+    private turnId;
+    private createdFromPrompt;
+    private scriptState;
+    constructor(externalTools: ExternalTool[], config: AgentConfig, scriptStore?: ScriptStore, turnId?: string, streamBuffer?: StreamBuffer, workflows?: WorkflowDescriptor[]);
+    private get scriptingEnabled();
+    /**
+     * 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
+     */
+    handleQuestion(userPrompt: string, apiKey?: string, conversationHistory?: string, streamCallback?: (chunk: string) => void): Promise<AgentResponse>;
+    private handleWriteScript;
+    private handleExecuteScript;
+    /**
+     * Build the AgentWrittenScript payload the caller will hand to
+     * `ScriptStore.promoteToVerified()`. Only returned when a verified
+     * successful execution is on record.
+     */
+    private buildSavedScript;
+    private normalizeParameterList;
+    /**
+     * 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).
+     */
+    private preResolveSchema;
+    /**
+     * Execute a direct tool — call fn() with LLM-provided params, no SourceAgent.
+     */
+    private handleDirectTool;
+    /**
+     * Build the main agent's system prompt with source summaries, direct tool descriptions,
+     * and workflow component descriptions.
+     */
+    private buildSystemPrompt;
+    /**
+     * Build tool definitions for source tools — summary-only descriptions.
+     * The full schema is inside the SourceAgent which runs independently.
+     */
+    private buildSourceToolDefinitions;
+    /**
+     * Build tool definitions for direct tools — expose their actual params.
+     * These are called directly by the main agent LLM, no SourceAgent.
+     */
+    private buildDirectToolDefinitions;
+    /**
+     * 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.
+     */
+    private handleWorkflow;
+    /**
+     * 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.
+     */
+    private buildWorkflowToolDefinitions;
+    /**
+     * Format a source agent's result as a clean string for the main agent LLM.
+     */
+    private formatResultForMainAgent;
+    /**
+     * Get source summaries (for external inspection/debugging).
+     */
+    getSourceSummaries(): SourceSummary[];
+}
+
+/**
+ * Represents an action that can be performed on a UIBlock
+ */
+interface Action {
+    id: string;
+    name: string;
+    type: string;
+    [key: string]: any;
+}
+
 type SystemPrompt = string | Anthropic.Messages.TextBlockParam[];
 interface LLMMessages {
     sys: SystemPrompt;
@@ -1322,6 +2236,16 @@ declare class LLM {
      * @returns Normalized system prompt for Anthropic API
      */
     private static _normalizeSystemPrompt;
+    /**
+     * 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.
+     */
+    private static _sanitizeMessages;
     /**
      * Log cache usage metrics from Anthropic API response
      * Shows cache hits, costs, and savings
@@ -1442,16 +2366,6 @@ declare class UILogCollector {
     setUIBlockId(uiBlockId: string): void;
 }
 
-/**
- * Represents an action that can be performed on a UIBlock
- */
-interface Action {
-    id: string;
-    name: string;
-    type: string;
-    [key: string]: any;
-}
-
 /**
  * UIBlock represents a single user and assistant message block in a thread
  * Contains user question, component metadata, component data, text response, and available actions
@@ -1634,12 +2548,20 @@ declare class Thread {
 
 /**
  * ThreadManager manages all threads globally
- * Provides methods to create, retrieve, and delete threads
+ * Provides methods to create, retrieve, and delete threads.
+ * Includes automatic cleanup to prevent unbounded memory growth.
  */
 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
      */
@@ -2339,18 +3261,30 @@ declare class OpenAILLM extends BaseLLM {
 declare const openaiLLM: OpenAILLM;
 
 /**
- * Query Cache - Stores query results with configurable TTL
- * Used to avoid re-executing queries that were already validated
+ * 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 queryIdCache;
     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: 5)
+     * @param minutes - TTL in minutes (default: 10)
      */
     setTTL(minutes: number): void;
     /**
@@ -2358,12 +3292,16 @@ declare class QueryCache {
      */
     getTTL(): number;
     /**
-     * Store query result in cache
-     * Key is the exact query string (or JSON for parameterized queries)
+     * 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.
      */
     set(query: string, data: any): void;
     /**
-     * Get cached result if exists and not expired
+     * 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.
      */
     get(query: string): any | null;
     /**
@@ -2383,30 +3321,37 @@ declare class QueryCache {
      */
     getStats(): {
         size: number;
+        queryIdCount: number;
         oldestEntryAge: number | null;
     };
     /**
-     * Start periodic cleanup of expired entries
+     * Start periodic cleanup of expired data cache entries.
      */
     private startCleanup;
     /**
-     * Generate a unique query ID
+     * Encrypt a payload into a self-contained token.
+     */
+    private encrypt;
+    /**
+     * Decrypt a token back to the original payload.
      */
-    private generateQueryId;
+    private decrypt;
     /**
-     * Store a query by ID. Returns the generated queryId.
-     * The query is stored server-side; only the queryId is sent to the frontend.
+     * 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;
     /**
-     * Get a stored query by its ID (not expired)
+     * Get a stored query by decrypting its token.
+     * Returns the SQL + any cached result data.
      */
     getQuery(queryId: string): {
         query: any;
         data: any;
     } | null;
     /**
-     * Update cached data for a queryId
+     * Update cached data for a queryId token
      */
     setQueryData(queryId: string, data: any): void;
     /**
@@ -2416,6 +3361,111 @@ declare class QueryCache {
 }
 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();
+    /**
+     * Set the TTL for dashboard histories
+     * @param minutes - TTL in minutes
+     */
+    setTTL(minutes: number): void;
+    /**
+     * Set max entries per dashboard
+     */
+    setMaxEntries(max: number): void;
+    /**
+     * Add a conversation entry for a user's dashboard
+     */
+    addEntry(dashboardId: string, userPrompt: string, componentSummary: string, userId?: string): void;
+    /**
+     * Get formatted conversation history for a user's dashboard
+     */
+    getHistory(dashboardId: string, userId?: string): string;
+    /**
+     * Clear history for a specific user's dashboard
+     */
+    clearDashboard(dashboardId: string, userId?: string): void;
+    /**
+     * Clear all dashboard histories
+     */
+    clearAll(): void;
+    /**
+     * Start periodic cleanup of expired histories
+     */
+    private startCleanup;
+    /**
+     * Stop cleanup interval (for graceful shutdown)
+     */
+    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);
+    /**
+     * 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.
+     */
+    match(userPrompt: string, apiKey?: string, model?: string): Promise<ScriptMatch | null>;
+    /**
+     * Build the script catalog string for the LLM prompt.
+     * Each script gets: index, ID, name, description, and parameter definitions.
+     */
+    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 {
     private ws;
@@ -2432,6 +3482,7 @@ declare class SuperatomSDK {
     private collections;
     private components;
     private tools;
+    private workflows;
     private anthropicApiKey;
     private groqApiKey;
     private geminiApiKey;
@@ -2439,6 +3490,9 @@ declare class SuperatomSDK {
     private llmProviders;
     private databaseType;
     private modelStrategy;
+    private mainAgentModel;
+    private sourceAgentModel;
+    private dashCompModels?;
     private conversationSimilarityThreshold;
     private userManager;
     private dashboardManager;
@@ -2538,6 +3592,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'
@@ -2568,4 +3635,4 @@ declare class SuperatomSDK {
     getConversationSimilarityThreshold(): number;
 }
 
-export { type Action, BM25L, type BM25LOptions, type BaseLLMConfig, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CollectionHandler, type CollectionOperation, type DBUIBlock, type DatabaseType, type HybridSearchOptions, type IncomingMessage, type KbNodesQueryFilters, type KbNodesRequestPayload, LLM, type LLMUsageEntry, type LogLevel, 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, 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 };