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

package/dist/index.d.ts

@@ -741,6 +741,10 @@ declare const ToolSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
     description: z.ZodString;
+    /** Tool type: "source" = routed through SourceAgent, "direct" = called directly by MainAgent */
+    toolType: z.ZodOptional<z.ZodEnum<["source", "direct"]>>;
+    /** Full untruncated schema for source agent (all columns visible) */
+    fullSchema: z.ZodOptional<z.ZodString>;
     params: z.ZodRecord<z.ZodString, z.ZodString>;
     fn: z.ZodFunction<z.ZodTuple<[z.ZodAny], z.ZodUnknown>, z.ZodAny>;
     outputSchema: z.ZodOptional<z.ZodObject<{
@@ -773,12 +777,22 @@ 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>;
     name: string;
     description: string;
     fn: (args_0: any, ...args: unknown[]) => any;
+    toolType?: "source" | "direct" | undefined;
+    fullSchema?: string | undefined;
     outputSchema?: {
         description: string;
         fields: {
@@ -787,12 +801,17 @@ declare const ToolSchema: z.ZodObject<{
             description: string;
         }[];
     } | undefined;
+    cache?: false | {
+        ttlMs?: number | undefined;
+    } | undefined;
 }, {
     id: string;
     params: Record<string, string>;
     name: string;
     description: string;
     fn: (args_0: any, ...args: unknown[]) => any;
+    toolType?: "source" | "direct" | undefined;
+    fullSchema?: string | undefined;
     outputSchema?: {
         description: string;
         fields: {
@@ -801,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';
@@ -852,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
@@ -870,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<{
@@ -877,18 +917,18 @@ declare const KbNodesQueryFiltersSchema: z.ZodObject<{
     category: z.ZodOptional<z.ZodString>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     type: z.ZodOptional<z.ZodEnum<["global", "user", "query"]>>;
-    createdBy: z.ZodOptional<z.ZodNumber>;
+    createdBy: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     type?: "query" | "user" | "global" | undefined;
     query?: string | undefined;
     category?: string | undefined;
-    createdBy?: number | undefined;
+    createdBy?: string | undefined;
     tags?: string[] | undefined;
 }, {
     type?: "query" | "user" | "global" | undefined;
     query?: string | undefined;
     category?: string | undefined;
-    createdBy?: number | undefined;
+    createdBy?: string | undefined;
     tags?: string[] | undefined;
 }>;
 type KbNodesQueryFilters = z.infer<typeof KbNodesQueryFiltersSchema>;
@@ -901,27 +941,27 @@ declare const KbNodesRequestPayloadSchema: z.ZodObject<{
         category: z.ZodOptional<z.ZodString>;
         tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         type: z.ZodOptional<z.ZodEnum<["global", "user", "query"]>>;
-        createdBy: z.ZodOptional<z.ZodNumber>;
-        updatedBy: z.ZodOptional<z.ZodNumber>;
-        userId: z.ZodOptional<z.ZodNumber>;
+        createdBy: z.ZodOptional<z.ZodString>;
+        updatedBy: z.ZodOptional<z.ZodString>;
+        userId: z.ZodOptional<z.ZodString>;
         query: z.ZodOptional<z.ZodString>;
         filters: z.ZodOptional<z.ZodObject<{
             query: z.ZodOptional<z.ZodString>;
             category: z.ZodOptional<z.ZodString>;
             tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
             type: z.ZodOptional<z.ZodEnum<["global", "user", "query"]>>;
-            createdBy: z.ZodOptional<z.ZodNumber>;
+            createdBy: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
             type?: "query" | "user" | "global" | undefined;
             query?: string | undefined;
             category?: string | undefined;
-            createdBy?: number | undefined;
+            createdBy?: string | undefined;
             tags?: string[] | undefined;
         }, {
             type?: "query" | "user" | "global" | undefined;
             query?: string | undefined;
             category?: string | undefined;
-            createdBy?: number | undefined;
+            createdBy?: string | undefined;
             tags?: string[] | undefined;
         }>>;
         limit: z.ZodOptional<z.ZodNumber>;
@@ -932,17 +972,17 @@ declare const KbNodesRequestPayloadSchema: z.ZodObject<{
         query?: string | undefined;
         title?: string | undefined;
         category?: string | undefined;
-        userId?: number | undefined;
+        userId?: string | undefined;
         limit?: number | undefined;
         filters?: {
             type?: "query" | "user" | "global" | undefined;
             query?: string | undefined;
             category?: string | undefined;
-            createdBy?: number | undefined;
+            createdBy?: string | undefined;
             tags?: string[] | undefined;
         } | undefined;
-        createdBy?: number | undefined;
-        updatedBy?: number | undefined;
+        createdBy?: string | undefined;
+        updatedBy?: string | undefined;
         offset?: number | undefined;
         tags?: string[] | undefined;
         content?: string | undefined;
@@ -952,17 +992,17 @@ declare const KbNodesRequestPayloadSchema: z.ZodObject<{
         query?: string | undefined;
         title?: string | undefined;
         category?: string | undefined;
-        userId?: number | undefined;
+        userId?: string | undefined;
         limit?: number | undefined;
         filters?: {
             type?: "query" | "user" | "global" | undefined;
             query?: string | undefined;
             category?: string | undefined;
-            createdBy?: number | undefined;
+            createdBy?: string | undefined;
             tags?: string[] | undefined;
         } | undefined;
-        createdBy?: number | undefined;
-        updatedBy?: number | undefined;
+        createdBy?: string | undefined;
+        updatedBy?: string | undefined;
         offset?: number | undefined;
         tags?: string[] | undefined;
         content?: string | undefined;
@@ -975,17 +1015,17 @@ declare const KbNodesRequestPayloadSchema: z.ZodObject<{
         query?: string | undefined;
         title?: string | undefined;
         category?: string | undefined;
-        userId?: number | undefined;
+        userId?: string | undefined;
         limit?: number | undefined;
         filters?: {
             type?: "query" | "user" | "global" | undefined;
             query?: string | undefined;
             category?: string | undefined;
-            createdBy?: number | undefined;
+            createdBy?: string | undefined;
             tags?: string[] | undefined;
         } | undefined;
-        createdBy?: number | undefined;
-        updatedBy?: number | undefined;
+        createdBy?: string | undefined;
+        updatedBy?: string | undefined;
         offset?: number | undefined;
         tags?: string[] | undefined;
         content?: string | undefined;
@@ -998,17 +1038,17 @@ declare const KbNodesRequestPayloadSchema: z.ZodObject<{
         query?: string | undefined;
         title?: string | undefined;
         category?: string | undefined;
-        userId?: number | undefined;
+        userId?: string | undefined;
         limit?: number | undefined;
         filters?: {
             type?: "query" | "user" | "global" | undefined;
             query?: string | undefined;
             category?: string | undefined;
-            createdBy?: number | undefined;
+            createdBy?: string | undefined;
             tags?: string[] | undefined;
         } | undefined;
-        createdBy?: number | undefined;
-        updatedBy?: number | undefined;
+        createdBy?: string | undefined;
+        updatedBy?: string | undefined;
         offset?: number | undefined;
         tags?: string[] | undefined;
         content?: string | undefined;
@@ -1280,6 +1320,715 @@ 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 */
+    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.
+     */
+    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;
+    /**
+     * 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.
+     */
+    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;
+}
+
+/**
+ * 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.
+ */
+
+/**
+ * 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).
+ */
+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;
+}
+/**
+ * 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.
+ */
+interface PromoteToVerifiedInput {
+    sourceIds: string[];
+    tables: string[];
+    parentId?: string;
+    forkDepth?: number;
+    forkReason?: 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[];
+    /**
+     * Get a recipe by ID — returns drafts as well as verified scripts.
+     * Used by MainAgent and the promotion path.
+     */
+    get(id: string): ScriptRecipe | null;
+    /**
+     * Number of verified recipes (matches `getAll().length`).
+     */
+    count(): number;
+    /**
+     * Save a recipe (create or update).
+     * File is named after the script: "order-status-distribution.json"
+     */
+    save(recipe: ScriptRecipe): 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.
+     */
+    saveDraft(input: SaveDraftInput): ScriptRecipe;
+    /**
+     * 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.
+     */
+    recordDraftError(recipeId: string, err: {
+        phase: 'compile' | 'runtime' | 'timeout' | 'ipc';
+        message: string;
+        attempt: number;
+    }): void;
+    /**
+     * 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.
+     */
+    promoteToVerified(recipeId: string, input: PromoteToVerifiedInput): ScriptRecipe | null;
+    /**
+     * 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.
+     */
+    discardDraft(recipeId: string): void;
+    /**
+     * Delete a recipe by ID.
+     */
+    delete(id: string): void;
+    /**
+     * Record a successful execution for a recipe.
+     */
+    recordSuccess(id: string): void;
+    /**
+     * Record a failed execution for a recipe.
+     */
+    recordFailure(id: string): void;
+    /**
+     * Get the failure rate for a recipe (0 to 1).
+     * Returns 0 if the recipe has fewer than 5 total uses.
+     */
+    getFailureRate(id: string): number;
+    private ensureLoaded;
+    /**
+     * Convert a script name to a safe filename.
+     * "Order Status Distribution" → "order-status-distribution"
+     */
+    private toFileName;
+    /**
+     * 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)
+     */
+    private loadAllFromDisk;
+    /**
+     * 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.
+     */
+    private saveRecipeToDisk;
+    /**
+     * Delete a recipe's files from disk (both metadata + body, plus any legacy file).
+     */
+    private deleteRecipeFromDisk;
+}
+
+/**
+ * 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;
@@ -1434,16 +2183,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
@@ -1626,12 +2365,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
      */
@@ -2331,17 +3078,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 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;
     /**
@@ -2349,12 +3109,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;
     /**
@@ -2374,12 +3138,39 @@ 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;
+    /**
+     * 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;
+    /**
+     * 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 token
+     */
+    setQueryData(queryId: string, data: any): void;
     /**
      * Stop cleanup interval (for graceful shutdown)
      */
@@ -2387,6 +3178,52 @@ 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;
+
 type MessageTypeHandler = (message: IncomingMessage) => void | Promise<void>;
 declare class SuperatomSDK {
     private ws;
@@ -2403,6 +3240,7 @@ declare class SuperatomSDK {
     private collections;
     private components;
     private tools;
+    private workflows;
     private anthropicApiKey;
     private groqApiKey;
     private geminiApiKey;
@@ -2410,6 +3248,9 @@ declare class SuperatomSDK {
     private llmProviders;
     private databaseType;
     private modelStrategy;
+    private mainAgentModel;
+    private sourceAgentModel;
+    private dashCompModels?;
     private conversationSimilarityThreshold;
     private userManager;
     private dashboardManager;
@@ -2457,9 +3298,11 @@ declare class SuperatomSDK {
      */
     private handleMessage;
     /**
-     * Send a message to the Superatom service
+     * Send a message to the Superatom service.
+     * Returns true if the message was sent, false if the WebSocket is not connected.
+     * Does NOT throw on closed connections — callers can check the return value if needed.
      */
-    send(message: Message): void;
+    send(message: Message): boolean;
     /**
      * Register a message handler to receive all messages
      */
@@ -2507,6 +3350,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'
@@ -2537,4 +3393,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 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, openaiLLM, queryCache, rerankChromaResults, rerankConversationResults, userPromptErrorLogger };