@superatomai/sdk-node 0.0.52-dsp → 0.0.52-mds

package/dist/index.d.mts

@@ -1,1073 +1,15 @@
 import { z } from 'zod';
 import Anthropic from '@anthropic-ai/sdk';
 
-/**
- * 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[];
-    /**
-     * What the user explicitly asked the output to LOOK like, set by a display
-     * edit ("show that as a bar chart", "make the bars horizontal").
-     *
-     * Deliberately SEPARATE from `components`. Those are validated bindings that
-     * must be cleared on a data edit — after "break it down by brand" the axis
-     * keys are wrong, and after "use the mode" the stored title still says
-     * "Average…". A rendering CHOICE, by contrast, is still valid afterwards.
-     * Keeping them in one field meant every data edit silently discarded the
-     * user's chart type.
-     *
-     * Fed to the component generator as a hint whenever specs are (re)generated,
-     * so the chosen rendering comes back even after the SQL changes.
-     */
-    displayPreference?: ScriptDisplayPreference;
-    /**
-     * 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;
-    };
-    /** userId who committed the most recent edit (audit trail — recipes are project-scoped). */
-    editedBy?: string;
-    /** The instruction that produced the current version. */
-    editedFrom?: string;
-    /**
-     * Prior versions, newest last. The body itself is archived on disk as
-     * `<fileBase>.v<version>.ts`; this records what changed and who did it.
-     */
-    history?: ScriptVersionRecord[];
-}
-/**
- * A durable, user-stated rendering choice for a recipe. Survives data edits.
- */
-interface ScriptDisplayPreference {
-    /** Component types the user's chosen rendering resolved to, e.g. ["DynamicBarChart"]. */
-    componentTypes: string[];
-    /** The instruction itself — carries nuance the types can't ("horizontal", "sorted descending"). */
-    instruction: string;
-    /** ISO timestamp of the display edit that set this. */
-    at: string;
-}
-/** One superseded version of a recipe body (see ScriptStore.commitEdit). */
-interface ScriptVersionRecord {
-    /** Version number this record superseded (i.e. the OLD version). */
-    version: number;
-    /** ISO timestamp of the edit that superseded it. */
-    at: string;
-    /** userId who made the edit, when known. */
-    by?: string;
-    /** The edit instruction that caused the supersede. */
-    instruction?: string;
-    /** One-line summary of what changed, for the version picker. */
-    changeSummary?: string;
-    /** sha256 of the superseded body — pairs with `<fileBase>.v<version>.ts`. */
-    bodyHash?: string;
-}
-interface ScriptParameter {
-    /** Parameter name (used in script body as params.name) */
-    name: string;
-    /** Parameter type */
-    type: 'string' | 'number' | 'date' | 'date_range' | 'enum' | 'boolean';
-    /** Whether this parameter is required */
-    required: boolean;
-    /** Default value if not provided */
-    default?: any;
-    /** For enum type — maps user-facing values to internal values */
-    enumValues?: Record<string, string>;
-    /** Human-readable description (used in the matcher LLM prompt) */
-    description: string;
-}
-/**
- * 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[];
-    /** Program-generated narrative, when the script exports getAnalysis. */
-    analysis?: AnalysisOutput;
-    /**
-     * getAnalysis threw. `success` stays true — the data is valid, so the caller
-     * falls back to LLM prose rather than losing the answer.
-     */
-    analysisError?: string;
-    /** Program-generated component specs, when the script exports getComponents. */
-    components?: ScriptComponentSpec[];
-    /**
-     * getComponents threw or returned a non-array. `success` stays true — the data
-     * is valid, so the caller falls back to the recipe's stored specs and then to
-     * LLM generation rather than losing the dashboard.
-     */
-    componentsError?: string;
-    /** 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.
- * - 'edit': the user is INSTRUCTING a change to the script that produced the
- *   previous answer (not asking a new question). Only reachable when the turn
- *   carries a ScriptBinding — without one the matcher coerces it to 'none', so
- *   a prompt regression can't turn this into a loose similarity path. The
- *   runtime runs MainAgent in edit mode and commits the result in place.
- *   See backend/docs/SCRIPT-EDIT-DESIGN.md.
- * - 'none': no script is relevant; full agent flow runs.
- */
-type MatchTier = 'high' | 'near' | 'edit' | 'none';
-/**
- * Which recipe produced the answer the user is currently looking at.
- *
- * Set whenever a turn's answer came from a script (replay, fresh authoring, or
- * a committed edit) and carried on the UIBlock + saved conversation row. Two
- * consumers:
- *  1. The matcher — the 'edit' tier is ONLY reachable when a binding exists, so
- *     "use mode instead of mean" resolves to a concrete script instead of being
- *     matched on keywords it shares with no script name.
- *  2. Cache invalidation — after an edit commits, conversations bound to that
- *     recipeId must be dropped, or the exact-match cache replays the pre-edit
- *     answer and the edit looks like a no-op.
- *
- * See backend/docs/SCRIPT-EDIT-DESIGN.md § Component 1.
- */
-interface ScriptBinding {
-    recipeId: string;
-    /**
-     * The recipe's own version number at the moment THIS turn ran — not
-     * necessarily the recipe's current version. A later edit bumps the live
-     * version, so without this a past turn's binding would silently point at
-     * whatever the recipe looks like today instead of what actually produced
-     * that answer. Absent on bindings created before this field existed.
-     */
-    version?: number;
-    /** Params the script ran with — the edit's starting point. */
-    params: Record<string, any>;
-    /** Recipe name at bind time (matcher catalog + user-facing confirmation). */
-    name: string;
-    /** Columns the last run returned — grounds the editor without a re-query. */
-    columns?: string[];
-    /**
-     * The question that produced this answer. Required for disambiguation when a
-     * thread ran several scripts — without it the candidates are just names and
-     * the matcher cannot resolve "use the mode for the WSP one".
-     */
-    userPrompt?: string;
-    /**
-     * The polished analysis text this script actually produced last time it ran
-     * (the same programAnswer Thread.getConversationContext() shows elsewhere).
-     * Carried alongside the script's own shape (columns, params) so the matcher
-     * sees "what did this script actually say" right next to "what can I ask it
-     * to change", instead of needing a separate conversation-history transcript
-     * that would otherwise just repeat the same question this block already
-     * states. This is why ScriptMatcher's own prompt no longer receives a raw
-     * conversation-history transcript at all — this field is what replaced it.
-     */
-    answerSummary?: string;
-}
-/**
- * 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>;
-    /**
-     * Proper nouns the question named, VERBATIM, with the parameter each fills.
-     *
-     * The matcher must NOT resolve these itself. Observed live: it substituted the
-     * customer name "PREMER ENRGES PHOTOOTAIC" into an id parameter believing that
-     * "the runtime will resolve the customer name to its PartyId(s)" — nothing on
-     * the replay path does, and `WHERE BillingPartyId IN (PREMER ENRGES
-     * PHOTOOTAIC)` reached SQL. Reported here, the runtime resolves them before
-     * replay and rejects the match when one cannot be resolved.
-     */
-    mentions?: Array<{
-        text: string;
-        param?: string;
-    }>;
-    /** Business concepts the question relies on (e.g. "outstanding balance"). */
-    entityTypes?: string[];
-    /** 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;
-    /**
-     * Which HALF of the recipe the edit targets (tier='edit'). A recipe has two
-     * independently editable halves:
-     *  - 'data'    — the scriptBody: how the rows are produced (aggregation,
-     *                filters, joins, grouping). Runs MainAgent in edit mode.
-     *  - 'display' — the component specs: how those SAME rows are shown (chart
-     *                type, orientation, columns, labels). Replays the proven SQL
-     *                and regenerates the specs — never authors a script.
-     * Defaults to 'data' when the matcher omits it.
-     */
-    editTarget?: 'data' | 'display';
-    /**
-     * Self-contained restatement of the change the user asked for (tier='edit').
-     * MUST have pronouns/deixis resolved ("this", "it", "that column") — the edit
-     * prompt never sees the conversation history, so an unresolved instruction is
-     * unusable downstream.
-     */
-    editInstruction?: string;
-    /** Why the matcher made this choice (for logs and telemetry) */
-    reasoning?: string;
-}
-
-/**
- * script-ipc.ts — Protocol definitions for parent/child IPC.
- *
- * Transport: newline-delimited JSON over the child's stdin/stdout.
- * stderr is passed through for uncaught exceptions and compile errors.
- *
- * See backend/docs/SCRIPT-FLOW-IMPLEMENTATION.md § IPC Bridge.
- */
-
-/**
- * What getAnalysis returns. `analysis` is the narrative and `summary` the short
- * bullets the markdown block binds to — siblings over one dataset, never a
- * summary OF the narrative. See backend/docs/ANALYSIS-AS-PROGRAM-DESIGN.md § 4.3.
- */
-interface AnalysisOutput {
-    analysis?: string;
-    summary?: string[];
-    method?: string;
-}
-
-/**
- * StreamBuffer - Buffered streaming utility for smoother text delivery
- * Batches small chunks together and flushes at regular intervals
- */
-type StreamCallback = (chunk: string) => void;
-/**
- * StreamBuffer class for managing buffered streaming output
- * Provides smooth text delivery by batching small chunks
- */
-declare class StreamBuffer {
-    private buffer;
-    private flushTimer;
-    private callback;
-    private fullText;
-    constructor(callback?: StreamCallback);
-    /**
-     * 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;
-    /** `signal` fires when the user hits Stop mid-query — passed through to the backend's SourceTool.fn. */
-    fn: (input: any, signal?: AbortSignal) => 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[];
-        /** Bounded summary over the FULL fetched result (complete structure). */
-        _summary?: any;
-        /** Up to MAIN_AGENT_COMPLETE_ROWS rows — the complete result when small. */
-        _mainAgentRows?: any[];
-    };
-    outputSchema?: any;
-    sourceSchema?: string;
-    sourceType?: string;
-}
-
-/**
- * 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[];
-    /** Entity-level semantic summary (what the table means) — for main-agent routing. */
-    summary?: 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 — bounded to MAIN_AGENT_COMPLETE_ROWS (Stage 2: what the LLM
-     *  sees verbatim in its own prompt). NOT render-sized — do not bind a UI
-     *  component's dataset to this field; use renderData instead. */
-    data: any[];
-    /** Result data rows bounded to MAX_ROWS_RENDERED (Stage 3: render-appropriate).
-     *  This is what already-fetched (Stage 1, <=MAX_ROWS_FETCHED) rows look like
-     *  before Stage 2 further truncates `data` down for the LLM's own context —
-     *  use this, not `data`, whenever binding a UI component's dataset. */
-    renderData: 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>;
-}
-/**
- * Set when this turn applies a user-directed edit to an existing script instead
- * of authoring a new one. MainAgent keeps the SAME harness (tools, loop,
- * write_script/execute_script verification) and swaps only the system prompt —
- * `agent-main-edit` instead of `agent-main`.
- *
- * The two framings contradict each other on whether to query a source first, so
- * they must never be resident in one rendered prompt.
- * See backend/docs/SCRIPT-EDIT-DESIGN.md § D3.
- */
-interface EditContext {
-    /** Recipe being edited — the shadow draft records it as parentId. */
-    recipeId: string;
-    parentName: string;
-    parentBody: string;
-    /** Self-contained restatement of the change (from the matcher). */
-    instruction: string;
-    /** Columns the last run returned — grounds the edit without a re-query. */
-    lastResultColumns?: string[];
-    /** Rendered parameter list of the parent, for the prompt. */
-    parentParams?: string;
-}
-/**
- * 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;
-    /**
-     * Program-generated narrative when the script exported getAnalysis. `text`
-     * already carries `analysis.analysis`; this also exposes `summary`, which
-     * the markdown block binds to instead of being an LLM summary of the prose.
-     */
-    analysis?: AnalysisOutput;
-    /** 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;
-    /** Failed execute_script tool_result texts this turn, in order — see RunTrace.script.failedAttempts. */
-    failedScriptAttempts?: string[];
-    /**
-     * 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;
-    /**
-     * Validated component specs the agent authored via `write_components`.
-     * When present the caller assembles the dashboard from these instead of
-     * running the component-generation LLM. Absent when the agent didn't call
-     * the tool — the caller then falls back to `generateScriptComponents`.
-     * See backend/docs/COMPONENT-GENERATION-V2.md §2.2.
-     */
-    componentSpecs?: ScriptComponentSpec[];
-    /** Layout title/description from the same `write_components` call. */
-    componentLayout?: {
-        title: string;
-        description?: string;
-    };
-}
-/**
- * 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;
-    }>;
-    /** The tool_result JSON MainAgent's LLM got back from execute_script — see RunTrace.script.executionResult. */
-    executionResult?: string;
-}
-/**
- * Debug trace for a single chat_agent turn — which KB/schema nodes were
- * retrieved and considered, and which script (if any) produced the answer.
- * Persisted separately from the answer itself (fusion-5's
- * `conversation_traces` table, written via `saveTrace`), never sent through
- * `analyticsClient` (data-residency — see design doc §5).
- */
-interface RunTrace {
-    version: 1;
-    kbNodes: {
-        /**
-         * Always-on nodes included regardless of the question (getGlobalKnowledgeBase).
-         * `content` is the node's full text AS IT WAS at retrieval time — captured so a
-         * later edit/delete of the KB node doesn't erase what the LLM actually saw.
-         */
-        global: Array<{
-            kbId: string;
-            title: string;
-            content?: string;
-        }>;
-        /** Semantically matched for this specific question (getKnowledgeBase). Same `content` reasoning as above. */
-        query: Array<{
-            kbId: string;
-            title: string;
-            similarity?: number;
-            content?: string;
-        }>;
-    };
-    schemaNodes: {
-        /** MainAgent's cross-source prefilter — which sources were even considered. */
-        routing: Array<{
-            sourceId: string;
-            sourceName?: string;
-            similarity: number;
-        }>;
-        /** SourceAgent-scope per-source table resolution (MainAgent.preResolveSchema). */
-        preResolve: Array<{
-            sourceId: string;
-            table?: string;
-            description?: string;
-            similarity: number;
-        }>;
-        /**
-         * The exact {{SOURCE_SUMMARIES}} text injected into MainAgent's system prompt
-         * (agent-prompt-builder.ts's formatSummariesForPrompt output) — every
-         * registered source's catalog entry, not retrieval-specific, captured once per
-         * turn. This is what the main agent actually saw when deciding which source(s)
-         * to call.
-         */
-        mainAgentCatalog?: string;
-        /**
-         * One entry per SourceAgent dispatch (a source called twice in one turn gets
-         * two entries) — the exact {{FULL_SCHEMA}} text injected into that
-         * SourceAgent's own system prompt, however it was sourced, plus any
-         * search_schema follow-up lookups it made mid-conversation when the schema
-         * shown wasn't enough.
-         */
-        sourceAgentSchemas: Array<{
-            sourceId: string;
-            sourceName?: string;
-            /**
-             * The exact intent text this dispatch's own prompt was built from —
-             * captured in SourceAgent.buildPrompt, so it ALREADY includes the
-             * resolved-entities and resolved-concepts blocks MainAgent appends by
-             * code before calling execute() (see buildResolvedEntitiesBlock /
-             * buildResolvedConceptsBlock) — not just what the LLM itself wrote.
-             */
-            intent: string;
-            /** How `schemaText` was sourced — see SourceAgent.buildPrompt's fullSchema fallback chain. */
-            method: 'preresolved-embedding' | 'tool-full-schema' | 'tool-description' | 'none';
-            schemaText: string;
-            /** In call order — each search_schema tool call this SourceAgent made, and the exact result text handed back to its own LLM. */
-            searchSchemaLookups: Array<{
-                keywords: string[];
-                result: string;
-            }>;
-            /** The tool_result text MainAgent's LLM read back for this dispatch (formatResultForMainAgent output). */
-            result?: string;
-            /**
-             * The full resolved-concept bodies this dispatch's intent was built
-             * with (the same content already baked into `intent` via
-             * buildResolvedConceptsBlock, surfaced here structured/separately so a
-             * trace reader doesn't have to parse it back out of the raw text).
-             * Stamped AFTER execute() resolves — same timing as `result` above —
-             * specifically so its presence here is proof the concepts were part
-             * of the prompt actually sent, not just of what MainAgent intended to
-             * send before the call happened.
-             */
-            resolvedConcepts?: Array<{
-                name: string;
-                kind: string;
-                body: string;
-            }>;
-        }>;
-    };
-    /** The script that produced this answer, if any. Null for a general (no-tool) answer. */
-    script: {
-        /** True when an existing recipe was replayed unchanged (ScriptMatcher tier='high'). */
-        reused: boolean;
-        recipeId?: string | null;
-        body?: string | null;
-        /** Set when reused — the matcher's reasoning for picking this recipe. */
-        reasoning?: string | null;
-        /** The winning execute_script tool_result text. Only set when reused=false — a replay never re-runs execute_script. Failed attempts aren't kept. */
-        executionResult?: string | null;
-        /** Failed execute_script tool_result texts this turn, in order (before the winning one, if any). */
-        failedAttempts?: string[];
-    } | null;
-    /**
-     * Everything ScriptMatcher.match() built and sent to its one LLM call this
-     * turn — Step 2 of the request flow, immediately after Step 1's exact-match
-     * check misses. Captured even when short-circuited before any LLM call, or
-     * when the call itself errored, so "why didn't this reuse a script" can
-     * always be answered from the trace alone, not just the outcome in `script`.
-     * See backend/docs/user-prompt-req-flow/SCRIPT-MATCH-IMPROVEMENTS.md.
-     */
-    scriptMatcher: {
-        /**
-         * Exactly what went INTO the one LLM call — every placeholder value
-         * substituted into `.prompts/script-match/system.md`, plus the routing
-         * facts (isExplicitEdit, the two counts) that aren't literal prompt text
-         * but explain WHY the catalog/active-script blocks look the way they do.
-         */
-        sent: {
-            /** Whether the raw prompt carried the explicit "edit :" prefix (see parseEditPrefix). */
-            isExplicitEdit: boolean;
-            /** The prefix-stripped question actually shown to the LLM (the USER_PROMPT placeholder). */
-            userPrompt: string;
-            /** The Edit Signal text handed to the LLM this turn (CONFIRMED/NOT CONFIRMED wording). */
-            editSignal: string;
-            /** The rendered "Scripts From Your Past Questions" catalog text (SCRIPT_CATALOG placeholder). */
-            scriptCatalog: string;
-            /** Distinct scripts actually in scriptCatalog, after health-filtering and the MAX_CATALOG_RECIPES cap. */
-            catalogRecipeCount: number;
-            /** The rendered "EDITABLE SCRIPTS" block text (ACTIVE_SCRIPT placeholder) — '' when the thread has no active bindings. */
-            activeScript: string;
-            /** Active bindings offered as edit candidates this turn. */
-            activeBindingCount: number;
-        };
-        /**
-         * Everything that came back OUT — the LLM's raw answer plus what the
-         * runtime decided to do with it. `tier` here is the FINAL tier after
-         * every coercion (near→none, the edit-prefix gate, candidate checks) —
-         * it can legitimately differ from `rawResponse.tier`.
-         */
-        received: {
-            /** False when short-circuited before any LLM call (no catalog match AND no active bindings) — `rawResponse`/`tier` below don't apply. */
-            calledLLM: boolean;
-            /** The raw JSON the LLM returned, when calledLLM is true and the call didn't throw. */
-            rawResponse?: any;
-            /** Set when calledLLM is true and the call threw, or the response named an unknown script id. */
-            error?: string;
-            /** Final tier after ALL coercions. Null when short-circuited, errored, or the call/coercions landed on no match. */
-            tier: MatchTier | null;
-        };
-    } | null;
-    /**
-     * `resolve_entities` tool activity this turn (see main-agent.ts's
-     * RESOLVE_ENTITIES_TOOL_DEF / handleResolveEntities) — names/identifiers the
-     * user mentioned, resolved to database ids before any SQL was written.
-     * Absent/empty entirely for a project with no entity-search collection
-     * registered, or a turn that named nothing.
-     */
-    entityResolution: {
-        /**
-         * The entity-type catalog text injected into MainAgent's system prompt
-         * (loadEntityCatalog's output) — what let the LLM name a concept instead
-         * of guessing the project's vocabulary. Captured once per turn.
-         */
-        catalogText?: string;
-        /**
-         * One entry per `resolve_entities` tool call this turn (a turn can call it
-         * more than once) — the FULL raw response from the entity-search
-         * collection, not just the trimmed {mention,entityType,instanceId,
-         * displayName} MainAgent keeps for itself to build the dispatch block.
-         * `score`/`ambiguous`/`alternatives` only exist here, nowhere else.
-         */
-        calls: Array<{
-            mentions: Array<{
-                text: string;
-                entityType?: string;
-            }>;
-            entityTypes: string[];
-            resolved: Array<{
-                mention: string;
-                entityType: string;
-                instanceId: string;
-                displayName: string;
-                attrs?: Record<string, any>;
-                score?: number;
-                ambiguous?: boolean;
-                alternatives?: Array<{
-                    instanceId: string;
-                    displayName: string;
-                    score: number;
-                }>;
-            }>;
-            unresolved: string[];
-            entityMap: Record<string, any>;
-            unmatchedEntityTypes?: Array<{
-                requested: string;
-                candidates?: string[];
-            }>;
-            /** Set when the collection call itself failed (fails open — see handleResolveEntities). */
-            error?: string;
-            /** Set on an early return (unavailable / nothing named) so the call is still visible in the trace, not indistinguishable from never having run. */
-            note?: string;
-        }>;
-    };
-    /**
-     * The prior-turn conversation context injected into this turn's prompt as
-     * CONVERSATION_HISTORY — exactly what each flow already builds for itself
-     * (chat: thread.getConversationContext(); report/dashboard: their own
-     * equivalents), captured as-is. Every call site sets this unconditionally
-     * (empty string '' when there's no prior context — new thread, or history
-     * trimmed to nothing), so an empty turn is visibly "no history" in the
-     * saved trace rather than a silently missing key. Optional only because
-     * traces saved before this field existed won't have it at all.
-     */
-    conversationHistory?: string;
-    /**
-     * The exact {{USER_ACCESS_CONTEXT}} text injected into MainAgent's system
-     * prompt — the per-user authorization config (sa-api users.config)
-     * rendered by buildUserAccessContext, as-is. Captured once (MainAgent's
-     * prompt is what SourceAgent's identical value is derived from — no need
-     * to duplicate it per source dispatch). Set unconditionally (empty string
-     * '' when there's no config for this user), so "no restrictions" is
-     * visible in the saved trace rather than a silently missing key. Optional
-     * only because traces saved before this field existed won't have it.
-     */
-    userAccessContext?: string;
-}
-/**
- * Configuration for the multi-agent system.
- * Controls limits, models, and behavior.
- */
-interface AgentConfig {
-    /** Max rows shown to the UI preview / inlined per source (default: 10) */
-    maxRowsPerSource: number;
-    /**
-     * Max rows a source query may FETCH from the DB server-side (default: 2000).
-     * Decoupled from what the main agent is shown: the full result is fetched and
-     * summarized (bounded), but only a small/complete slice enters LLM context.
-     * This lets small lookups (benchmark maps) arrive COMPLETE without letting
-     * large results blow up context.
-     */
-    maxRowsFetched: number;
-    /** Model for the main agent (routing + analysis in one LLM call) */
-    mainAgentModel: string;
-    /** Model for source agent query generation */
-    sourceAgentModel: string;
-    /** API key for LLM calls */
-    apiKey?: string;
-    /** Max retry attempts per source agent */
-    maxRetries: number;
-    /** Max tool calling iterations for the main agent loop */
-    maxIterations: number;
-    /** Global knowledge base context (static, same for all users/questions — cached in system prompt) */
-    globalKnowledgeBase?: string;
-    /** Per-request knowledge base context (user-specific + query-matched — dynamic, not cached) */
-    knowledgeBaseContext?: string;
-    /** Per-user authorization config (sa-api users.config), rendered to text — see buildUserAccessContext */
-    userAccessContext?: string;
-    /** Collections registry (ChromaDB search hooks) for embedding-based schema + source search */
-    collections?: any;
-    /** Optional project ID for scoping embedding searches */
-    projectId?: string;
-    /**
-     * Optional debug-trace accumulator for this turn (Phase 1, chat_agent only).
-     * When present, MainAgent-scope retrieval call sites (e.g. preResolveSchema)
-     * push their structured results into it. Absent for callers that don't care
-     * about trace capture (e.g. headless flows) — every push site must treat
-     * this as optional and never let a capture failure affect the real answer.
-     */
-    trace?: RunTrace;
-}
-/**
- * Default agent configuration
- */
-declare const DEFAULT_AGENT_CONFIG: AgentConfig;
-
 /**
  * Unified UIBlock structure for database storage
- * Used in both bookmarks and user-conversations tables.
- *
- * `analysis` always holds whatever real narration exists — the full answer on
- * success, or whatever was actually streamed before a failure (may be empty).
- * `error` is a dedicated field, null on success — it can be a plain string OR
- * a structured object/array (e.g. the agent's raw `errors` list), whatever
- * shape the failure naturally has; it's never coerced into `analysis`.
+ * Used in both bookmarks and user-conversations tables
  */
 interface DBUIBlock {
     id: string;
     component: Record<string, any> | null;
     analysis: string | null;
     user_prompt: string;
-    error?: unknown | null;
-    /**
-     * The script recipe that produced this answer, when one did. Read back via
-     * `conversation-history.exactMatch` so an edit follow-up still has a target
-     * after a reload (the in-memory thread is gone by then), and indexed so
-     * committing an edit can purge every cached answer bound to the recipe.
-     */
-    scriptBinding?: {
-        recipeId: string;
-        params?: Record<string, any>;
-        name?: string;
-        columns?: string[];
-    };
 }
 
 /**
@@ -1218,7 +160,6 @@ declare const DSLRendererPropsSchema$1: z.ZodObject<{
             dependencies?: string[] | undefined;
         } | undefined;
         props?: Record<string, any> | undefined;
-        data?: Record<string, any> | undefined;
         render?: any;
         states?: Record<string, any> | undefined;
         methods?: Record<string, {
@@ -1229,6 +170,7 @@ declare const DSLRendererPropsSchema$1: z.ZodObject<{
             fn: string;
             deps?: string[] | undefined;
         }[] | undefined;
+        data?: Record<string, any> | undefined;
         pages?: {
             id: string;
             name: string;
@@ -1250,7 +192,6 @@ declare const DSLRendererPropsSchema$1: z.ZodObject<{
             dependencies?: string[] | undefined;
         } | undefined;
         props?: Record<string, any> | undefined;
-        data?: Record<string, any> | undefined;
         render?: any;
         states?: Record<string, any> | undefined;
         methods?: Record<string, {
@@ -1261,6 +202,7 @@ declare const DSLRendererPropsSchema$1: z.ZodObject<{
             fn: string;
             deps?: string[] | undefined;
         }[] | undefined;
+        data?: Record<string, any> | undefined;
         pages?: {
             id: string;
             name: string;
@@ -1286,7 +228,6 @@ declare const DSLRendererPropsSchema$1: z.ZodObject<{
             dependencies?: string[] | undefined;
         } | undefined;
         props?: Record<string, any> | undefined;
-        data?: Record<string, any> | undefined;
         render?: any;
         states?: Record<string, any> | undefined;
         methods?: Record<string, {
@@ -1297,6 +238,7 @@ declare const DSLRendererPropsSchema$1: z.ZodObject<{
             fn: string;
             deps?: string[] | undefined;
         }[] | undefined;
+        data?: Record<string, any> | undefined;
         pages?: {
             id: string;
             name: string;
@@ -1322,7 +264,6 @@ declare const DSLRendererPropsSchema$1: z.ZodObject<{
             dependencies?: string[] | undefined;
         } | undefined;
         props?: Record<string, any> | undefined;
-        data?: Record<string, any> | undefined;
         render?: any;
         states?: Record<string, any> | undefined;
         methods?: Record<string, {
@@ -1333,6 +274,7 @@ declare const DSLRendererPropsSchema$1: z.ZodObject<{
             fn: string;
             deps?: string[] | undefined;
         }[] | undefined;
+        data?: Record<string, any> | undefined;
         pages?: {
             id: string;
             name: string;
@@ -1413,7 +355,6 @@ declare const DSLRendererPropsSchema: z.ZodObject<{
             dependencies?: string[] | undefined;
         } | undefined;
         props?: Record<string, any> | undefined;
-        data?: Record<string, any> | undefined;
         render?: any;
         states?: Record<string, any> | undefined;
         methods?: Record<string, {
@@ -1424,6 +365,7 @@ declare const DSLRendererPropsSchema: z.ZodObject<{
             fn: string;
             deps?: string[] | undefined;
         }[] | undefined;
+        data?: Record<string, any> | undefined;
     }, {
         id: string;
         name?: string | undefined;
@@ -1437,7 +379,6 @@ declare const DSLRendererPropsSchema: z.ZodObject<{
             dependencies?: string[] | undefined;
         } | undefined;
         props?: Record<string, any> | undefined;
-        data?: Record<string, any> | undefined;
         render?: any;
         states?: Record<string, any> | undefined;
         methods?: Record<string, {
@@ -1448,6 +389,7 @@ declare const DSLRendererPropsSchema: z.ZodObject<{
             fn: string;
             deps?: string[] | undefined;
         }[] | undefined;
+        data?: Record<string, any> | undefined;
     }>;
     data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
     context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
@@ -1465,7 +407,6 @@ declare const DSLRendererPropsSchema: z.ZodObject<{
             dependencies?: string[] | undefined;
         } | undefined;
         props?: Record<string, any> | undefined;
-        data?: Record<string, any> | undefined;
         render?: any;
         states?: Record<string, any> | undefined;
         methods?: Record<string, {
@@ -1476,6 +417,7 @@ declare const DSLRendererPropsSchema: z.ZodObject<{
             fn: string;
             deps?: string[] | undefined;
         }[] | undefined;
+        data?: Record<string, any> | undefined;
     };
     data?: Record<string, any> | undefined;
     context?: Record<string, any> | undefined;
@@ -1493,7 +435,6 @@ declare const DSLRendererPropsSchema: z.ZodObject<{
             dependencies?: string[] | undefined;
         } | undefined;
         props?: Record<string, any> | undefined;
-        data?: Record<string, any> | undefined;
         render?: any;
         states?: Record<string, any> | undefined;
         methods?: Record<string, {
@@ -1504,6 +445,7 @@ declare const DSLRendererPropsSchema: z.ZodObject<{
             fn: string;
             deps?: string[] | undefined;
         }[] | undefined;
+        data?: Record<string, any> | undefined;
     };
     data?: Record<string, any> | undefined;
     context?: Record<string, any> | undefined;
@@ -1919,10 +861,6 @@ interface SuperatomSDKConfig {
     bundleDir?: string;
     promptsDir?: string;
     databaseType?: DatabaseType;
-    /** BCP-47 locale for `fmt` in generated analyses, e.g. 'en-IN', 'en-US'. Defaults to 'en-IN'. */
-    locale?: string;
-    /** ISO-4217 currency for `fmt`, e.g. 'INR', 'USD'. Defaults to 'INR'. */
-    currency?: string;
     ANTHROPIC_API_KEY?: string;
     GROQ_API_KEY?: string;
     GEMINI_API_KEY?: string;
@@ -1966,6 +904,13 @@ interface SuperatomSDKConfig {
      * Default: 5 minutes
      */
     queryCacheTTL?: number;
+    /**
+     * Byte budget for cached query results, in MB.
+     * The cache evicts least-recently-used entries to stay under it, so a long TTL
+     * cannot grow the process until the host kills it. Keep it well below the
+     * process memory limit. Default: 1024 MB
+     */
+    queryCacheMaxMB?: number;
     /**
      * Dashboard conversation history TTL (Time To Live) in minutes
      * Per-dashboard conversation histories expire after this duration
@@ -2070,7 +1015,7 @@ declare const KbNodesRequestPayloadSchema: z.ZodObject<{
         content?: string | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    operation: "create" | "getOne" | "search" | "update" | "delete" | "getAll" | "getByCategory" | "getByUser" | "getCategories" | "getTags";
+    operation: "create" | "getOne" | "update" | "delete" | "getAll" | "search" | "getByCategory" | "getByUser" | "getCategories" | "getTags";
     data?: {
         id?: number | undefined;
         type?: "query" | "user" | "global" | undefined;
@@ -2093,7 +1038,7 @@ declare const KbNodesRequestPayloadSchema: z.ZodObject<{
         content?: string | undefined;
     } | undefined;
 }, {
-    operation: "create" | "getOne" | "search" | "update" | "delete" | "getAll" | "getByCategory" | "getByUser" | "getCategories" | "getTags";
+    operation: "create" | "getOne" | "update" | "delete" | "getAll" | "search" | "getByCategory" | "getByUser" | "getCategories" | "getTags";
     data?: {
         id?: number | undefined;
         type?: "query" | "user" | "global" | undefined;
@@ -2364,347 +1309,292 @@ declare class ReportManager {
      */
     updateReport(reportId: string, report: DSLRendererProps): DSLRendererProps | null;
     /**
-     * Delete a report
-     * @param reportId - Report ID
-     * @returns True if deleted, false if not found
+     * Delete a report
+     * @param reportId - Report ID
+     * @returns True if deleted, false if not found
+     */
+    deleteReport(reportId: string): boolean;
+    /**
+     * Check if a report exists
+     * @param reportId - Report ID
+     * @returns True if report exists, false otherwise
+     */
+    reportExists(reportId: string): boolean;
+    /**
+     * Get report count
+     * @returns Number of reports
+     */
+    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."
      */
-    deleteReport(reportId: string): boolean;
+    whenToUse: string;
     /**
-     * Check if a report exists
-     * @param reportId - Report ID
-     * @returns True if report exists, false otherwise
+     * 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',
+     * }
+     * ```
      */
-    reportExists(reportId: string): boolean;
+    propsSchema: Record<string, string>;
     /**
-     * Get report count
-     * @returns Number of reports
+     * 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.
      */
-    getReportCount(): number;
+    defaultProps?: Record<string, any>;
 }
-
 /**
- * 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).
+ * The workflow selection captured during a routing call.
+ * Set on AgentResponse when the LLM picks a workflow tool.
  */
-
-/** One recipe's metadata as stored in Postgres (mirrors the script_recipes table). */
-interface ScriptRecipeMetaRow {
-    id: string;
-    projectId?: string | null;
-    version: number;
+interface SelectedWorkflow {
+    /** Component name (matches WorkflowDescriptor.name) */
     name: string;
-    intentDescription: string;
-    tags: string[] | null;
-    createdFrom: string | null;
-    sourceIds: string[] | null;
-    tables: string[] | null;
-    parameters: ScriptParameter[] | null;
-    components?: ScriptComponentSpec[] | null;
-    displayPreference?: ScriptDisplayPreference | 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;
-    editedBy?: string | null;
-    editedFrom?: string | null;
-    history?: ScriptVersionRecord[] | 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>;
-    /**
-     * Commit a verified edit onto an EXISTING recipe: bump `version`, replace the
-     * body-bearing metadata, append a history record, reset health counters, and
-     * clear the component specs (they were validated against the old shape).
-     * Returns the updated row, or null when the target is gone.
-     * See backend/docs/SCRIPT-EDIT-DESIGN.md § Component 5.
-     */
-    commitEdit?(id: string, patch: {
-        name?: string;
-        intentDescription?: string;
-        tags?: string[];
-        parameters?: ScriptParameter[];
-        bodyHash: string;
-        /** New on-disk stem when the edit renamed the script; omitted otherwise. */
-        fileBase?: string;
-        sourceIds?: string[];
-        tables?: string[];
-        editedBy?: string;
-        editedFrom?: string;
-        historyEntry: {
-            version: number;
-            at: string;
-            by?: string;
-            instruction?: string;
-            changeSummary?: string;
-            bodyHash?: string;
-        };
-    }): 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>;
+    /** Props extracted from the prompt + merged with workflow.defaultProps */
+    props: Record<string, any>;
 }
-/** 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.
+ * The complete response from the multi-agent system.
+ * Contains everything needed for text display + component generation.
  */
-
-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;
-    /**
-     * Set when this draft is a SHADOW of an existing recipe being edited. The
-     * draft is verified independently and merged back onto the parent via
-     * `commitEdit`, so the working script is never clobbered by an edit that
-     * turns out not to run. See backend/docs/SCRIPT-EDIT-DESIGN.md § D5.
-     */
-    parentId?: 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;
-}
-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>;
-    /**
-     * Fetch one recipe by id, pinned to a SPECIFIC past version rather than
-     * whatever is live today. Needed to render a past turn's conversation
-     * history accurately after the script has since been edited — get() alone
-     * always returns the CURRENT body, which may no longer be what that turn
-     * actually ran.
-     *
-     * Returns null (never a silently-wrong version) when the requested version
-     * isn't the current one and its archived body can't be found — e.g. the
-     * archive was cleaned up after the whole recipe was later deleted.
-     */
-    getVersion(id: string, version: number): 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>;
-    /**
-     * Commit a user-directed edit: merge a VERIFIED shadow draft back onto the
-     * recipe it was editing, as version N+1 under the SAME recipe id.
-     *
-     * Keeping the id stable is the point of the whole feature — every cached
-     * conversation, `script_dataset` regeneration descriptor and persisted
-     * component spec already points at it, so the correction applies retroactively
-     * to replays instead of stranding them on the old body.
-     *
-     * Steps (see backend/docs/SCRIPT-EDIT-DESIGN.md § Component 5):
-     *  1. archive the current body as `<fileBase>.v<version>.ts`
-     *  2. write the edited body to the original fileBase (atomic)
-     *  3. version++, copy name/description/params, append a history record
-     *  4. reset health counters — the pre-edit failure history is stale
-     *  5. clear component specs — they were validated against the OLD shape
-     *  6. delete the shadow draft (row + file)
-     *
-     * Returns the updated recipe, or null when the commit could not be applied
-     * (caller should then fall back to treating the draft as a new script).
-     */
-    commitEdit(targetId: string, draft: {
-        recipeId: string;
-        name?: string;
-        intentDescription?: string;
-        tags?: string[];
-        parameters?: ScriptParameter[];
-        scriptBody: string;
-        sourceIds?: string[];
-        tables?: string[];
-    }, meta: {
-        instruction?: string;
-        changeSummary?: string;
-        editedBy?: string;
-    }): 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;
-    /**
-     * Attach getComponents to the recipe body. The stored `components` column is
-     * cleared at promotion (see promoteToVerified): once the body computes its own
-     * specs, a stale spec array beside a live program is how the wrong one gets
-     * read later. See backend/docs/COMPONENTS-AS-PROGRAM-DESIGN.md § 4.4.
-     */
-    attachComponents(recipeId: string, componentsBody: string): Promise<boolean>;
-    /**
-     * Append (or replace) the `getAnalysis` export on an existing draft body.
-     *
-     * The narrative is authored AFTER execution, so it lands on a file that
-     * already holds a working getData — rewriting the whole body would risk
-     * losing the query that just succeeded. Replaces any earlier getAnalysis so
-     * a retry does not stack duplicate exports.
-     */
-    attachAnalysis(recipeId: string, analysisBody: string): Promise<boolean>;
-    private bodyPath;
-    private readBody;
-    /** Directory holding superseded bodies. Dot-prefixed so IDEs/`ls` hide it. */
-    private get archiveDir();
-    /**
-     * Archive a superseded body as `.versions/<fileBase>.v<n>.ts`.
-     *
-     * Kept out of the main store directory on purpose — see commitEdit step 1.
-     * To roll back: copy the file back over `scripts-store/<fileBase>.ts`.
-     */
-    private writeArchive;
+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[];
     /**
-     * Move a recipe's archived versions to a new prefix when its fileBase changes,
-     * so all versions of one recipe stay grouped. Without this, two renames would
-     * scatter a single recipe's history across three prefixes in `.versions/` with
-     * nothing linking them back to the live script.
+     * 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.
      */
-    private renameArchives;
-    /** Atomic body write (temp + rename) so concurrent reads never see a partial file. */
-    private writeBody;
-    private unlinkBody;
+    workflow?: SelectedWorkflow;
+}
+/**
+ * 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;
 }
+/**
+ * Default agent configuration
+ */
+declare const DEFAULT_AGENT_CONFIG: AgentConfig;
 
 /**
  * Main Agent (Orchestrator)
@@ -2726,85 +1616,7 @@ declare class MainAgent {
     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;
-    /** Answer-flow component catalog (filtered + projected by the caller). */
-    private componentCatalog;
-    /** Specs accepted by `write_components` this turn; empty until it succeeds. */
-    /**
-     * Entities resolved this turn, appended verbatim to every source dispatch.
-     *
-     * Not left to the model to copy into its intent prose: observed live, the
-     * MainAgent wrote names instead of ids on the first dispatch AND re-spelled
-     * 'F D C LIMITED' as 'FDC Limited', so the source agent fell back to
-     * `PartyName LIKE '%FDC%'` and found 2 of 3 customers. Carrying the ids
-     * structurally makes that impossible rather than instruction-dependent.
-     */
-    private resolvedEntities;
-    /**
-     * Concept bodies resolved this turn (via resolve_entities' embedded concept
-     * lookup or a standalone resolve_concepts call) — retained the same way as
-     * resolvedEntities above, so they can be attached to the SourceAgent dispatch.
-     *
-     * Without this, a concept resolved HERE (MainAgent's own tool loop) never
-     * reaches SourceAgent at all: SourceAgent only gets the natural-language
-     * `intent` MainAgent writes, which is a paraphrase, not the concept's
-     * verbatim, authoritative body. Deduped on name so a mid-turn re-resolve
-     * doesn't repeat an already-attached concept.
-     */
-    private resolvedConcepts;
-    private componentSpecs;
-    private componentLayout;
-    private renderComponentAttempts;
-    /** Same repeated-violation tracking as ScriptState.lastAnalysisViolationTexts, for write_components. */
-    private lastComponentsViolationTexts;
-    /**
-     * Fork mode — set when this turn is adapting a near-matching parent script.
-     * In fork mode there is no legitimate "answer with bare text" outcome: the
-     * only correct first move is a tool call (write_script, or a source tool for
-     * schema discovery). We therefore force tool use on the first LLM iteration
-     * so the model can't end its turn with a bare "I'll adapt…" preamble and zero
-     * tool calls. Never set on the fresh-authoring / general-question path.
-     */
-    private forkMode;
-    /**
-     * Edit mode — set when this turn applies a user-directed change to an
-     * existing script. Swaps the system prompt to `agent-main-edit` and stamps
-     * the shadow draft's parentId. Like fork mode there is no legitimate
-     * "answer with bare text" outcome, so tool use is forced on iteration 1.
-     * See backend/docs/SCRIPT-EDIT-DESIGN.md § Component 4.
-     */
-    private editContext;
-    /** The recipe's durable rendering choice — see the constructor. */
-    private displayPreference;
-    /**
-     * Per-turn cancellation signal (user hit "Stop"). Set at the top of
-     * handleQuestion and read by the tool handler, the SourceAgent dispatch, and
-     * the script subprocess so an abort tears down every layer of the turn.
-     */
-    private abortSignal?;
-    constructor(externalTools: ExternalTool[], config: AgentConfig, scriptStore?: ScriptStore, turnId?: string, streamBuffer?: StreamBuffer, workflows?: WorkflowDescriptor[], forkMode?: boolean, editContext?: EditContext, componentCatalog?: Component[], 
-    /**
-     * The recipe's durable rendering choice, when it has one. A DATA edit
-     * re-authors getComponents from scratch, so without this the user's chart
-     * type is silently dropped whenever anyone changes the SQL.
-     */
-    displayPreference?: {
-        componentTypes: string[];
-        instruction: string;
-    });
-    /** True when the turn is applying a user-directed script edit. */
-    private get editMode();
-    private get scriptingEnabled();
+    constructor(externalTools: ExternalTool[], config: AgentConfig, streamBuffer?: StreamBuffer, workflows?: WorkflowDescriptor[]);
     /**
      * Handle a user question using the multi-agent system.
      *
@@ -2815,175 +1627,7 @@ declare class MainAgent {
      * 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, signal?: AbortSignal): Promise<AgentResponse>;
-    /**
-     * Tool definition, with the catalog rendered from the registered `Metadata`
-     * the caller passed in. Generated rather than hand-written so it cannot drift
-     * from what the frontend actually ships.
-     */
-    private buildWriteComponentsToolDef;
-    /**
-     * Validate the agent's component picks against the REAL columns of each bound
-     * dataset. All-or-nothing: any error rejects the whole call and returns the
-     * findings, because a partially-accepted dashboard makes the retry ambiguous.
-     */
-    private validateSpecs;
-    /**
-     * Author the dashboard as a program. Attaches getComponents to the draft, runs
-     * it over the verified rows, then validates the specs it RETURNED — the program
-     * is never trusted because it is a program, exactly as an authored spec is not.
-     */
-    private handleWriteComponents;
-    /**
-     * Author the answer as a program. Runs after execute_script, so the body is
-     * written with the result already known and can react to what it found.
-     *
-     * Rejects a body that types numbers rather than computing them — see
-     * analysis-lint. A hardcoded figure is worse than prose: it freezes into the
-     * recipe and replays unchanged while the data moves underneath it.
-     */
-    private handleWriteAnalysis;
-    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;
-    /**
-     * Which declared parameter NAMES never actually appear wired into the
-     * script body — checked as plain text, not a real parser, so it only
-     * catches the worst case (completely unreferenced) rather than every
-     * subtler variant (e.g. used for display text while the SQL itself still
-     * hardcodes the value). That worst case is exactly what's been observed:
-     * a parameter declared purely for show, with the actual filter hardcoded.
-     * Accepts `params.name`, `params['name']`/`params["name"]`, and a
-     * destructuring binding (`const { name } = params`) as valid wiring.
-     */
-    private findUnwiredParams;
-    /**
-     * 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).
-     */
-    /**
-     * Ids + verbatim names for everything resolved this turn, appended by CODE to
-     * each source dispatch so neither omission nor re-spelling by the model can
-     * lose them. Empty string when nothing was resolved, so intents are untouched
-     * for questions that name no entities.
-     *
-     * Also appends `attrs.scopeSql` when the resolved instance carries one —
-     * same "guaranteed by code" reasoning as the ids/names above, extended to
-     * the one attrs field with a documented, cross-entity-type meaning: a
-     * ready-made SQL predicate an entity's index precomputed (see
-     * ENTITY-SEARCH-DESIGN.md's hierarchy-broadening pattern — branch/region/
-     * state entity types attach it so a lane/route question never needs its
-     * own city-matching join). Confirmed real cost of not doing this: a
-     * branch/state resolved with scopeSql sat unused while the source agent
-     * spent 4 failed exploratory queries rediscovering the exact same
-     * branch-id list by hand (Invalid column name 'StateName'/'CityId'/
-     * 'OrganizationLocationId', in that order, ~144s, before landing on ids
-     * that were sitting in scopeSql from the very first resolve_entities
-     * call). Other attrs (code, counts, etc.) are not dumped here — they are
-     * descriptive, not actionable the way a precomputed predicate is, and
-     * bloating every dispatch with all of them for no clear gain isn't worth
-     * it; scopeSql is the one thing worth this guarantee today.
-     */
-    private buildResolvedEntitiesBlock;
-    /** Dedupe-and-retain helper shared by resolveConceptsForTurn and handleResolveConcepts. */
-    private retainResolvedConcepts;
-    /**
-     * Same purpose as buildResolvedEntitiesBlock, for concept bodies instead of
-     * entity ids — appended to the dispatch intent so SourceAgent's own,
-     * independent LLM call receives the resolved definitions verbatim rather
-     * than only MainAgent's paraphrased intent text.
-     */
-    private buildResolvedConceptsBlock;
-    /** True when the backend registered the entity-search collection. */
-    private get entitySearchEnabled();
-    /** True when the backend registered the concepts collection. */
-    private get conceptsEnabled();
-    /**
-     * Concept names for the system prompt. Names ONLY — the body comes back from
-     * resolve_concepts once the LLM has named one, exactly as with the entity
-     * catalog. Putting bodies here would rebuild the always-on context problem
-     * concepts exist to solve.
-     *
-     * Not cached, for the same reason loadEntityCatalog isn't: unchanged rows
-     * render byte-identical text so the prompt-cache prefix still hits, and a
-     * process cache would only buy a window where a new concept is invisible.
-     */
-    private loadConceptCatalog;
-    /**
-     * The ALWAYS-INJECTED tier: preconditions no question is semantically close
-     * to — date encodings, valid-row filters. These cannot be retrieval-gated.
-     * "What was revenue last quarter?" has no similarity to "dates are DD/MM/YYYY
-     * text", so leaving them to be requested means they are silently dropped and
-     * the answer is confidently wrong rather than visibly missing.
-     *
-     * Bodies ARE included here — unlike the catalog — because there is nothing to
-     * request: being unrequestable is what makes them invariants.
-     *
-     * Also retained into resolvedConcepts (same as an explicit resolve_concepts
-     * call) so these bodies reach SourceAgent's dispatch too — an invariant is
-     * meant to apply everywhere, not just wherever the model happens to ask for
-     * something whose `requires` chain reaches it.
-     */
-    private loadConceptInvariants;
-    /**
-     * Resolve the concepts for a turn, with a SERVER-SIDE FLOOR.
-     *
-     * Pinning a tool guarantees it is called; it does not guarantee the model
-     * fills in the arguments. Observed: a question containing the exact words
-     * "revenue forecast" produced a call with no concepts at all, and the agent
-     * then used an incomplete copy of the formula from the knowledge base — the
-     * resulting query filtered a customer id against a project column and
-     * returned zero rows on every attempt.
-     *
-     * So when the model names nothing, scan the question itself for catalog names
-     * and aliases on word boundaries. Precise (a literal name is evidence, not a
-     * guess) and asymmetric in the safe direction: an unneeded definition costs a
-     * few hundred ignorable tokens, a missing one costs a wrong answer.
-     */
-    /**
-     * Returns the tool-facing fields to spread into the resolve_entities JSON
-     * response, PLUS a `_trace` field with everything the trace needs that the
-     * model does not (asked/viaFloor/unmatched). Callers must pull `_trace` out
-     * before spreading the rest into what the model sees — see handleResolveEntities.
-     */
-    private resolveConceptsForTurn;
-    /**
-     * Never throws: a concept-store outage must degrade to "no definition found"
-     * and leave the agent deriving the formula as it does today, not take the
-     * whole answer down.
-     */
-    private handleResolveConcepts;
-    /**
-     * Compact catalog (type + gloss) for the system prompt. This is what lets the
-     * LLM NAME a concept instead of guessing at our vocabulary — it can infer
-     * that a question is about unpaid money, but not that we call that
-     * `outstanding-balance`. Full `resolution` detail is fetched by the tool.
-     *
-     * Deliberately NOT cached in-process. The token cost is already handled by
-     * prompt caching (the system prompt carries a cache_control breakpoint), and
-     * re-reading a tiny PK-ordered table costs ~nothing. Fetching fresh does not
-     * weaken the prompt cache either: unchanged data renders byte-identical text,
-     * so the prefix still hits. A process cache would only buy a staleness window
-     * in which a newly indexed entity is invisible to the agent.
-     */
-    private loadEntityCatalog;
-    /**
-     * Never throws: a resolver outage must degrade to "nothing resolved" and
-     * leave the agent exactly as it was, not take the whole answer down.
-     */
-    private handleResolveEntities;
-    private preResolveSchema;
+    handleQuestion(userPrompt: string, apiKey?: string, conversationHistory?: string, streamCallback?: (chunk: string) => void): Promise<AgentResponse>;
     /**
      * Execute a direct tool — call fn() with LLM-provided params, no SourceAgent.
      */
@@ -3051,43 +1695,6 @@ interface LLMOptions {
     apiKey?: string;
     baseURL?: string;
     partial?: (chunk: string) => void;
-    /**
-     * Per-request cancellation. When the caller aborts this signal (user hit
-     * "Stop"), the underlying provider request is cancelled and the call throws
-     * a RequestAbortedError. Threaded into the provider `messages.create` request
-     * options and checked between tool-loop iterations. Currently honored on the
-     * Anthropic path (the agent flow's default provider).
-     */
-    signal?: AbortSignal;
-    /**
-     * Forces a tool call on the FIRST iteration of streamWithTools only
-     * (subsequent iterations revert to auto). Used by fork mode to stop the
-     * model from ending its turn with a bare "I'll adapt the script…" preamble
-     * and zero tool calls. `{ type: 'any' }` lets the model pick which tool
-     * (write_script in the common case, a source tool for schema discovery);
-     * `{ type: 'tool', name }` pins a specific tool. Honored on both the
-     * Anthropic path and the OpenAI/OpenRouter path (mapped to OpenAI's
-     * tool_choice: 'required' / a named function).
-     */
-    firstIterationToolChoice?: {
-        type: 'any';
-    } | {
-        type: 'tool';
-        name: string;
-    };
-    /**
-     * Internal — set only by the OpenRouter wrappers when the target is a Claude
-     * model. Tells the OpenAI-wire path to emit Anthropic `cache_control`
-     * breakpoints (OpenRouter forwards them to Anthropic for prompt caching).
-     * Never set for direct OpenAI/Groq calls, so their requests are unchanged.
-     */
-    _openrouterClaudeCaching?: boolean;
-    /**
-     * Internal — OpenRouter provider-routing preferences (forwarded as the
-     * `provider` body field). Set by the OpenRouter wrappers to steer routing to
-     * a fast backend (e.g. {sort:'throughput'}). Never set for direct OpenAI/Groq.
-     */
-    _openrouterProvider?: Record<string, unknown>;
 }
 interface Tool {
     name: string;
@@ -3140,41 +1747,15 @@ declare class LLM {
      * (e.g. "claude-sonnet-4.5"). OpenRouter slugs drop the date suffix and use dotted versions.
      */
     private static _toOpenRouterSlug;
-    /**
-     * Per-provider proxy base URL. Returns `${SUPERATOM_LLM_PROXY_URL}/<provider>`
-     * when our Cloudflare LLM proxy is configured, else undefined (→ talk to the
-     * provider directly, legacy behaviour). An explicit options.baseURL (e.g.
-     * OpenRouter) always wins and is never overridden. See backend/docs/llm-proxy.md.
-     */
-    private static _proxyBaseURL;
     private static _openrouterOptions;
-    private static _isRetryableProviderError;
-    private static _withOpenrouterRetry;
     private static _openrouterText;
     private static _openrouterStream;
     private static _openrouterStreamWithTools;
-    /**
-     * Build an Anthropic client. Routes through our Cloudflare LLM proxy when
-     * SUPERATOM_LLM_PROXY_URL is set (each client ships a per-client proxy key as
-     * ANTHROPIC_API_KEY and never holds the real key); otherwise talks to
-     * api.anthropic.com directly. See backend/docs/llm-proxy.md.
-     */
-    private static _anthropicClient;
-    /** True when OpenRouter is configured as a fail-open fallback for Claude. */
-    private static _openrouterAvailable;
-    /** Remap an Anthropic model id to the OpenRouter model path for fail-open. */
-    private static _anthropicFallbackModel;
     private static _anthropicText;
     private static _anthropicStream;
     private static _anthropicStreamWithTools;
     private static _groqText;
     private static _groqStream;
-    /**
-     * Gemini request options carrying the proxy base URL, or undefined → talk to
-     * generativelanguage.googleapis.com directly. The Google SDK takes baseUrl as a
-     * per-model request option, not a constructor arg. See backend/docs/llm-proxy.md.
-     */
-    private static _geminiRequestOptions;
     private static _geminiText;
     private static _geminiStream;
     /**
@@ -3183,28 +1764,8 @@ declare class LLM {
      */
     private static _cleanSchemaForGemini;
     private static _geminiStreamWithTools;
-    /** True for Anthropic/Claude model ids — gates OpenRouter prompt caching. */
-    private static _isClaudeModel;
-    /**
-     * Build the OpenAI-wire system message. For OpenRouter + Claude
-     * (cacheClaude=true) it emits content parts carrying Anthropic
-     * `cache_control` breakpoints (preserving any the caller set, else marking
-     * the last block), so OpenRouter forwards them to Anthropic for prompt
-     * caching. Otherwise it returns a plain flattened string — unchanged for
-     * direct OpenAI/Groq.
-     */
-    private static _openaiSystemMessage;
-    /**
-     * Split an OpenAI-wire usage object. `prompt_tokens` INCLUDES cached tokens,
-     * so we subtract them out (Anthropic-style: input excludes cache reads) and
-     * report cached separately — this makes calculateCost price cache reads at
-     * the discounted rate and reflects OpenRouter prompt-cache savings in logs.
-     */
-    private static _openaiUsage;
     private static _openaiText;
     private static _openaiStream;
-    /** Map the Anthropic-style firstIterationToolChoice to OpenAI's tool_choice. */
-    private static _openaiToolChoice;
     private static _openaiStreamWithTools;
     /**
      * Parse JSON string, handling markdown code blocks and surrounding text
@@ -3306,13 +1867,6 @@ declare class UIBlock {
     private textResponse;
     private actions;
     private createdAt;
-    /**
-     * Which script recipe produced this answer, when a script did. Read on the
-     * NEXT turn so the user can say "use mode instead" and have the matcher
-     * resolve it to a concrete script (the `edit` tier is unreachable without it).
-     * See backend/docs/SCRIPT-EDIT-DESIGN.md § Component 1.
-     */
-    private scriptBinding;
     /**
      * Creates a new UIBlock instance
      * @param userQuestion - The user's question or input
@@ -3321,8 +1875,11 @@ declare class UIBlock {
      * @param actions - Optional array of available actions
      * @param id - Optional custom ID, generates UUID if not provided
      * @param textResponse - Optional text response from LLM
+     * @param createdAt - Optional original timestamp. Needed when a block is rebuilt from
+     *   storage: conversation context is ordered by this, so defaulting to now would make
+     *   a restored turn look newer than the live one.
      */
-    constructor(userQuestion: string, componentData?: Record<string, any>, generatedComponentMetadata?: Record<string, any>, actions?: Action[], id?: string, textResponse?: string | null);
+    constructor(userQuestion: string, componentData?: Record<string, any>, generatedComponentMetadata?: Record<string, any>, actions?: Action[], id?: string, textResponse?: string | null, createdAt?: Date);
     /**
      * Get the UIBlock ID
      */
@@ -3404,22 +1961,9 @@ declare class UIBlock {
      * Clear all actions
      */
     clearActions(): void;
-    /** The program-generated half of the answer — see setProgramAnswer. */
-    programAnswer?: string | null;
     /**
-     * Bind this block to the script recipe that produced its answer.
-     */
-    setScriptBinding(binding: Record<string, any> | null): void;
-    /**
-     * The program-generated half of the answer, kept verbatim so a reload can
-     * replace exactly that text without disturbing the streamed narration.
-     */
-    setProgramAnswer(text: string | null): void;
-    getProgramAnswer(): string | null;
-    /**
-     * The script recipe bound to this block, if any.
+     * Get creation timestamp
      */
-    getScriptBinding(): Record<string, any> | null;
     getCreatedAt(): Date;
     /**
      * Convert UIBlock to JSON-serializable object
@@ -3427,6 +1971,14 @@ declare class UIBlock {
     toJSON(): Record<string, any>;
 }
 
+/** One stored turn, as a host's conversation collection hands it back. */
+interface HydratedTurn {
+    id: string;
+    userQuestion?: string;
+    textResponse?: string | null;
+    componentMetadata?: Record<string, any>;
+    createdAt?: Date | string;
+}
 /**
  * Thread represents a conversation thread containing multiple UIBlocks
  * Each UIBlock in a thread represents a user question and assistant response pair
@@ -3435,6 +1987,7 @@ declare class Thread {
     private id;
     private uiblocks;
     private createdAt;
+    private hydrated;
     /**
      * Creates a new Thread instance
      * @param id - Optional custom ID, generates UUID if not provided
@@ -3448,6 +2001,14 @@ declare class Thread {
      * Add a UIBlock to the thread
      */
     addUIBlock(uiblock: UIBlock): void;
+    /**
+     * Rebuild past turns from storage so a thread survives a restart or a new session.
+     * Once only, and never over a block already held: anything in memory is the live
+     * copy and may carry state the stored row does not.
+     */
+    hydrate(turns: HydratedTurn[]): number;
+    /** Whether hydration has already been attempted, successful or not. */
+    isHydrated(): boolean;
     /**
      * Get a UIBlock by ID
      */
@@ -3487,40 +2048,7 @@ declare class Thread {
      * @param currentUIBlockId - ID of current UIBlock to exclude from context (optional)
      * @returns Formatted conversation history string
      */
-    /**
-     * The script recipe bound to the most recent completed UIBlock — i.e. the
-     * script behind the answer the user is currently looking at. Drives the
-     * matcher's `edit` tier: without it, "use mode instead" has no target and
-     * falls through to regeneration.
-     * See backend/docs/SCRIPT-EDIT-DESIGN.md § Component 1.
-     */
-    getActiveScriptBinding(currentUIBlockId?: string): Record<string, any> | null;
-    /**
-     * The recent script-backed answers in this thread, newest first — the
-     * candidate set a user-directed edit can target.
-     *
-     * Returning several rather than only the newest is what lets an instruction
-     * name its own target ("use the mode for the WSP one"). With a single
-     * candidate every edit lands on the most recent script, which silently edits
-     * the wrong recipe whenever the user meant an earlier one.
-     *
-     * Deduped by recipeId (newest occurrence wins) so a long editing session on
-     * one script doesn't crowd out the others. Each entry carries the question
-     * that produced it — without that the candidates are indistinguishable.
-     *
-     * In-memory only: dies with the process. The caller falls back to the
-     * persisted bindings when this comes back empty.
-     * See backend/docs/SCRIPT-EDIT-DESIGN.md § Component 1.
-     */
-    getScriptBindings(limit?: number, currentUIBlockId?: string): Record<string, any>[];
-    /**
-     * @param getScriptBody Resolves a script-backed turn's EXACT script, pinned
-     * to the version that turn actually ran — never today's (possibly
-     * since-edited) live body. Owned by the caller (needs a ScriptStore, which
-     * Thread doesn't hold) — omit it and every turn falls back to the
-     * no-script summary below.
-     */
-    getConversationContext(limit?: number, currentUIBlockId?: string, getScriptBody?: (recipeId: string, version: number) => Promise<string | null>): Promise<string>;
+    getConversationContext(limit?: number, currentUIBlockId?: string): string;
     /**
      * Convert Thread to JSON-serializable object
      */
@@ -4182,7 +2710,7 @@ declare abstract class BaseLLM {
      * This helps provide intelligent suggestions for follow-up queries
      * For general/conversational questions without components, pass textResponse instead
      */
-    generateNextQuestions(originalUserPrompt: string, component?: Component | null, componentData?: Record<string, unknown>, apiKey?: string, conversationHistory?: string, textResponse?: string, signal?: AbortSignal): Promise<string[]>;
+    generateNextQuestions(originalUserPrompt: string, component?: Component | null, componentData?: Record<string, unknown>, apiKey?: string, conversationHistory?: string, textResponse?: string): Promise<string[]>;
 }
 
 interface AnthropicLLMConfig extends BaseLLMConfig {
@@ -4259,10 +2787,33 @@ declare class QueryCache {
     private cache;
     private ttlMs;
     private maxCacheSize;
+    private maxCacheBytes;
+    private currentBytes;
     private cleanupInterval;
     private readonly algorithm;
     private encryptionKey;
     constructor();
+    /**
+     * Set the byte budget for cached result data.
+     * @param megabytes - Budget in MB. Keep it well under the process memory limit.
+     */
+    setMaxBytes(megabytes: number): void;
+    /** Current estimated bytes held by the data cache. */
+    getCurrentBytes(): number;
+    /**
+     * Rough retained size of a result, in bytes.
+     *
+     * Sampled rather than exact: stringifying a multi-megabyte result on every set()
+     * would allocate the very memory this budget exists to protect. Estimated from a
+     * few rows of the largest array in the payload, at 2 bytes per UTF-16 char.
+     * Both error directions are safe — under-estimating evicts less than ideal,
+     * over-estimating evicts more, and a miss only re-runs the query.
+     */
+    private estimateBytes;
+    /** Largest array at the top level or one level in — where result rows live. */
+    private largestArray;
+    /** Drop least-recently-used entries until the budget is satisfied. */
+    private evictUntilUnderBudget;
     /**
      * Set the cache TTL (Time To Live)
      * @param minutes - TTL in minutes (default: 10)
@@ -4388,198 +2939,6 @@ declare class DashboardConversationHistory {
 }
 declare const dashboardConversationHistory: DashboardConversationHistory;
 
-/**
- * Whole-dashboard generation via Pi, a terminal coding agent — as opposed to
- * DASH_COMP_REQ's single-widget-at-a-time flow. Runs Pi in-process via its
- * SDK (createAgentSession), not as a subprocess: no shell, no argument
- * quoting, no stdin/stdout piping, none of the Windows-specific subprocess
- * issues that came with spawning the `pi` CLI directly.
- *
- * Called from sdk-nodejs/src/dashboardAgent/index.ts (DASHBOARD_AGENT_REQ),
- * which owns the generic streaming/abort machinery (mirrors USER_PROMPT_REQ)
- * and passes `signal`/`onProgress` alongside the normal params — this stays
- * within CollectionHandler's loose (params) => Promise<result> typing, no
- * change needed to that shared type.
- *
- * This mechanism is generic and reusable across any deployment. What's
- * genuinely project-specific — where AGENTS.md lives, which model to use —
- * is supplied via `DashboardAgentCollectionConfig`, with defaults sensible
- * enough that most callers don't need to override them (see below). The
- * data-source tool list and the dashboard's current state both come from
- * things sdk-nodejs already exposes generically: `sdk.getTools()` (whatever
- * this deployment registered via `sdk.setTools()`) and `sdk.callCollection
- * ('dashboards', 'query', ...)` (whatever this deployment already registered
- * under that name/shape) — no per-deployment callback needed for either.
- * Same convention on the way out: after a successful run, the prompt and the
- * full response text are handed to `sdk.callCollection('dashboard-agent-
- * conversations', 'create', ...)` if this deployment has registered one —
- * skipped silently otherwise, since conversation history is optional.
- *
- * Pi verifies every query against the live database itself (via whatever
- * local tool-execution bridge the deployment exposes, e.g. an HTTP bridge
- * on localhost), but does NOT persist the result itself — it writes the
- * finished DSL to an absolute path inside `runtimeDir`, told to it explicitly
- * in the prompt, and stops there. This handler reads that file after the run
- * finishes and returns its content as `dashboard` in the result. The caller
- * (frontend) is the one that actually saves it, via whatever authenticated
- * create/update path any other dashboard edit goes through — Pi has no user
- * session/auth context of its own, so persistence shouldn't happen from
- * inside it.
- *
- * Session persistence: the FIRST call for a dashboardId pays the full cost
- * (explore KB, discover schema, plan, verify, build). Every call after that
- * resumes the same session file (SessionManager.open) so Pi has everything
- * it already learned — it only needs to reason about the new, smaller ask,
- * not rediscover the whole dashboard from scratch. The session's file path
- * (AgentSession.sessionFile) is captured right after creation and persisted
- * in a small local file, keyed by dashboardId, inside `runtimeDir`.
- */
-interface DashboardAgentCollectionConfig {
-    /**
-     * Working directory Pi runs from — must contain AGENTS.md. This is a
-     * version-controlled prompt file, so `cwd` is expected to live somewhere
-     * like a `.prompts/` folder alongside the deployment's other prompts.
-     * Default: `<process.cwd()>/.prompts/dashboard-agent` — the same
-     * process.cwd()-based convention PromptLoader already uses for the main
-     * agent's prompts, which needs no explicit override in the common case
-     * (the backend process's own cwd already is its project root).
-     */
-    cwd?: string;
-    /**
-     * Where drafts/, the session-id map, and dashboard.log get written —
-     * separate from `cwd` deliberately, so this deployment's runtime state
-     * (regenerated per session, safe to gitignore) doesn't sit inside the
-     * same folder as the version-controlled AGENTS.md prompt.
-     * Default: `<process.cwd()>/.pi-dashboard-agent-runtime`.
-     */
-    runtimeDir?: string;
-    /** Model provider (default: process.env.PI_AGENT_PROVIDER || 'openrouter'). */
-    provider?: string;
-    /** Model id (default: process.env.PI_AGENT_MODEL || 'anthropic/claude-sonnet-4.5'). */
-    model?: string;
-    /**
-     * true (default): every request starts a brand-new pi session, with the 2
-     * most recent prior responses (if any) injected into the prompt as
-     * context — bounded cost per request, but pi re-explores schema/KB facts
-     * it already verified in an earlier turn on this same dashboard.
-     * false: resumes the same session file across requests on a given
-     * dashboard — pi keeps everything it already learned, but context (and
-     * cost) grows unbounded across turns (one observed turn: 2M+ cache-read
-     * tokens after a handful of edits on the same dashboard).
-     * Default: process.env.PI_AGENT_FRESH_SESSION !== 'false'.
-     */
-    freshSession?: boolean;
-}
-declare function registerDashboardAgentCollection(sdk: SuperatomSDK, config?: DashboardAgentCollectionConfig): void;
-
-/**
- * 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;
-    private collections?;
-    private userId?;
-    private trace?;
-    constructor(store: ScriptStore, opts?: {
-        collections?: any;
-        userId?: string;
-        trace?: RunTrace;
-    });
-    /**
-     * 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.
-     *
-     * Thin wrapper around `doMatch` whose only job is guaranteeing the trace
-     * capture happens exactly once, on every exit path (short-circuit, normal
-     * return, or the LLM call erroring) — see RunTrace.scriptMatcher.
-     */
-    match(userPrompt: string, apiKey?: string, model?: string, signal?: AbortSignal, activeBindings?: ScriptBinding[]): Promise<ScriptMatch | null>;
-    private doMatch;
-    /**
-     * Renders a recipe's declared parameters the same way in every prompt
-     * section (catalog, active-script, edit candidates) so the LLM sees one
-     * consistent format regardless of which block a script came from.
-     */
-    private formatParamList;
-    /**
-     * Semantic search over THIS user's own past prompts (`conversation-history`
-     * ChromaDB embeddings, already user-scoped) — not a project-wide name/tag
-     * search. Groups hits by the recipe that answered them, so a script gets
-     * ONE catalog entry carrying every matched past question, not one per hit.
-     *
-     * Scope is deliberate (see SCRIPT-MATCH-IMPROVEMENTS.md, Change 2): a
-     * script only shows up here because THIS user has, before, asked something
-     * similar that it answered — not because some other user's question did.
-     */
-    private searchPromptHistory;
-    /**
-     * Build the script catalog string for the LLM prompt from prompt-history
-     * matches: each script's declared parameters PLUS the actual past questions
-     * of this user's that it answered (real precedent, not a hand-written
-     * description) and what params they ran with.
-     */
-    private buildPromptHistoryCatalog;
-    /**
-     * The recent script-backed answers in this thread — the bounded set an edit
-     * may target. Rendered as its own prompt section (never merged into the
-     * ranked catalog) so the `edit` rules have an unambiguous referent set, and
-     * numbered newest-first so the prompt's "prefer the most recent when the
-     * instruction is ambiguous" tie-break has something to point at.
-     *
-     * Each entry carries the QUESTION that produced it plus the columns it
-     * returned — that is what lets the matcher resolve "use the mode for the WSP
-     * one" instead of blindly taking the newest.
-     */
-    private buildActiveScriptBlock;
-}
-
-/**
- * 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;
-    /**
-     * Per-turn cancellation signal. When the user hits "Stop" mid-run, the child
-     * process group is SIGKILLed and the run resolves as an aborted failure (the
-     * caller is already unwinding, so the result is discarded).
-     */
-    signal?: AbortSignal;
-}
-/**
- * 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;
@@ -4597,6 +2956,7 @@ declare class SuperatomSDK {
     private components;
     private tools;
     private workflows;
+    private registryWaiters;
     private anthropicApiKey;
     private groqApiKey;
     private geminiApiKey;
@@ -4615,8 +2975,6 @@ declare class SuperatomSDK {
     private lastPong;
     private readonly PING_INTERVAL_MS;
     private readonly PONG_TIMEOUT_MS;
-    private pendingOutbox;
-    private readonly MAX_OUTBOX_SIZE;
     constructor(config: SuperatomSDKConfig);
     /**
      * Initialize PromptLoader and load prompts into memory
@@ -4661,20 +3019,6 @@ declare class SuperatomSDK {
      * Does NOT throw on closed connections — callers can check the return value if needed.
      */
     send(message: Message): boolean;
-    /**
-     * Queue a message that couldn't be delivered because the socket was down,
-     * to be resent once it reconnects. Drops the oldest entry once the bound is
-     * hit — an outage long enough to fill this queue means the oldest queued
-     * responses are for requests the caller has likely already given up on.
-     */
-    private queuePendingMessage;
-    /**
-     * Resend everything queued while the socket was down, now that it's back
-     * up. Uses this.ws.send() directly (not send()) so a message that fails
-     * again goes back through queuePendingMessage() rather than being silently
-     * dropped a second time.
-     */
-    private flushPendingOutbox;
     /**
      * Register a message handler to receive all messages
      */
@@ -4714,14 +3058,6 @@ declare class SuperatomSDK {
      */
     private handlePong;
     private storeComponents;
-    /**
-     * The live, frontend-registered component catalog (name, type, description,
-     * and full prop schema per component) — the same authoritative source
-     * DASH_COMP_REQ's LLM prompt is built from. Exposed so other integrations
-     * (e.g. the dashboard-agent script bridge) can read real component
-     * contracts instead of maintaining a separate, driftable hand-written copy.
-     */
-    getComponents(): Component[];
     /**
      * Set tools for the SDK instance
      */
@@ -4730,16 +3066,6 @@ declare class SuperatomSDK {
      * Get the stored tools
      */
     getTools(): Tool$1[];
-    /**
-     * Call a registered collection operation in-process — no WebSocket
-     * round-trip, since the caller is already running inside this same SDK
-     * instance. Lets SDK-internal features (e.g. the dashboard agent) reuse
-     * whatever collection a deployment has already registered (e.g.
-     * 'dashboards'.'query') by name/convention, instead of requiring a
-     * separate callback purely to re-expose data a collection already serves.
-     * Throws if the collection or operation isn't registered.
-     */
-    callCollection<TResult = any>(collectionName: string, operation: string, params?: any): Promise<TResult>;
     /**
      * Register workflow components for the SDK instance.
      *
@@ -4749,6 +3075,19 @@ declare class SuperatomSDK {
      * the workflow component is returned directly, with the LLM-extracted props.
      */
     setWorkflows(workflows: WorkflowDescriptor[]): void;
+    /**
+     * Make sure the agent has a tool surface before answering a prompt.
+     *
+     * Components and workflows are pushed by the browser once per page load and
+     * kept only in memory, so a backend restart leaves both lists empty until
+     * someone reloads a tab. The agent still answers — with no workflows to route
+     * to and no components to render — which looks like a model regression rather
+     * than lost state. Ask the client to re-send instead, and proceed regardless
+     * so a stale or silent client degrades no worse than it does today.
+     */
+    private ensureRegistry;
+    /** Release anyone blocked in ensureRegistry() now that the list has arrived. */
+    private resolveRegistryWaiters;
     /**
      * Get the registered workflow components.
      */
@@ -4783,4 +3122,4 @@ declare class SuperatomSDK {
     getConversationSimilarityThreshold(): number;
 }
 
-export { type Action, type AgentConfig, type AgentResponse, BM25L, type BM25LOptions, type BaseLLMConfig, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CollectionHandler, type CollectionOperation, type DBUIBlock, DEFAULT_AGENT_CONFIG, type DashboardAgentCollectionConfig, 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, registerDashboardAgentCollection, rerankChromaResults, rerankConversationResults, resolveScriptRecipeStore, runScript, 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 };