@superatomai/sdk-node 0.0.56 → 0.0.57-dsp

package/dist/index.d.ts

@@ -1,15 +1,1262 @@
 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;
+    /**
+     * Restrictions an authorization policy injected into THIS query before it
+     * ran. Handed to getAnalysis/getComponents as `scope` so the answer can name
+     * the restriction without the recipe hardcoding a value that goes stale.
+     */
+    appliedPolicies?: string[];
+}
+/**
+ * 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.
+ */
+
+/**
+ * A name the user said, and what it resolved to.
+ *
+ * Handed to getAnalysis/getComponents so a narrative can NAME the thing the
+ * question was about without typing the name in. Before this, the runtime knew
+ * "Fusion5 Pty Ltd" and used that knowledge only to REJECT scripts that typed
+ * it — with no sanctioned way to obtain it, the only legal escape was to add a
+ * column to getData and re-run the query, spending an execute attempt to learn
+ * something the runtime already knew.
+ */
+interface ResolvedEntityRef {
+    /** The text the user actually wrote. */
+    mention: string;
+    entityType: string;
+    instanceId: string;
+    displayName: string;
+}
+/**
+ * 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[];
+        /**
+         * Set when an authorization policy restricted the query before it ran.
+         * Read by BOTH agents: the source agent's tool response and the main
+         * agent's result block, because the main agent is the one that writes the
+         * titles, analysis and method line that must state the restriction.
+         */
+        _ACCESS_POLICY_APPLIED?: string;
+    };
+    /**
+     * THIS call's rows, at render size — deliberately a sibling of `result`, not a
+     * field inside it, because `result` is the object that gets picked apart for
+     * prompts (`_sampleData`, `_mainAgentRows`, `_summary`). Never put these in a
+     * prompt.
+     *
+     * Exists because a SourceAgentResult keeps only the LAST query's rows for a
+     * whole dispatch (see main-agent's "a follow-up query overwrites result.data"
+     * note). A component bound to an EARLIER query therefore rendered the later
+     * query's data — confirmed live: a revenue chart and a budget chart both drew
+     * budget, because both queries ran through one tool.
+     */
+    renderRows?: 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;
+            }>;
+            /** This dispatch's `SourceToolInput.aggregation` ('raw' | 'pre-aggregate' | 'summary') — decides which AGGREGATION_MODE text this SourceAgent's own prompt got. */
+            aggregation?: string;
+            /** The exact DATABASE_RULES text this SourceAgent's own prompt got (promptLoader.loadDatabaseRulesForType). */
+            databaseRulesText?: string;
+            /** The exact ROW_LIMIT_SYNTAX text this SourceAgent's own prompt got. */
+            rowLimitSyntaxText?: string;
+            /** The exact SCHEMA_SEARCH_INSTRUCTIONS text this SourceAgent's own prompt got — the guidance, not the runtime searchSchemaLookups results above. */
+            schemaSearchInstructionsText?: string;
+            /** The literal tool definitions (query tool + search_schema tool, when offered) handed to this SourceAgent's own LLM.streamWithTools call. */
+            toolsSent?: any[];
+            /** This SourceAgent's own LLM.streamWithTools call config. */
+            callConfig?: {
+                model?: string;
+                maxTokens?: number;
+                temperature?: number;
+                maxIterations?: number;
+            };
+            /** The exact USER_ACCESS_CONTEXT text this SourceAgent's own prompt got — its own copy of the same value captured once at the turn level in userAccessContext. */
+            userAccessContextText?: string;
+        }>;
+    };
+    /**
+     * Concept-catalog activity this turn (see main-agent.ts's loadConceptCatalog /
+     * loadConceptInvariants / RESOLVE_CONCEPTS_TOOL_DEF). Parallel to
+     * `entityResolution` above. Absent/empty for a project with no concepts
+     * collection registered.
+     */
+    concepts: {
+        /** The exact {{CONCEPT_CATALOG}} text injected into MainAgent's system prompt (names + aliases only — bodies come back via resolve_concepts). */
+        catalogText?: string;
+        /** The exact {{CONCEPT_INVARIANTS}} text injected into MainAgent's system prompt — always-on, never requested by the LLM. Distinct from the resolved-concept bodies below, which mix invariants and explicitly-resolved concepts together. */
+        invariantsText?: string;
+        /** One entry per resolve_concepts-driven resolution this turn — explicit tool calls, resolve_entities-triggered concept lookups, and (for the dashboard flow) its own concept tool. */
+        calls: Array<{
+            via: 'resolve_concepts' | 'resolve_entities' | 'dashboard-agent';
+            asked?: string[];
+            implied?: string[];
+            returned?: Array<{
+                kind: string;
+                name: string;
+                returns?: any;
+                definition: string;
+                viaRequires?: boolean;
+            }>;
+            viaFloor?: string[];
+            corrected?: Array<{
+                asked: string;
+                matched: string;
+            }>;
+            unmatched?: string[];
+            suggestions?: string[];
+            error?: string;
+            note?: 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;
+            /** This call's LLM.stream config. */
+            model?: string;
+            maxTokens?: number;
+            temperature?: 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;
+    /**
+     * The exact per-user knowledge-base text injected into MainAgent's system
+     * prompt (getUserKnowledgeBase's output, folded into KNOWLEDGE_BASE_CONTEXT
+     * alongside the query-matched half already captured in kbNodes.query).
+     * Captured separately because it's a distinct fetch with no node-level
+     * structure to list, unlike kbNodes.
+     */
+    userKbContext?: string;
+    /** The literal tool definitions (source, direct, workflow, resolve_entities, resolve_concepts, write_script, execute_script, write_analysis, write_components — whichever were actually offered this turn) handed to MainAgent's LLM.streamWithTools call. */
+    toolsSent?: any[];
+    /** The exact {{DIRECT_TOOLS}} text injected into MainAgent's system prompt. */
+    directToolsText?: string;
+    /** The exact {{WORKFLOW_COMPONENTS}} text injected into MainAgent's system prompt. */
+    workflowsText?: string;
+    /** The exact {{SCRIPT_BODY_CONTRACT}} text injected into MainAgent's system prompt (promptLoader.loadScriptBodyContract). */
+    scriptBodyContractText?: string;
+    /**
+     * Full edit-mode context as sent to MainAgent this turn — every EditContext
+     * field, not just the instruction already folded into `script.reasoning`.
+     * Null for a non-edit turn.
+     */
+    editContext?: {
+        recipeId?: string;
+        parentName?: string;
+        parentBody?: string;
+        instruction?: string;
+        lastResultColumns?: string[];
+        parentParams?: string;
+    } | null;
+    /**
+     * The fork-mode preamble as actually assembled and prepended to the user
+     * prompt (agent-user-response.ts) — parentBody/gaps/modificationHint as
+     * sent, plus the lineage fields also written to the script store separately
+     * (parentRecipeId/forkDepth/forkReason). Null for a non-fork turn.
+     */
+    forkContext?: {
+        parentBody?: string;
+        gaps?: string;
+        modificationHint?: string;
+        parentRecipeId?: string;
+        forkDepth?: number;
+        forkReason?: string;
+    } | null;
+    /** The write_analysis tool call's analysisBody argument this turn, when called. */
+    writeAnalysisBody?: string;
+    /** The write_components tool call's componentsBody argument this turn, when called. */
+    writeComponentsBody?: string;
+    /**
+     * Component-generation/re-authoring activity this turn — one entry per call
+     * to `authorComponentsProgram` (script-component-generator.ts — the
+     * display-edit path, reauthoring getComponents as a program),
+     * `generateScriptComponents` (the script-replay fallback, spec/analysis-based
+     * generation), or `summarizeToMarkdown` (its own small analysis-summary LLM
+     * call, reached via `assembleComponentsFromSpecs`). A turn can hit more than
+     * one of these across its fallback chain, so this is an array, not a
+     * singleton — same pattern as `concepts.calls`/`entityResolution.calls`.
+     */
+    componentGen: Array<{
+        via: 'authorComponentsProgram' | 'generateScriptComponents' | 'summarizeToMarkdown';
+        /** authorComponentsProgram only: the edit instruction driving the re-author. */
+        instruction?: string;
+        /** authorComponentsProgram only: the component body being revised, before this attempt. */
+        currentBody?: string;
+        /** Dataset shapes/schemas the LLM was shown (both generation paths, different derivation). */
+        datasetShapes?: string;
+        /** The component catalog text/list handed to the LLM. */
+        componentCatalog?: string;
+        /** generateScriptComponents only: source name(s) shown (SOURCE_NAME). */
+        sourceName?: string;
+        /** generateScriptComponents only: row count(s) shown (ROW_COUNT). */
+        rowCount?: string;
+        /** generateScriptComponents only: column descriptions text shown. */
+        columnDescriptions?: string;
+        /** generateScriptComponents/summarizeToMarkdown: the analysis text handed to the LLM. */
+        analysisText?: string;
+        /** This call's LLM config. */
+        callConfig?: {
+            model?: string;
+            maxTokens?: number;
+            temperature?: number;
+        };
+        /** authorComponentsProgram only: one entry per retry attempt — the feedback fed back in and the raw response for that attempt, in order. */
+        attempts?: Array<{
+            feedback?: string;
+            rawResponse?: string;
+        }>;
+        /** The final raw LLM response text for this call (last attempt, for authorComponentsProgram's retry loop; the single response otherwise). */
+        rawResponse?: 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
+ * 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`.
  */
 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[];
+    };
 }
 
 /**
@@ -160,6 +1407,7 @@ 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, {
@@ -170,7 +1418,6 @@ declare const DSLRendererPropsSchema$1: z.ZodObject<{
             fn: string;
             deps?: string[] | undefined;
         }[] | undefined;
-        data?: Record<string, any> | undefined;
         pages?: {
             id: string;
             name: string;
@@ -192,6 +1439,7 @@ 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, {
@@ -202,7 +1450,6 @@ declare const DSLRendererPropsSchema$1: z.ZodObject<{
             fn: string;
             deps?: string[] | undefined;
         }[] | undefined;
-        data?: Record<string, any> | undefined;
         pages?: {
             id: string;
             name: string;
@@ -228,6 +1475,7 @@ 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, {
@@ -238,7 +1486,6 @@ declare const DSLRendererPropsSchema$1: z.ZodObject<{
             fn: string;
             deps?: string[] | undefined;
         }[] | undefined;
-        data?: Record<string, any> | undefined;
         pages?: {
             id: string;
             name: string;
@@ -264,6 +1511,7 @@ 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, {
@@ -274,7 +1522,6 @@ declare const DSLRendererPropsSchema$1: z.ZodObject<{
             fn: string;
             deps?: string[] | undefined;
         }[] | undefined;
-        data?: Record<string, any> | undefined;
         pages?: {
             id: string;
             name: string;
@@ -355,6 +1602,7 @@ 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, {
@@ -365,7 +1613,6 @@ declare const DSLRendererPropsSchema: z.ZodObject<{
             fn: string;
             deps?: string[] | undefined;
         }[] | undefined;
-        data?: Record<string, any> | undefined;
     }, {
         id: string;
         name?: string | undefined;
@@ -379,6 +1626,7 @@ 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, {
@@ -389,7 +1637,6 @@ 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>>;
@@ -407,6 +1654,7 @@ 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, {
@@ -417,7 +1665,6 @@ 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;
@@ -435,6 +1682,7 @@ 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, {
@@ -445,7 +1693,6 @@ 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;
@@ -634,23 +1881,20 @@ declare const ComponentSchema: z.ZodObject<{
     type: z.ZodString;
     description: z.ZodString;
     props: z.ZodObject<{
-        query: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>]>>;
+        query: z.ZodOptional<z.ZodNullable<z.ZodUnion<[z.ZodString, z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>]>>>;
         title: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
         config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        actions: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
     }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-        query: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>]>>;
+        query: z.ZodOptional<z.ZodNullable<z.ZodUnion<[z.ZodString, z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>]>>>;
         title: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
         config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        actions: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
     }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-        query: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>]>>;
+        query: z.ZodOptional<z.ZodNullable<z.ZodUnion<[z.ZodString, z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>]>>>;
         title: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
         config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        actions: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
     }, z.ZodTypeAny, "passthrough">>;
     category: z.ZodOptional<z.ZodString>;
     keywords: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -661,10 +1905,9 @@ declare const ComponentSchema: z.ZodObject<{
     description: string;
     props: {
         description?: string | undefined;
-        query?: string | {} | undefined;
+        query?: string | {} | null | undefined;
         title?: string | undefined;
         config?: Record<string, unknown> | undefined;
-        actions?: any[] | undefined;
     } & {
         [k: string]: unknown;
     };
@@ -679,10 +1922,9 @@ declare const ComponentSchema: z.ZodObject<{
     description: string;
     props: {
         description?: string | undefined;
-        query?: string | {} | undefined;
+        query?: string | {} | null | undefined;
         title?: string | undefined;
         config?: Record<string, unknown> | undefined;
-        actions?: any[] | undefined;
     } & {
         [k: string]: unknown;
     };
@@ -741,6 +1983,10 @@ declare const ToolSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
     description: z.ZodString;
+    /** Tool type: "source" = routed through SourceAgent, "direct" = called directly by MainAgent */
+    toolType: z.ZodOptional<z.ZodEnum<["source", "direct"]>>;
+    /** Full untruncated schema for source agent (all columns visible) */
+    fullSchema: z.ZodOptional<z.ZodString>;
     params: z.ZodRecord<z.ZodString, z.ZodString>;
     fn: z.ZodFunction<z.ZodTuple<[z.ZodAny], z.ZodUnknown>, z.ZodAny>;
     outputSchema: z.ZodOptional<z.ZodObject<{
@@ -773,12 +2019,22 @@ declare const ToolSchema: z.ZodObject<{
             description: string;
         }[];
     }>>;
+    /** Cache policy. `false` = never cache (live data, write ops). Mirrors HTTP `Cache-Control: no-store`. */
+    cache: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<false>, z.ZodObject<{
+        ttlMs: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        ttlMs?: number | undefined;
+    }, {
+        ttlMs?: number | undefined;
+    }>]>>;
 }, "strip", z.ZodTypeAny, {
     id: string;
     params: Record<string, string>;
     name: string;
     description: string;
     fn: (args_0: any, ...args: unknown[]) => any;
+    toolType?: "source" | "direct" | undefined;
+    fullSchema?: string | undefined;
     outputSchema?: {
         description: string;
         fields: {
@@ -787,12 +2043,17 @@ declare const ToolSchema: z.ZodObject<{
             description: string;
         }[];
     } | undefined;
+    cache?: false | {
+        ttlMs?: number | undefined;
+    } | undefined;
 }, {
     id: string;
     params: Record<string, string>;
     name: string;
     description: string;
     fn: (args_0: any, ...args: unknown[]) => any;
+    toolType?: "source" | "direct" | undefined;
+    fullSchema?: string | undefined;
     outputSchema?: {
         description: string;
         fields: {
@@ -801,6 +2062,9 @@ declare const ToolSchema: z.ZodObject<{
             description: string;
         }[];
     } | undefined;
+    cache?: false | {
+        ttlMs?: number | undefined;
+    } | undefined;
 }>;
 type Tool$1 = z.infer<typeof ToolSchema>;
 type CollectionOperation = 'getMany' | 'getOne' | 'query' | 'mutation' | 'updateOne' | 'deleteOne' | 'createOne';
@@ -839,6 +2103,10 @@ 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;
@@ -852,27 +2120,61 @@ interface SuperatomSDKConfig {
      * - 'balanced': Use best model for complex tasks, fast model for simple tasks (default)
      */
     modelStrategy?: ModelStrategy;
+    /**
+     * Model for the main agent (routing + analysis).
+     * Format: "provider/model-name" (e.g., "anthropic/claude-haiku-4-5-20251001")
+     * If not set, uses the provider's default model.
+     */
+    mainAgentModel?: string;
+    /**
+     * Model for source agents (per-source query generation).
+     * Format: "provider/model-name" (e.g., "anthropic/claude-haiku-4-5-20251001")
+     * If not set, uses the provider's default model.
+     */
+    sourceAgentModel?: string;
     /**
      * Separate model configuration for DASH_COMP flow (dashboard component picking)
      * If not provided, falls back to provider-based model selection
      */
     dashCompModels?: DashCompModelConfig;
+    /**
+     * Similarity threshold for conversation search (semantic matching)
+     * Value between 0 and 1 (e.g., 0.8 = 80% similarity required)
+     * Higher values require closer matches, lower values allow more distant matches
+     * Default: 0.8
+     */
+    conversationSimilarityThreshold?: number;
+    /**
+     * Query cache TTL (Time To Live) in minutes
+     * Cached query results expire after this duration
+     * Default: 5 minutes
+     */
+    queryCacheTTL?: number;
+    /**
+     * Dashboard conversation history TTL (Time To Live) in minutes
+     * Per-dashboard conversation histories expire after this duration
+     * Default: 30 minutes
+     */
+    dashboardHistoryTTL?: number;
 }
 
 declare const KbNodesQueryFiltersSchema: z.ZodObject<{
     query: z.ZodOptional<z.ZodString>;
     category: z.ZodOptional<z.ZodString>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    createdBy: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodOptional<z.ZodEnum<["global", "user", "query"]>>;
+    createdBy: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
+    type?: "query" | "user" | "global" | undefined;
     query?: string | undefined;
     category?: string | undefined;
-    createdBy?: number | undefined;
+    createdBy?: string | undefined;
     tags?: string[] | undefined;
 }, {
+    type?: "query" | "user" | "global" | undefined;
     query?: string | undefined;
     category?: string | undefined;
-    createdBy?: number | undefined;
+    createdBy?: string | undefined;
     tags?: string[] | undefined;
 }>;
 type KbNodesQueryFilters = z.infer<typeof KbNodesQueryFiltersSchema>;
@@ -884,106 +2186,118 @@ declare const KbNodesRequestPayloadSchema: z.ZodObject<{
         content: z.ZodOptional<z.ZodString>;
         category: z.ZodOptional<z.ZodString>;
         tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-        createdBy: z.ZodOptional<z.ZodNumber>;
-        updatedBy: z.ZodOptional<z.ZodNumber>;
-        userId: z.ZodOptional<z.ZodNumber>;
+        type: z.ZodOptional<z.ZodEnum<["global", "user", "query"]>>;
+        createdBy: z.ZodOptional<z.ZodString>;
+        updatedBy: z.ZodOptional<z.ZodString>;
+        userId: z.ZodOptional<z.ZodString>;
         query: z.ZodOptional<z.ZodString>;
         filters: z.ZodOptional<z.ZodObject<{
             query: z.ZodOptional<z.ZodString>;
             category: z.ZodOptional<z.ZodString>;
             tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-            createdBy: z.ZodOptional<z.ZodNumber>;
+            type: z.ZodOptional<z.ZodEnum<["global", "user", "query"]>>;
+            createdBy: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
+            type?: "query" | "user" | "global" | undefined;
             query?: string | undefined;
             category?: string | undefined;
-            createdBy?: number | undefined;
+            createdBy?: string | undefined;
             tags?: string[] | undefined;
         }, {
+            type?: "query" | "user" | "global" | undefined;
             query?: string | undefined;
             category?: string | undefined;
-            createdBy?: number | undefined;
+            createdBy?: string | undefined;
             tags?: string[] | undefined;
         }>>;
         limit: z.ZodOptional<z.ZodNumber>;
         offset: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         id?: number | undefined;
+        type?: "query" | "user" | "global" | undefined;
         query?: string | undefined;
         title?: string | undefined;
         category?: string | undefined;
-        userId?: number | undefined;
+        userId?: string | undefined;
         limit?: number | undefined;
         filters?: {
+            type?: "query" | "user" | "global" | undefined;
             query?: string | undefined;
             category?: string | undefined;
-            createdBy?: number | undefined;
+            createdBy?: string | undefined;
             tags?: string[] | undefined;
         } | undefined;
-        createdBy?: number | undefined;
-        updatedBy?: number | undefined;
+        createdBy?: string | undefined;
+        updatedBy?: string | undefined;
+        offset?: number | undefined;
         tags?: string[] | undefined;
         content?: string | undefined;
-        offset?: number | undefined;
     }, {
         id?: number | undefined;
+        type?: "query" | "user" | "global" | undefined;
         query?: string | undefined;
         title?: string | undefined;
         category?: string | undefined;
-        userId?: number | undefined;
+        userId?: string | undefined;
         limit?: number | undefined;
         filters?: {
+            type?: "query" | "user" | "global" | undefined;
             query?: string | undefined;
             category?: string | undefined;
-            createdBy?: number | undefined;
+            createdBy?: string | undefined;
             tags?: string[] | undefined;
         } | undefined;
-        createdBy?: number | undefined;
-        updatedBy?: number | undefined;
+        createdBy?: string | undefined;
+        updatedBy?: string | undefined;
+        offset?: number | undefined;
         tags?: string[] | undefined;
         content?: string | undefined;
-        offset?: number | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    operation: "create" | "getOne" | "update" | "delete" | "getAll" | "search" | "getByCategory" | "getByUser" | "getCategories" | "getTags";
+    operation: "create" | "getOne" | "search" | "update" | "delete" | "getAll" | "getByCategory" | "getByUser" | "getCategories" | "getTags";
     data?: {
         id?: number | undefined;
+        type?: "query" | "user" | "global" | undefined;
         query?: string | undefined;
         title?: string | undefined;
         category?: string | undefined;
-        userId?: number | undefined;
+        userId?: string | undefined;
         limit?: number | undefined;
         filters?: {
+            type?: "query" | "user" | "global" | undefined;
             query?: string | undefined;
             category?: string | undefined;
-            createdBy?: number | undefined;
+            createdBy?: string | undefined;
             tags?: string[] | undefined;
         } | undefined;
-        createdBy?: number | undefined;
-        updatedBy?: number | undefined;
+        createdBy?: string | undefined;
+        updatedBy?: string | undefined;
+        offset?: number | undefined;
         tags?: string[] | undefined;
         content?: string | undefined;
-        offset?: number | undefined;
     } | undefined;
 }, {
-    operation: "create" | "getOne" | "update" | "delete" | "getAll" | "search" | "getByCategory" | "getByUser" | "getCategories" | "getTags";
+    operation: "create" | "getOne" | "search" | "update" | "delete" | "getAll" | "getByCategory" | "getByUser" | "getCategories" | "getTags";
     data?: {
         id?: number | undefined;
+        type?: "query" | "user" | "global" | undefined;
         query?: string | undefined;
         title?: string | undefined;
         category?: string | undefined;
-        userId?: number | undefined;
+        userId?: string | undefined;
         limit?: number | undefined;
         filters?: {
+            type?: "query" | "user" | "global" | undefined;
             query?: string | undefined;
             category?: string | undefined;
-            createdBy?: number | undefined;
+            createdBy?: string | undefined;
             tags?: string[] | undefined;
         } | undefined;
-        createdBy?: number | undefined;
-        updatedBy?: number | undefined;
+        createdBy?: string | undefined;
+        updatedBy?: string | undefined;
+        offset?: number | undefined;
         tags?: string[] | undefined;
         content?: string | undefined;
-        offset?: number | undefined;
     } | undefined;
 }>;
 type KbNodesRequestPayload = z.infer<typeof KbNodesRequestPayloadSchema>;
@@ -1252,19 +2566,749 @@ declare class ReportManager {
     getReportCount(): number;
 }
 
-type SystemPrompt = string | Anthropic.Messages.TextBlockParam[];
-interface LLMMessages {
-    sys: SystemPrompt;
-    user: string;
-    prefill?: string;
+/**
+ * ScriptRecipeStore — injected metadata backend for the script flow.
+ *
+ * The SDK is standalone (no DB dependency). The backend implements this
+ * interface over Postgres (full-text search + atomic counters) and injects it
+ * via `collections['script-recipes']`, exactly like `collections['source-embeddings']`.
+ * `ScriptStore` consumes it for all METADATA operations while keeping the
+ * executable body on disk as scripts-store/<fileBase>.ts.
+ *
+ * All metadata rows are plain JSON (no scriptBody — that lives on disk).
+ * See backend/docs/SCRIPT-FLOW-SCALING-ISSUES.md (#1, #3, #7).
+ */
+
+/** One recipe's metadata as stored in Postgres (mirrors the script_recipes table). */
+interface ScriptRecipeMetaRow {
+    id: string;
+    projectId?: string | null;
+    version: number;
+    name: string;
+    intentDescription: string;
+    tags: string[] | null;
+    createdFrom: string | null;
+    sourceIds: string[] | null;
+    tables: string[] | null;
+    parameters: ScriptParameter[] | null;
+    components?: ScriptComponentSpec[] | null;
+    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 LLMOptions {
-    model?: string;
-    maxTokens?: number;
-    temperature?: number;
-    topP?: number;
-    apiKey?: string;
+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>;
+}
+/** Pull the injected store off the collections bag (or null if not wired). */
+declare function resolveScriptRecipeStore(collections: any): ScriptRecipeStore | null;
+
+/**
+ * ScriptStore — Postgres metadata + on-disk body for script recipes.
+ *
+ * Split of responsibilities:
+ *   - METADATA  → injected `ScriptRecipeStore` (Postgres FTS + atomic counters),
+ *                 resolved from `collections['script-recipes']`.
+ *   - BODY      → scripts-store/<fileBase>.ts, editable in your IDE. Written
+ *                 atomically (temp + rename); `bodyHash` (sha256) detects edits.
+ *
+ * The old "read every file every turn + send the whole catalog to the LLM"
+ * matcher is gone — matching is `store.search(prompt)` (FTS shortlist). The
+ * draft/verified filename dance is gone too: `status` is a DB column and the
+ * file keeps a stable `<fileBase>.ts` name across promotion.
+ *
+ * When no metadata store is injected, the store degrades to a safe no-op
+ * (count 0 → script flow disabled) instead of crashing.
+ *
+ * See backend/docs/SCRIPT-FLOW-SCALING-ISSUES.md.
+ */
+
+interface SaveDraftInput {
+    /** Reuse an existing draft (retry); omit to mint a new one. */
+    recipeId?: string;
+    /** Per-turn unique suffix, stable across retries within the turn. */
+    turnId: string;
+    name: string;
+    intentDescription: string;
+    tags: string[];
+    parameters: ScriptParameter[];
+    scriptBody: string;
+    createdFrom: string;
+    /**
+     * 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;
+}
+/**
+ * Fingerprint of everything that decides what `getData` PRODUCES.
+ *
+ * A recipe holds three programs in one file — getData, getAnalysis,
+ * getComponents — but only getData costs a source query, and only getData's
+ * output can invalidate a verified run. Editing the narrative or a chart title
+ * cannot change a single row, yet a whole-body comparison says it did, because
+ * `write_script` resubmits the entire file. That is what made a cosmetic edit
+ * indistinguishable from a SQL change and cost a scarce execute attempt.
+ *
+ * Parameters are part of the fingerprint, not an afterthought: `execute_script`
+ * runs with `{}`, so the DEFAULTS are the values getData actually sees. Same
+ * getData text with a changed default is a genuinely different result, and
+ * hashing the body alone would have called it unchanged.
+ *
+ * Deliberately conservative — trimmed, not whitespace-collapsed. The two ways
+ * to be wrong are NOT symmetric: a false "unchanged" reuses a stale result and
+ * reports wrong numbers, while a false "changed" merely costs an attempt. So it
+ * biases toward detecting change, and a reformat is allowed to look like an edit.
+ */
+declare function dataFingerprint(scriptBody: string, parameters?: ScriptParameter[]): string;
+/** Inverse of `stripNamedExport` — pulls the named export block OUT instead of removing it. Null when absent. */
+declare function extractNamedExport(body: string, fnName: string): string | null;
+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.
+     */
+    /**
+     * Body text as it stands now, for reverting an attach that turns out to be
+     * invalid.
+     *
+     * getComponents can only be VALIDATED by running it, and it can only be run
+     * once it is on disk — so attachComponents necessarily writes before anyone
+     * knows whether the body is good. Without a revert, a rejected body stays
+     * attached: promote() then sees the recipe "exports getComponents", clears
+     * the specs the fallback generator produced, and the recipe is verified with
+     * component code that was already rejected. Confirmed live on
+     * "Total Bookings by Branch", which shipped a sourceRef of 'computed:_final'
+     * that validateSpecs had refused.
+     */
+    snapshotBody(recipeId: string): Promise<string | null>;
+    /** Put back a body captured by {@link snapshotBody}. */
+    restoreBody(recipeId: string, body: string): Promise<boolean>;
+    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;
+    /**
+     * 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.
+     */
+    private renameArchives;
+    /** Atomic body write (temp + rename) so concurrent reads never see a partial file. */
+    private writeBody;
+    private unlinkBody;
+}
+
+/**
+ * Main Agent (Orchestrator)
+ *
+ * A single LLM.streamWithTools() call that handles everything:
+ * - Routing: decides which source(s) to query based on summaries
+ * - Querying: calls source tools (each wraps an independent SourceAgent)
+ * - Direct tools: calls pre-built function tools directly with LLM-provided params
+ * - Re-querying: if data is wrong/incomplete, calls tools again with modified intent
+ * - Analysis: generates final text response from the data
+ *
+ * Two tool types:
+ * - "source" tools: main agent sees summaries, SourceAgent handles SQL generation independently
+ * - "direct" tools: main agent calls fn() directly with structured params (no SourceAgent)
+ */
+
+declare class MainAgent {
+    private externalTools;
+    private workflows;
+    private config;
+    private streamBuffer;
+    /**
+     * Optional: when provided, MainAgent exposes the `write_script` /
+     * `execute_script` tools to the LLM and persists drafts to disk via the
+     * store. Headless callers (alert analyzer, metric resolver) omit these to
+     * suppress script authoring entirely — drafts would otherwise leak onto
+     * disk with no caller to promote or clean them up.
+     */
+    private scriptStore;
+    private turnId;
+    private createdFromPrompt;
+    private scriptState;
+    /** 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();
+    /**
+     * Handle a user question using the multi-agent system.
+     *
+     * This is ONE LLM.streamWithTools() call. The LLM:
+     * 1. Sees source summaries + direct tool descriptions in system prompt
+     * 2. Decides which tool(s) to call (routing)
+     * 3. Source tools → SourceAgent runs independently → returns data
+     * 4. Direct tools → fn() called directly with LLM params → returns data
+     * 5. Generates final analysis text
+     */
+    handleQuestion(userPrompt: string, apiKey?: string, conversationHistory?: string, streamCallback?: (chunk: string) => void, 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;
+    /**
+     * Restrictions the seam reported while this run's queries executed.
+     *
+     * getData does NOT re-run for write_components/write_analysis, so the child
+     * cannot observe these itself — the parent hands them across, exactly as it
+     * does for `entities`.
+     */
+    private observedPolicies;
+    /**
+     * 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;
+    /**
+     * Execute a direct tool — call fn() with LLM-provided params, no SourceAgent.
+     */
+    private handleDirectTool;
+    /**
+     * Build the main agent's system prompt with source summaries, direct tool descriptions,
+     * and workflow component descriptions.
+     */
+    private buildSystemPrompt;
+    /**
+     * Build tool definitions for source tools — summary-only descriptions.
+     * The full schema is inside the SourceAgent which runs independently.
+     */
+    private buildSourceToolDefinitions;
+    /**
+     * Build tool definitions for direct tools — expose their actual params.
+     * These are called directly by the main agent LLM, no SourceAgent.
+     */
+    private buildDirectToolDefinitions;
+    /**
+     * Capture a workflow selection. We do NOT execute anything — the LLM has
+     * already extracted the props it wants the workflow rendered with. We
+     * record the selection (via the capture callback) and return a short
+     * acknowledgement so the LLM ends its turn cleanly without writing
+     * analysis text or calling more tools.
+     */
+    private handleWorkflow;
+    /**
+     * Build LLM tool definitions for workflow components. The workflow's
+     * propsSchema becomes the tool's input_schema so the LLM extracts props
+     * directly from the prompt — same mechanic as direct tools.
+     */
+    private buildWorkflowToolDefinitions;
+    /**
+     * Format a source agent's result as a clean string for the main agent LLM.
+     */
+    private formatResultForMainAgent;
+    /**
+     * Get source summaries (for external inspection/debugging).
+     */
+    getSourceSummaries(): SourceSummary[];
+}
+
+type SystemPrompt = string | Anthropic.Messages.TextBlockParam[];
+interface LLMMessages {
+    sys: SystemPrompt;
+    user: string;
+    prefill?: string;
+}
+interface LLMOptions {
+    model?: string;
+    maxTokens?: number;
+    temperature?: number;
+    topP?: number;
+    apiKey?: string;
+    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;
@@ -1286,6 +3330,16 @@ declare class LLM {
      * @returns Normalized system prompt for Anthropic API
      */
     private static _normalizeSystemPrompt;
+    /**
+     * Strip unpaired UTF-16 surrogates from every text field of a message set.
+     *
+     * A lone surrogate (from mid-pair string slicing or corrupt source data)
+     * serializes to a bare `\udXXX` escape that strict JSON parsers — including
+     * the one on Anthropic's API — reject with "no low surrogate in string",
+     * failing the whole request. Sanitizing here, at the single boundary every
+     * provider call flows through, guarantees no request can carry one.
+     */
+    private static _sanitizeMessages;
     /**
      * Log cache usage metrics from Anthropic API response
      * Shows cache hits, costs, and savings
@@ -1302,16 +3356,76 @@ declare class LLM {
      * "claude-sonnet-4-5" → ["anthropic", "claude-sonnet-4-5"] (default)
      */
     private static _parseModel;
+    /**
+     * Map an Anthropic model id (e.g. "claude-sonnet-4-5-20250929") to the OpenRouter slug
+     * (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;
+    /**
+     * Recursively strip unsupported JSON Schema properties for Gemini
+     * Gemini doesn't support: additionalProperties, $schema, etc.
+     */
+    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
@@ -1401,19 +3515,9 @@ declare class UILogCollector {
     setUIBlockId(uiBlockId: string): void;
 }
 
-/**
- * Represents an action that can be performed on a UIBlock
- */
-interface Action {
-    id: string;
-    name: string;
-    type: string;
-    [key: string]: any;
-}
-
 /**
  * UIBlock represents a single user and assistant message block in a thread
- * Contains user question, component metadata, component data, text response, and available actions
+ * Contains user question, component metadata, component data, and text response
  */
 declare class UIBlock {
     private id;
@@ -1421,18 +3525,23 @@ declare class UIBlock {
     private generatedComponentMetadata;
     private componentData;
     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
      * @param componentData - The component data object
      * @param generatedComponentMetadata - Optional metadata about the generated component
-     * @param actions - Optional array of available actions
      * @param id - Optional custom ID, generates UUID if not provided
      * @param textResponse - Optional text response from LLM
      */
-    constructor(userQuestion: string, componentData?: Record<string, any>, generatedComponentMetadata?: Record<string, any>, actions?: Action[], id?: string, textResponse?: string | null);
+    constructor(userQuestion: string, componentData?: Record<string, any>, generatedComponentMetadata?: Record<string, any>, id?: string, textResponse?: string | null);
     /**
      * Get the UIBlock ID
      */
@@ -1482,41 +3591,22 @@ declare class UIBlock {
      * Set or update text response
      */
     setTextResponse(textResponse: string | null): void;
+    /** The program-generated half of the answer — see setProgramAnswer. */
+    programAnswer?: string | null;
     /**
-     * Get all actions (only if they are resolved, not if fetching)
-     */
-    getActions(): Action[] | null | Promise<Action[]>;
-    /**
-     * Get or fetch actions
-     * If actions don't exist or are a Promise, calls the generateFn and stores the promise
-     * If actions already exist, returns them
-     * @param generateFn - Async function to generate actions
-     * @returns Promise resolving to Action[]
-     */
-    getOrFetchActions(generateFn: () => Promise<Action[]>): Promise<Action[]>;
-    /**
-     * Set or replace all actions
-     */
-    setActions(actions: Action[]): void;
-    /**
-     * Add a single action (only if actions are resolved)
-     */
-    addAction(action: Action): void;
-    /**
-     * Add multiple actions (only if actions are resolved)
-     */
-    addActions(actions: Action[]): void;
-    /**
-     * Remove an action by ID (only if actions are resolved)
+     * Bind this block to the script recipe that produced its answer.
      */
-    removeAction(actionId: string): boolean;
+    setScriptBinding(binding: Record<string, any> | null): void;
     /**
-     * Clear all actions
+     * The program-generated half of the answer, kept verbatim so a reload can
+     * replace exactly that text without disturbing the streamed narration.
      */
-    clearActions(): void;
+    setProgramAnswer(text: string | null): void;
+    getProgramAnswer(): string | null;
     /**
-     * Get creation timestamp
+     * The script recipe bound to this block, if any.
      */
+    getScriptBinding(): Record<string, any> | null;
     getCreatedAt(): Date;
     /**
      * Convert UIBlock to JSON-serializable object
@@ -1584,7 +3674,55 @@ declare class Thread {
      * @param currentUIBlockId - ID of current UIBlock to exclude from context (optional)
      * @returns Formatted conversation history string
      */
-    getConversationContext(limit?: number, currentUIBlockId?: string): 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.
+     * @param fetchRecentFromDb When provided, this is now the SOURCE OF TRUTH
+     * for history instead of this process's in-memory `uiblocks` map — reads
+     * the persisted `user_conversations` rows (DB `response` jsonb shape, see
+     * transformUIBlockForDB in conversation-saver.ts) via the caller's own
+     * `user-conversations.getRecentForContext` collection. Rows come back
+     * newest-first (already excluding status='aborted' — the query itself
+     * filters that, matching what the in-memory path achieved via
+     * thread.removeUIBlock() on abort). Fixes the standing gap where a backend
+     * restart lost every thread's history (ThreadManager has no DB-backed
+     * rehydration) — DB-backed history survives that, and is correct even if
+     * a different process instance saved the row. Omit it and this falls back
+     * to the in-memory map, for any caller not yet updated.
+     */
+    getConversationContext(limit?: number, currentUIBlockId?: string, getScriptBody?: (recipeId: string, version: number) => Promise<string | null>, fetchRecentFromDb?: (limit: number) => Promise<Array<{
+        userprompt?: string;
+        response?: Record<string, any>;
+    }>>): Promise<string>;
     /**
      * Convert Thread to JSON-serializable object
      */
@@ -1593,12 +3731,20 @@ declare class Thread {
 
 /**
  * ThreadManager manages all threads globally
- * Provides methods to create, retrieve, and delete threads
+ * Provides methods to create, retrieve, and delete threads.
+ * Includes automatic cleanup to prevent unbounded memory growth.
  */
 declare class ThreadManager {
     private static instance;
     private threads;
+    private cleanupInterval;
+    private readonly threadTtlMs;
     private constructor();
+    /**
+     * Periodically remove threads older than 7 days.
+     * Runs every hour to avoid frequent iteration over the map.
+     */
+    private startCleanup;
     /**
      * Get singleton instance of ThreadManager
      */
@@ -1997,6 +4143,92 @@ declare function rerankConversationResults<T extends {
     bm25Score: number;
 }>;
 
+/**
+ * QueryExecutionService - Handles all query execution, validation, and retry logic
+ * Extracted from BaseLLM for better separation of concerns
+ */
+
+/**
+ * Context for component when requesting query fix
+ */
+interface ComponentContext {
+    name: string;
+    type: string;
+    title?: string;
+}
+/**
+ * Result of query validation
+ */
+interface QueryValidationResult {
+    component: Component | null;
+    queryKey: string;
+    result: any;
+    validated: boolean;
+}
+/**
+ * Result of batch query validation
+ */
+interface BatchValidationResult {
+    components: Component[];
+    queryResults: Map<string, any>;
+}
+/**
+ * Configuration for QueryExecutionService
+ */
+interface QueryExecutionServiceConfig {
+    defaultLimit: number;
+    getModelForTask: (taskType: 'simple' | 'complex') => string;
+    getApiKey: (apiKey?: string) => string | undefined;
+    providerName: string;
+}
+/**
+ * QueryExecutionService handles all query-related operations
+ */
+declare class QueryExecutionService {
+    private config;
+    constructor(config: QueryExecutionServiceConfig);
+    /**
+     * Get the cache key for a query
+     * This ensures the cache key matches what the frontend will send
+     */
+    getQueryCacheKey(query: any): string;
+    /**
+     * Execute a query against the database
+     * @param query - The SQL query to execute (string or object with sql/values)
+     * @param collections - Collections object containing database execute function
+     * @returns Object with result data and cache key
+     */
+    executeQuery(query: any, collections: any): Promise<{
+        result: any;
+        cacheKey: string;
+    }>;
+    /**
+     * Request the LLM to fix a failed SQL query
+     * @param failedQuery - The query that failed execution
+     * @param errorMessage - The error message from the failed execution
+     * @param componentContext - Context about the component
+     * @param apiKey - Optional API key
+     * @returns Fixed query string
+     */
+    requestQueryFix(failedQuery: string, errorMessage: string, componentContext: ComponentContext, apiKey?: string): Promise<string>;
+    /**
+     * Validate a single component's query with retry logic
+     * @param component - The component to validate
+     * @param collections - Collections object containing database execute function
+     * @param apiKey - Optional API key for LLM calls
+     * @returns Validation result with component, query key, and result
+     */
+    validateSingleQuery(component: Component, collections: any, apiKey?: string): Promise<QueryValidationResult>;
+    /**
+     * Validate multiple component queries in parallel
+     * @param components - Array of components with potential queries
+     * @param collections - Collections object containing database execute function
+     * @param apiKey - Optional API key for LLM calls
+     * @returns Object with validated components and query results map
+     */
+    validateComponentQueries(components: Component[], collections: any, apiKey?: string): Promise<BatchValidationResult>;
+}
+
 /**
  * Task types for model selection
  * - 'complex': Text generation, component matching, parameter adaptation (uses best model in balanced mode)
@@ -2015,6 +4247,7 @@ interface BaseLLMConfig {
      * - 'balanced': Use best model for complex tasks, fast model for simple tasks (default)
      */
     modelStrategy?: ModelStrategy;
+    conversationSimilarityThreshold?: number;
 }
 /**
  * BaseLLM abstract class for AI-powered component generation and matching
@@ -2026,6 +4259,8 @@ declare abstract class BaseLLM {
     protected defaultLimit: number;
     protected apiKey?: string;
     protected modelStrategy: ModelStrategy;
+    protected conversationSimilarityThreshold: number;
+    protected queryService: QueryExecutionService;
     constructor(config?: BaseLLMConfig);
     /**
      * Get the appropriate model based on task type and model strategy
@@ -2043,6 +4278,16 @@ declare abstract class BaseLLM {
      * @returns The current model strategy
      */
     getModelStrategy(): ModelStrategy;
+    /**
+     * Set the conversation similarity threshold at runtime
+     * @param threshold - Value between 0 and 1 (e.g., 0.8 = 80% similarity required)
+     */
+    setConversationSimilarityThreshold(threshold: number): void;
+    /**
+     * Get the current conversation similarity threshold
+     * @returns The current threshold value
+     */
+    getConversationSimilarityThreshold(): number;
     /**
      * Get the default model for this provider (used for complex tasks like text generation)
      */
@@ -2071,28 +4316,26 @@ declare abstract class BaseLLM {
      */
     protected containsFormComponent(component: any): boolean;
     /**
-     * Match components from text response suggestions and generate follow-up questions
+     * Match components from text response suggestions
      * Takes a text response with component suggestions (c1:type format) and matches with available components
-     * Also generates title, description, and intelligent follow-up questions (actions) based on the analysis
+     * Also generates title and description based on the analysis
      * All components are placed in a default MultiComponentContainer layout
      * @param analysisContent - The text response containing component suggestions
      * @param components - List of available components
      * @param apiKey - Optional API key
-     * @param logCollector - Optional log collector
      * @param componentStreamCallback - Optional callback to stream primary KPI component as soon as it's identified
-     * @returns Object containing matched components, layout title/description, and follow-up actions
+     * @returns Object containing matched components and layout title/description
      */
-    matchComponentsFromAnalysis(analysisContent: string, components: Component[], apiKey?: string, logCollector?: any, componentStreamCallback?: (component: Component) => void, deferredTools?: any[], executedTools?: any[]): Promise<{
+    matchComponentsFromAnalysis(analysisContent: string, components: Component[], userPrompt: string, apiKey?: string, componentStreamCallback?: (component: Component) => void, deferredTools?: any[], executedTools?: any[], collections?: any, userId?: string): Promise<{
         components: Component[];
         layoutTitle: string;
         layoutDescription: string;
-        actions: Action[];
     }>;
     /**
      * Classify user question into category and detect external tools needed
      * Determines if question is for data analysis, requires external tools, or needs text response
      */
-    classifyQuestionCategory(userPrompt: string, apiKey?: string, logCollector?: any, conversationHistory?: string, externalTools?: any[]): Promise<{
+    classifyQuestionCategory(userPrompt: string, apiKey?: string, conversationHistory?: string, externalTools?: any[]): Promise<{
         category: 'data_analysis' | 'data_modification' | 'general';
         externalTools: Array<{
             type: string;
@@ -2109,7 +4352,7 @@ declare abstract class BaseLLM {
      * Takes a matched UI block from semantic search and modifies its props to answer the new question
      * Also adapts the cached text response to match the new question
      */
-    adaptUIBlockParameters(currentUserPrompt: string, originalUserPrompt: string, matchedUIBlock: any, apiKey?: string, logCollector?: any, cachedTextResponse?: string): Promise<{
+    adaptUIBlockParameters(currentUserPrompt: string, originalUserPrompt: string, matchedUIBlock: any, apiKey?: string, cachedTextResponse?: string): Promise<{
         success: boolean;
         adaptedComponent?: Component;
         adaptedTextResponse?: string;
@@ -2124,13 +4367,8 @@ declare abstract class BaseLLM {
      * This provides conversational text responses instead of component generation
      * Supports tool calling for query execution with automatic retry on errors (max 3 attempts)
      * After generating text response, if components are provided, matches suggested components
-     * @param streamCallback - Optional callback function to receive text chunks as they stream
-     * @param collections - Collection registry for executing database queries via database.execute
-     * @param components - Optional list of available components for matching suggestions
-     * @param externalTools - Optional array of external tools (email, calendar, etc.) that can be called
-     * @param category - Question category ('data_analysis' | 'data_modification' | 'general'). For data_modification, answer component streaming is skipped. For general, component generation is skipped entirely.
      */
-    generateTextResponse(userPrompt: string, apiKey?: string, logCollector?: any, conversationHistory?: string, streamCallback?: (chunk: string) => void, collections?: any, components?: Component[], externalTools?: any[], category?: 'data_analysis' | 'data_modification' | 'general'): Promise<T_RESPONSE>;
+    generateTextResponse(userPrompt: string, apiKey?: string, conversationHistory?: string, streamCallback?: (chunk: string) => void, collections?: any, components?: Component[], externalTools?: any[], category?: 'data_analysis' | 'data_modification' | 'general', userId?: string): Promise<T_RESPONSE>;
     /**
      * Main orchestration function with semantic search and multi-step classification
      * NEW FLOW (Recommended):
@@ -2138,19 +4376,8 @@ declare abstract class BaseLLM {
      *    - If match found → Adapt UI block parameters and return
      * 2. Category classification: Determine if data_analysis, requires_external_tools, or text_response
      * 3. Route appropriately based on category and response mode
-     *
-     * @param responseMode - 'component' for component generation (default), 'text' for text responses
-     * @param streamCallback - Optional callback function to receive text chunks as they stream (only for text mode)
-     * @param collections - Collection registry for executing database queries (required for text mode)
-     * @param externalTools - Optional array of external tools (email, calendar, etc.) that can be called (only for text mode)
      */
-    handleUserRequest(userPrompt: string, components: Component[], apiKey?: string, logCollector?: any, conversationHistory?: string, responseMode?: 'component' | 'text', streamCallback?: (chunk: string) => void, collections?: any, externalTools?: any[], userId?: string): Promise<T_RESPONSE>;
-    /**
-     * Generate next questions that the user might ask based on the original prompt and generated component
-     * This helps provide intelligent suggestions for follow-up queries
-     * For general/conversational questions without components, pass textResponse instead
-     */
-    generateNextQuestions(originalUserPrompt: string, component?: Component | null, componentData?: Record<string, unknown>, apiKey?: string, logCollector?: any, conversationHistory?: string, textResponse?: string): Promise<string[]>;
+    handleUserRequest(userPrompt: string, components: Component[], apiKey?: string, conversationHistory?: string, responseMode?: 'component' | 'text', streamCallback?: (chunk: string) => void, collections?: any, externalTools?: any[], userId?: string): Promise<T_RESPONSE>;
 }
 
 interface AnthropicLLMConfig extends BaseLLMConfig {
@@ -2209,83 +4436,1348 @@ declare class OpenAILLM extends BaseLLM {
 }
 declare const openaiLLM: OpenAILLM;
 
-declare const SDK_VERSION = "0.0.8";
-type MessageTypeHandler = (message: IncomingMessage) => void | Promise<void>;
-declare class SuperatomSDK {
-    private ws;
-    private url;
-    private apiKey?;
-    private projectId;
-    private type;
-    private bundleDir;
-    private messageHandlers;
-    private messageTypeHandlers;
-    private connected;
-    private reconnectAttempts;
-    private maxReconnectAttempts;
-    private collections;
-    private components;
-    private tools;
-    private anthropicApiKey;
-    private groqApiKey;
-    private geminiApiKey;
-    private openaiApiKey;
-    private llmProviders;
-    private databaseType;
-    private modelStrategy;
-    private userManager;
-    private dashboardManager;
-    private reportManager;
-    private pingInterval;
-    private lastPong;
-    private readonly PING_INTERVAL_MS;
-    private readonly PONG_TIMEOUT_MS;
-    constructor(config: SuperatomSDKConfig);
+/**
+ * Query Cache — Two mechanisms:
+ *
+ * 1. `cache` (query string → result data) — TTL-based with max size, for avoiding re-execution
+ *    of recently validated queries. True LRU eviction: reads bubble entries to the back via
+ *    delete+re-set so the oldest *unused* entry is evicted, not the oldest *inserted*.
+ *
+ * 2. Encrypted queryId tokens — SQL is encrypted into the queryId itself (self-contained).
+ *    No server-side storage needed for SQL mappings. The token is decrypted on each request.
+ *    This eliminates the unbounded queryIdCache that previously grew forever and caused
+ *    memory bloat (hundreds of MBs after thousands of queries).
+ *
+ *    Result data can still be cached temporarily via the data cache (mechanism 1).
+ */
+declare class QueryCache {
+    private cache;
+    private ttlMs;
+    private maxCacheSize;
+    private cleanupInterval;
+    private readonly algorithm;
+    private encryptionKey;
+    constructor();
     /**
-     * Initialize PromptLoader and load prompts into memory
-     * Tries to load from file system first, then falls back to hardcoded prompts
+     * Set the cache TTL (Time To Live)
+     * @param minutes - TTL in minutes (default: 10)
      */
-    private initializePromptLoader;
+    setTTL(minutes: number): void;
     /**
-     * Initialize UserManager for the project
+     * Get the current TTL in minutes
      */
-    private initializeUserManager;
+    getTTL(): number;
     /**
-     * Get the UserManager instance for this SDK
+     * Which access bucket this call reads and writes.
+     *
+     * `''` means the unrestricted bucket and produces a key identical to the one
+     * used before authorization existed. `null` means do not touch the cache.
      */
-    getUserManager(): UserManager;
+    private scope;
+    /** The stored key: the scope namespace, then the caller's key. NUL cannot occur in SQL. */
+    private scopedKey;
     /**
-     * Initialize DashboardManager for the project
+     * Store query result in data cache.
+     * If the key already exists, it's removed first so the re-insert places it
+     * at the back of the iteration order (LRU). Eviction only fires when adding
+     * a genuinely new key past the size limit.
      */
-    private initializeDashboardManager;
+    set(query: string, data: any): void;
     /**
-     * Get the DashboardManager instance for this SDK
+     * Get cached result if exists and not expired.
+     * On hit, re-inserts the entry so it moves to the back of the Map's
+     * iteration order — turning FIFO eviction into true LRU.
      */
-    getDashboardManager(): DashboardManager;
+    get(query: string): any | null;
     /**
-     * Initialize ReportManager for the project
+     * Check if query exists in cache (not expired)
      */
-    private initializeReportManager;
+    has(query: string): boolean;
     /**
-     * Get the ReportManager instance for this SDK
+     * Remove a specific query from cache
      */
-    getReportManager(): ReportManager;
+    delete(query: string): void;
     /**
-     * Connect to the Superatom WebSocket service
+     * Clear all cached entries
      */
-    connect(): Promise<void>;
+    clear(): void;
     /**
-     * Handle incoming WebSocket messages
+     * Get cache statistics
      */
-    private handleMessage;
+    getStats(): {
+        size: number;
+        queryIdCount: number;
+        oldestEntryAge: number | null;
+    };
     /**
-     * Send a message to the Superatom service
+     * Start periodic cleanup of expired data cache entries.
      */
-    send(message: Message): void;
+    private startCleanup;
     /**
-     * Register a message handler to receive all messages
+     * Encrypt a payload into a self-contained token.
      */
-    onMessage(handler: (message: IncomingMessage) => void): () => void;
+    private encrypt;
+    /**
+     * Decrypt a token back to the original payload.
+     */
+    private decrypt;
+    /**
+     * Store a query by generating an encrypted token as queryId.
+     * The SQL is encrypted INTO the token — nothing stored in memory.
+     * If data is provided, it's cached temporarily in the data cache.
+     */
+    storeQuery(query: any, data?: any): string;
+    /**
+     * Get a stored query by decrypting its token.
+     * Returns the SQL + any cached result data.
+     */
+    getQuery(queryId: string): {
+        query: any;
+        data: any;
+    } | null;
+    /**
+     * Update cached data for a queryId token
+     */
+    setQueryData(queryId: string, data: any): void;
+    /**
+     * Stop cleanup interval (for graceful shutdown)
+     */
+    destroy(): void;
+}
+declare const queryCache: QueryCache;
+
+/**
+ * Request context — who is asking, carried to wherever it is needed.
+ *
+ * The data seam (`BaseSource.prepareSql()` in the backend) has to know which
+ * user a query is for, so the SQL rewriter has a policy to inject. Identity
+ * arrives here, in the SDK's message handlers; the seam is several layers and
+ * one package away. This module is the carrier for the paths where the async
+ * chain stays intact.
+ *
+ * Design and the paths where it does NOT reach:
+ * backend/docs/REQUEST-CONTEXT-DESIGN.md
+ *
+ * Two rules the rest of the system depends on:
+ *
+ *   1. **Absence is not `system`.** No context means we do not know who is
+ *      asking, which is a different thing from knowing this is a trusted job.
+ *      Conflating them turns every call site anyone forgets into an unpoliced
+ *      one. Trust has to be written down, by name, via `runAsSystem()`.
+ *
+ *   2. **This is not a security boundary on its own.** It carries whatever it
+ *      is given. It is only worth something once the value it carries comes
+ *      from a verified identity rather than the request payload — see the
+ *      Prerequisite section of SQL-AUTHORIZATION-DESIGN.md.
+ */
+/**
+ * Who a unit of work is running on behalf of.
+ *
+ * `system` requires a reason because it appears in the audit log and because
+ * an unexplained escalation is indistinguishable from a bug.
+ */
+type Principal = {
+    kind: 'user';
+    userId: string;
+    orgId?: string;
+    role?: string;
+} | {
+    kind: 'system';
+    reason: string;
+};
+/**
+ * One row restriction, in the shape the rewriter's inject_policies() consumes
+ * directly — no translation layer, deliberately: a mapping step between what an
+ * admin writes and what gets injected is somewhere for the two to drift apart.
+ */
+interface RowFilter {
+    /** Unqualified matches on table name alone; qualified ("dw.FactSales") must match exactly. */
+    table?: string;
+    column: string;
+    op?: 'in' | 'not_in' | 'eq' | 'ne';
+    values: unknown[];
+    /**
+     * How to SAY this restriction to an end user, e.g. "Hyderabad branch".
+     *
+     * Without it the agent has only the predicate, and pastes
+     * `com_trn_documentstamp.LocationId IN (110)` into the answer — accurate and
+     * meaningless to the person reading it. Only whoever writes the policy knows
+     * that 110 is Hyderabad, so only they can supply this.
+     */
+    label?: string;
+}
+/**
+ * What one user may see in one source. `sourceId` is not optional in spirit: a
+ * filter naming a column of one database must never be injected into another's
+ * SQL. Omitting it means "every source", which is only correct for a column that
+ * genuinely exists everywhere.
+ */
+interface SourcePolicy {
+    sourceId?: string | null;
+    /** Default {@link RowFilter.label} for every filter in this policy that lacks its own. */
+    label?: string;
+    rowFilters?: RowFilter[];
+    /** Gate 3. Empty means no table restriction — see SQL-AUTHORIZATION-DESIGN.md. */
+    readableTables?: string[];
+}
+interface RequestContext {
+    principal: Principal;
+    projectId?: string;
+    /**
+     * Access policies resolved ONCE per request, not per query. Empty means
+     * "no restrictions apply". Narrowed to the source being queried at the seam
+     * — see the backend's policy-gate.
+     */
+    policies?: SourcePolicy[];
+    /** Correlates the audit log with a chat turn. */
+    requestId?: string;
+}
+/** The context for the current async chain, or `undefined` if none was established. */
+declare function getRequestContext(): RequestContext | undefined;
+/**
+ * Like `getRequestContext()`, but throws when there is none.
+ *
+ * For call sites that must not proceed anonymously. Prefer this over
+ * `getRequestContext() ?? somethingPermissive` — the fallback is exactly the
+ * silent bypass this module exists to prevent.
+ */
+declare function requireRequestContext(what?: string): RequestContext;
+declare class MissingRequestContextError extends Error {
+    constructor(message: string);
+}
+/** Run `fn` with `ctx` visible to everything it awaits. */
+declare function runWithContext<T>(ctx: RequestContext, fn: () => T): T;
+/** Convenience for the common case: a request on behalf of a signed-in user. */
+declare function runAsUser<T>(user: {
+    userId: string;
+    orgId?: string;
+    role?: string;
+    projectId?: string;
+    requestId?: string;
+    policies?: SourcePolicy[];
+}, fn: () => T): T;
+/**
+ * Declare a unit of work as trusted, naming why.
+ *
+ * For entry points with no user behind them: schedulers, admin tooling, the
+ * cross-machine proxy. `reason` is not decoration — it is what the audit log
+ * shows in place of a user, and it is what makes these paths greppable when
+ * someone asks "what runs unpoliced?".
+ *
+ * Nesting inside a user context deliberately REPLACES it: a system subtask is
+ * an escalation, and it should look like one in the log rather than silently
+ * inheriting a user's restrictions.
+ */
+declare function runAsSystem<T>(reason: string, fn: () => T, opts?: {
+    projectId?: string;
+    requestId?: string;
+}): T;
+/**
+ * Capture the current context so it can be re-entered later.
+ *
+ * For boundaries where the async chain breaks but a reference survives — an
+ * event listener registered outside the request, a callback stored in a
+ * registry. Does NOT help across a process or HTTP boundary (the script
+ * bridge); that needs a token, see the design doc.
+ */
+declare function captureContext(): RequestContext | undefined;
+/** Re-enter a captured context. A no-op wrapper when `ctx` is undefined. */
+declare function withCapturedContext<T>(ctx: RequestContext | undefined, fn: () => T): T;
+/**
+ * Bind a function to the context active at bind time.
+ *
+ * The trap this exists for, stated the right way round (verified, because it
+ * is easy to get backwards): context propagates through ASYNC RESOURCE
+ * creation, and `EventEmitter.emit` is an ordinary synchronous call. So a
+ * plain listener runs in the context active at EMIT time, whatever it was
+ * registered inside. A handler registered during a request and fired later
+ * from another chain therefore sees nothing at all.
+ *
+ * Bind it when the registering context is the one that matters.
+ */
+declare function bindContext<A extends unknown[], R>(fn: (...args: A) => R): (...args: A) => R;
+/** Short label for logs and audit rows: `user:u_123` / `system:alert-scheduler` / `anonymous`. */
+declare function describeContext(ctx?: RequestContext | undefined): string;
+/** True when the context represents a signed-in user rather than a trusted job. */
+declare function isUserContext(ctx?: RequestContext | undefined): boolean;
+
+/**
+ * Deriving "who is asking" from an incoming WebSocket message.
+ *
+ * Separate from `utils/request-context.ts` on purpose: that module is a pure
+ * carrier with no opinion about where identity comes from, this one knows the
+ * message shape and the trust level of each field.
+ *
+ * See backend/docs/REQUEST-CONTEXT-DESIGN.md and the Prerequisite section of
+ * backend/docs/SQL-AUTHORIZATION-DESIGN.md.
+ */
+
+/**
+ * Read access policies out of the admin-authored per-user config.
+ *
+ * The config is free-form JSON typed by a human into an admin field, so every
+ * step here is defensive: a malformed entry is DROPPED, never guessed at. That
+ * is a deliberate trade-off with a sharp edge — a typo'd policy silently
+ * becomes no policy, i.e. unrestricted. Validating shapes against the source
+ * schema (and refusing, rather than dropping) is the fix, and is not built yet.
+ *
+ * Accepts either a single object or an array, so one user can be scoped across
+ * several sources.
+ */
+declare function policiesFromConfig(config: unknown): SourcePolicy[];
+/**
+ * Run `fn` with the caller's identity established.
+ *
+ * Trust order:
+ *
+ *   1. `message.authContext` — stamped by the relay from a verified session.
+ *      Trustworthy. Does not exist yet.
+ *   2. `payload.userId` — sent by the browser, which can put anything there.
+ *      Enough to prove the plumbing works end to end; NOT enough to enforce
+ *      anything on. Used because it is what exists today.
+ *   3. Neither — no context is established at all.
+ *
+ * Case 3 is deliberately not a `system` context. "We don't know who this is"
+ * and "this is a trusted job" must stay distinguishable, or every path that
+ * loses identity silently becomes an unpoliced one. With no context, the data
+ * seam decides what to do (see SA_SQL_POLICY_ENFORCE), and the honest answer
+ * there is a refusal rather than an unfiltered read.
+ */
+declare function runWithMessageIdentity<T>(message: any, fn: () => T): T;
+
+/**
+ * Context tokens — carrying identity across a boundary AsyncLocalStorage cannot.
+ *
+ * The script flow is the one path where the async chain genuinely breaks:
+ * scripts run in a separate OS process and call back into the backend over
+ * loopback HTTP (`script-bootstrap.ts` → `script-bridge.ts`), so the bridge's
+ * request handler starts a fresh async context with no relationship to the
+ * chat turn that launched the script. Nothing ambient crosses that; the
+ * identity has to be handed over explicitly.
+ *
+ * So: the parent mints a token bound to the live context before spawning, the
+ * child presents it on every bridge call, and the bridge resolves it back and
+ * runs the query inside that context.
+ *
+ * The registry is in-memory and process-local, which is exactly right here —
+ * the minting side (script-runner) and the resolving side (script-bridge) are
+ * both in the backend process; only the script itself is elsewhere. A token is
+ * therefore never valid anywhere but the process that issued it, and never
+ * outlives that process.
+ *
+ * See backend/docs/REQUEST-CONTEXT-DESIGN.md.
+ */
+
+/**
+ * Mint a token for the context active right now.
+ *
+ * Returns `undefined` when there is no context — deliberately, so that an
+ * unidentified script run stays unidentified rather than being handed a token
+ * that vouches for nothing. The bridge then sees no token and the data seam
+ * treats it as anonymous, which is the truth.
+ */
+declare function mintContextToken(ttlMs?: number): string | undefined;
+/** Resolve a token back to its context, or `undefined` if unknown or expired. */
+declare function resolveContextToken(token: string | undefined | null): RequestContext | undefined;
+/** Drop a token. Call when the work it was minted for is finished. */
+declare function revokeContextToken(token: string | undefined | null): void;
+/** Diagnostics only. */
+declare function contextTokenCount(): number;
+/** Test seam. */
+declare function clearContextTokens(): void;
+
+/**
+ * Manages conversation history scoped per user + dashboard.
+ * Each user-dashboard pair has its own isolated history that expires after a configurable TTL.
+ */
+declare class DashboardConversationHistory {
+    private histories;
+    private ttlMs;
+    private maxEntries;
+    private cleanupInterval;
+    constructor();
+    /**
+     * Set the TTL for dashboard histories
+     * @param minutes - TTL in minutes
+     */
+    setTTL(minutes: number): void;
+    /**
+     * Set max entries per dashboard
+     */
+    setMaxEntries(max: number): void;
+    /**
+     * Add a conversation entry for a user's dashboard
+     */
+    addEntry(dashboardId: string, userPrompt: string, componentSummary: string, userId?: string): void;
+    /**
+     * Get formatted conversation history for a user's dashboard
+     */
+    getHistory(dashboardId: string, userId?: string): string;
+    /**
+     * Clear history for a specific user's dashboard
+     */
+    clearDashboard(dashboardId: string, userId?: string): void;
+    /**
+     * Clear all dashboard histories
+     */
+    clearAll(): void;
+    /**
+     * Start periodic cleanup of expired histories
+     */
+    private startCleanup;
+    /**
+     * Stop cleanup interval (for graceful shutdown)
+     */
+    destroy(): void;
+}
+declare const dashboardConversationHistory: DashboardConversationHistory;
+
+/**
+ * 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;
+
+/**
+ * Coding-agent driver contract — one shape over every harness (codex today;
+ * claude-code / opencode / pi next). Callers depend on this file only, never on
+ * a harness SDK, so swapping the agent behind a task is a config change.
+ *
+ * Deliberately narrower than the harness SDKs it wraps: the three things a
+ * production run needs and that harness abstractions usually omit — real abort,
+ * real token accounting, and structured tool args — are part of the contract,
+ * not per-driver extras.
+ */
+type AgentEventKind = 'turn' | 'message' | 'reasoning' | 'command' | 'tool' | 'file' | 'todo' | 'error';
+interface AgentEvent {
+    kind: AgentEventKind;
+    /** Stable across started→updated→completed, so a UI updates one block in place. */
+    id?: string;
+    text?: string;
+    command?: string;
+    output?: string;
+    /** Tool calls carry real parsed args — never SQL scraped back out of a shell string. */
+    tool?: {
+        server?: string;
+        name: string;
+        args?: unknown;
+    };
+    status?: 'in_progress' | 'completed' | 'failed';
+    done?: boolean;
+}
+interface AgentUsage {
+    inputTokens: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    /** Tool + command invocations. With tokens, separates "silently did nothing" from a real run. */
+    toolCalls: number;
+    /** Only when the harness reports it — codex reports tokens but not cost. */
+    costUSD?: number;
+}
+interface AgentRunHandlers {
+    /** Formatted live stream: assistant text deltas plus one-line tool/command markers. */
+    onOutput?: (chunk: string) => void;
+    onEvent?: (event: AgentEvent) => void;
+    /** Assistant prose only — safe to show a non-technical user as progress. */
+    onNarration?: (text: string) => void;
+    onUsage?: (usage: AgentUsage) => void;
+    /**
+     * Polled once the turn is live. When it returns true the run ends immediately —
+     * for tasks whose deliverable is a file, the moment it exists there is nothing
+     * left to wait for.
+     */
+    doneWhen?: () => boolean | Promise<boolean>;
+}
+type AgentRunStatus = 'completed' | 'early' | 'aborted' | 'error';
+interface AgentRunResult {
+    status: AgentRunStatus;
+    /** The final assistant message. */
+    answer: string;
+    ms: number;
+    usage: AgentUsage;
+    /**
+     * Set when status is 'error'. Covers stream-reported failures too, which arrive
+     * as events rather than thrown exceptions — a swallowed provider error is the
+     * failure mode that otherwise looks like a successful empty run.
+     */
+    error?: string;
+    sessionId?: string;
+}
+interface McpServerSpec {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+interface CodingAgentSessionOptions {
+    /** Working directory the agent operates in. Scope it to a runtime dir, not a source checkout. */
+    cwd: string;
+    model?: string;
+    /** Resume a prior conversation — the value a previous run returned as sessionId. */
+    resumeId?: string;
+    /** Tools, as MCP servers. Keyed by server name, which shows up on every tool event. */
+    mcpServers?: Record<string, McpServerSpec>;
+    /**
+     * Extra env for the agent process. By default only a small allowlist is passed
+     * through (see ENV_ALLOWLIST) so an agent with shell access can't read the
+     * backend's own secrets out of its environment.
+     */
+    env?: Record<string, string>;
+    /** Opt out of env scrubbing. Only for local debugging. */
+    inheritEnv?: boolean;
+}
+interface CodingAgentSession {
+    readonly harness: string;
+    /** Structured event log vs. a raw terminal stream — the UI picks its renderer from this. */
+    readonly kind: 'events' | 'pty';
+    run(prompt: string, handlers?: AgentRunHandlers, signal?: AbortSignal): Promise<AgentRunResult>;
+    /** Rolling structured events, for replay when a client reconnects mid-run. */
+    events(): AgentEvent[];
+    /** Rolling formatted text, same purpose as events() for text-oriented views. */
+    buffer(): string;
+    busy(): boolean;
+    /** Persist this and pass it back as resumeId to continue the conversation. */
+    sessionId(): string | undefined;
+    /** Abandon the conversation; the next run starts fresh. */
+    reset(): void;
+    dispose(): void;
+}
+
+/**
+ * Harness registry. Kept separate from index.ts so collection.ts can reach the
+ * factory without importing the module's own barrel (a cycle tsup would have to
+ * resolve at bundle time).
+ */
+type Harness = 'codex';
+declare function createCodingAgentSession(harness: Harness, opts: CodingAgentSessionOptions): CodingAgentSession;
+
+/**
+ * Codex driver — OpenAI Codex via @openai/codex-sdk.
+ *
+ * FORMAT CONTRACT: written against @openai/codex-sdk 0.149.1. Harness event
+ * shapes drift; if the event log goes blank after an SDK bump, check normEvent
+ * against the package's dist/index.d.ts first.
+ *
+ * Three things this leans on that the SDK gives natively, so we don't reinvent
+ * them: TurnOptions.signal (real cancellation), TurnCompletedEvent.usage (token
+ * accounting), and mcp_tool_call items (tool args arrive parsed, not scraped
+ * out of a shell command string).
+ *
+ * The package is an optionalDependency: every deployment gets it, but an
+ * install that cannot fetch the ~309MB platform binary skips it rather than
+ * failing. It is therefore loaded dynamically and its types mirrored
+ * structurally below, so a VM without it still builds, starts, and runs
+ * everything else — only the coding agent reports itself unavailable.
+ */
+type CodexSandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
+type CodexReasoningEffort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultra';
+interface CodexSessionOptions extends CodingAgentSessionOptions {
+    reasoningEffort?: CodexReasoningEffort;
+    /**
+     * Filesystem reach. Default 'workspace-write' — the agent writes its
+     * deliverable into cwd and nothing else. 'danger-full-access' hands a
+     * shell-capable agent the whole box; don't use it on a client VM.
+     */
+    sandboxMode?: CodexSandboxMode;
+    /** Network for commands the agent runs. Off by default; MCP tools don't need it. */
+    networkAccessEnabled?: boolean;
+    apiKey?: string;
+    baseUrl?: string;
+    /** Raw `--config` overrides merged into the codex config. */
+    extraConfig?: Record<string, unknown>;
+    approvalPolicy?: 'never' | 'on-request' | 'on-failure' | 'untrusted';
+}
+declare function createCodexSession(opts: CodexSessionOptions): CodingAgentSession;
+
+/**
+ * What makes an agent fire.
+ *
+ * Declared ON the definition, deliberately. If triggers lived at the call sites
+ * instead — a counter in the conversation handler, a hook in the kb-nodes
+ * collection — then adding an agent would mean editing unrelated files across
+ * the backend, and no one file would tell you when an agent actually runs.
+ * Here, an agent's folder plus its definition is the whole story.
+ *
+ * The deployment's only job is to announce that something happened:
+ *
+ *   emitAgentEvent('conversation.answered', { threadId })
+ *   emitAgentEvent('kb-node.changed', { id, op: 'update' })
+ *
+ * Which agents care, and how many events it takes, is the agents' business.
+ * The emitter therefore speaks the WORLD's vocabulary, never any one agent's —
+ * translating an event into a particular agent's input is `buildInput` below.
+ */
+/** One announced fact, as it reaches a trigger. */
+interface TriggerEvent {
+    /** The event name passed to emitAgentEvent. */
+    name: string;
+    payload?: unknown;
+}
+/**
+ * Turns the events that caused this run into the agent's `input`.
+ *
+ * Takes the whole list, not one payload, because every batching trigger here
+ * fires for MANY events: a debounced burst, or N counted occurrences. Handing
+ * over only the last one silently discarded the rest — five edited nodes became
+ * one.
+ *
+ * Omit it and the agent receives the most recent payload unchanged, which is
+ * the historical behaviour. Any agent that batches should declare one.
+ */
+type BuildTriggerInput = (events: TriggerEvent[]) => unknown;
+type AgentTrigger = 
+/** Only runCodingAgent(). The default. */
+{
+    type: 'manual';
+}
+/** Every N milliseconds while the process is up. Fires with no events. */
+ | {
+    type: 'interval';
+    everyMs: number;
+    buildInput?: BuildTriggerInput;
+}
+/**
+ * On a named event. `debounceMs` collapses a burst into one run — editing
+ * five knowledge nodes in a row is one reason to rebuild, not five. The run
+ * still receives all five events; only the RUNS are collapsed.
+ */
+ | {
+    type: 'event';
+    on: string | string[];
+    debounceMs?: number;
+    buildInput?: BuildTriggerInput;
+}
+/**
+ * Every Nth occurrence of an event. The events are PERSISTED, so "after 10
+ * questions" survives a restart instead of silently starting over.
+ */
+ | {
+    type: 'count';
+    on: string;
+    every: number;
+    buildInput?: BuildTriggerInput;
+};
+interface TriggerFireInfo {
+    agentId: string;
+    /** What set it off, for the log line. */
+    reason: string;
+    /** Everything that caused this run, in arrival order. */
+    events: TriggerEvent[];
+    /** What buildInput produced — exactly what the agent was handed. */
+    input?: unknown;
+}
+/** Notified after every triggered run — for recording history or alerting. */
+type RunListener = (record: AgentRunRecord, info: TriggerFireInfo) => void;
+declare function onAgentRun(fn: RunListener): () => void;
+/**
+ * Tell the agents something happened. Safe to call from anywhere, including a
+ * request path — it never throws and never blocks: matching runs are started,
+ * not awaited.
+ */
+declare function emitAgentEvent(event: string, payload?: unknown): void;
+/**
+ * Start interval triggers. Call once at startup, after registerCodingAgents.
+ * Event and count triggers need nothing started — they wake on emitAgentEvent.
+ */
+declare function startAgentTriggers(): void;
+declare function stopAgentTriggers(): void;
+/** What fires each agent — for a startup log or an admin screen. */
+declare function describeTriggers(): Array<{
+    agentId: string;
+    triggers: string[];
+}>;
+
+/**
+ * What a coding agent IS.
+ *
+ * An agent is a job description, not code that does the job: instructions, the
+ * inputs it should be handed, the tools it may reach, the deliverable it must
+ * produce, and what we do with that deliverable. The agent itself decides HOW —
+ * it can read the inputs, write and run scripts over them, check its own work,
+ * and iterate. That is the whole reason for using a coding agent rather than a
+ * single LLM call: the job's data never has to fit in a context window.
+ *
+ * Adding an agent is a folder with a system.md, one file implementing this
+ * interface, and one line in the registry. Nothing else changes.
+ */
+/** The disposable directory one run happens in. */
+interface Workspace {
+    /** Absolute path the agent runs in. Everything below is relative to it. */
+    dir: string;
+    /** Unique per run — also the folder name, so runs never collide. */
+    runId: string;
+    /** Write a file into the workspace, creating parent directories. */
+    write(relPath: string, contents: string): Promise<void>;
+    /** Write JSON (pretty-printed — the agent reads these by eye as often as by script). */
+    writeJson(relPath: string, value: unknown): Promise<void>;
+    /** Write one JSON object per line. The right shape for anything the agent will stream or grep. */
+    writeJsonl(relPath: string, rows: unknown[]): Promise<void>;
+    /** Read a file the agent produced. Returns null when it isn't there. */
+    read(relPath: string): Promise<string | null>;
+    /** Absolute path for a workspace-relative path — for telling the agent where to write. */
+    pathTo(relPath: string): string;
+}
+/** Minimal validator shape, so this file needn't depend on a schema library. */
+interface OutputValidator<T> {
+    /** Throw with a useful message, or return the parsed value. Zod's `.parse` satisfies this. */
+    parse(value: unknown): T;
+}
+interface OutputContract<T> {
+    /**
+     * Workspace-relative path the agent must write, e.g. 'out/concepts.json'.
+     * Nothing else counts as the deliverable: the run ends the moment this
+     * appears, and a run that finishes without it is a failure, not a partial
+     * success.
+     */
+    file: string;
+    /** Validated before anything is persisted, so a malformed run fails loudly and applies nothing. */
+    schema: OutputValidator<T>;
+}
+/** What apply() reports back — surfaced in the run record and to the caller. */
+interface ApplySummary {
+    /** One line a human can read in a log or the UI. */
+    summary: string;
+    /** Whatever counts for this agent: {created, updated, skipped}, etc. */
+    counts?: Record<string, number>;
+    /** Anything the caller may want to inspect or show. */
+    details?: unknown;
+}
+interface AgentRunContext {
+    projectId?: string;
+    userId?: string;
+    /**
+     * This run's id — also the workspace directory name. Passed so apply() can
+     * stamp whatever it persists with the run that produced it, which is the
+     * only link from a stored result back to the inputs and scripts behind it.
+     */
+    runId?: string;
+    /** The run's workspace, for an apply() that needs a file the agent left. */
+    workspaceDir?: string;
+    /** Cancels the run; forwarded to the driver's real abort. */
+    signal?: AbortSignal;
+    /** Live progress. Populated for chat mode; a task run may also stream to a log. */
+    onOutput?: (chunk: string) => void;
+    onEvent?: (event: AgentEvent) => void;
+    onUsage?: (usage: AgentUsage) => void;
+}
+/**
+ * How much an agent carries between runs.
+ *
+ * Codex manages its own context: it tracks the window and compacts when it
+ * crosses `auto_compact_token_limit`, emitting a ContextCompacted event. That
+ * happens with no involvement from us, so a persistent session survives
+ * indefinitely on its own. (The mechanism is in the engine but not the
+ * TypeScript SDK — Thread exposes only id/run/runStreamed — which is why there
+ * is nothing here to call.)
+ *
+ * What compaction cannot do is make the session authoritative. It summarises to
+ * make room, so detail is lost by design; and ~/.codex/sessions is a directory
+ * on one machine, not the database. So durable facts belong in `memory/` files
+ * and in the tables the agent writes through apply(), with the session free to
+ * compact itself as it likes. Memory on disk, context managed by codex.
+ */
+interface SessionPolicy {
+    /**
+     * 'per-run'    a fresh harness session each time (default).
+     * 'persistent' resume the same session across runs, so the agent keeps its
+     *              working context. Always paired with durable files — never rely
+     *              on it alone.
+     */
+    scope?: 'per-run' | 'persistent';
+    /**
+     * 'per-run'    a throwaway directory per run (default); pruned by keepRuns.
+     * 'persistent' one directory the agent owns across runs. `memory/` survives
+     *              untouched; `input/` is cleared each run so a stale input can
+     *              never be mistaken for this run's.
+     */
+    workspace?: 'per-run' | 'persistent';
+    /**
+     * Safety valve, not the compaction mechanism — codex already compacts on its
+     * own. Starts a fresh session after this many runs while keeping the
+     * workspace, for when you want a hard ceiling on how much summarised history
+     * an agent drags along, or a clean slate on a cadence. Omit by default.
+     */
+    resetAfterTurns?: number;
+}
+interface CodingAgentDefinition<TInput = unknown, TOutput = unknown> {
+    /** Stable id: the folder name under .prompts/coding-agents, and the key callers use. */
+    id: string;
+    /** Human-readable, for the UI and logs. */
+    title: string;
+    /** One line: what this agent is for. */
+    description?: string;
+    /**
+     * 'task' — headless. Runs from a cron, an event, or a command; produces the
+     *   deliverable and applies it. Nobody is watching.
+     * 'chat' — a person is typing. Streams, keeps its session across turns, and
+     *   is not required to produce a deliverable at all.
+     */
+    mode: 'task' | 'chat';
+    /**
+     * Directory holding this agent's system.md. Defaults to
+     * `<promptRoot>/<id>`. The runner copies system.md into the workspace as
+     * AGENTS.md, which is the filename the harness actually reads from its
+     * working directory — that indirection is what lets the instructions stay
+     * version-controlled while the workspace stays disposable.
+     */
+    promptDir?: string;
+    /** Override the deployment default for this agent alone. */
+    harness?: Harness;
+    model?: string;
+    /**
+     * Let this agent's shell reach the network. Off by default.
+     *
+     * Needed by any agent given bridge shims (writeBridgeShims), which reach the
+     * backend over localhost HTTP. Note the sandbox has no host allowlist, so
+     * this grants the whole internet, not just the bridge — scope it to agents
+     * that genuinely need it.
+     */
+    networkAccessEnabled?: boolean;
+    /**
+     * Filesystem reach. Defaults to the driver's 'workspace-write'.
+     * 'danger-full-access' removes the sandbox entirely — it is the only mode in
+     * which codex permits MCP tool calls headlessly, which is exactly why the
+     * shims exist instead.
+     */
+    sandboxMode?: 'read-only' | 'workspace-write' | 'danger-full-access';
+    /**
+     * Tools this agent may reach, as MCP servers. Deliberately per-agent: an
+     * agent that reads the knowledge base has no business holding a database
+     * connection. Omit for an agent that only needs the files it is given.
+     */
+    tools?: Record<string, McpServerSpec>;
+    /**
+     * Put the job's inputs in the workspace as FILES, not prompt text. A coding
+     * agent can grep, aggregate and script over a file; it cannot do any of that
+     * with text pasted into its prompt, and a large input would not fit there
+     * anyway.
+     */
+    prepare?(ws: Workspace, input: TInput, ctx: AgentRunContext): Promise<void>;
+    /**
+     * The short framing sent as the turn's prompt. Keep it short — the standing
+     * instructions belong in system.md and the data belongs in files. Defaults
+     * to a generic instruction naming the output path.
+     */
+    buildPrompt?(ws: Workspace, input: TInput, ctx: AgentRunContext): string | Promise<string>;
+    /** Required for 'task' mode; meaningless for 'chat'. */
+    output?: OutputContract<TOutput>;
+    /**
+     * Persist the validated deliverable — through existing services, never raw
+     * SQL from inside the agent. Keeping the write on this side is what makes a
+     * run auditable and replayable: the artifact on disk is the same input
+     * apply() would get again tomorrow.
+     */
+    apply?(result: TOutput, input: TInput, ctx: AgentRunContext): Promise<ApplySummary>;
+    /**
+     * What makes this agent run. Declared here so an agent's folder plus this
+     * file is the complete story of when it fires. See triggers.ts.
+     */
+    trigger?: AgentTrigger | AgentTrigger[];
+    /**
+     * WHO this agent's accumulated state belongs to. Distinct from `mode`, which
+     * is only how a run was triggered — the two were conflated before, so a
+     * project agent someone chatted with silently got a private per-thread
+     * workspace and lost its memory.
+     *
+     *   'project'  ONE workspace and session for the whole deployment, whoever
+     *              invokes it. A concept builder is project-wide: everything it
+     *              learns should accumulate in one place, and a chat turn joins
+     *              that same workspace rather than forking a copy. Concurrent
+     *              runs serialise.
+     *   'user'     one per user, shared across that user's threads.
+     *   'thread'   one per conversation — an ordinary chat assistant.
+     *
+     * Default: 'thread' for mode 'chat', 'project' for mode 'task'.
+     */
+    scope?: 'project' | 'user' | 'thread';
+    /**
+     * Kill the turn the moment the deliverable file appears, instead of letting
+     * the agent finish.
+     *
+     * Off by default, and the reason is measured: an agent typically writes its
+     * output and then keeps going — verifying, re-reading, summarising — so
+     * stopping at the write cuts the turn well before codex emits
+     * turn.completed, which is the only event carrying token usage. Early stop
+     * therefore costs you all cost tracking, and skips the agent's own
+     * self-check. Turn it on for a long-tailed agent where the file really is
+     * the last thing that matters.
+     */
+    stopOnDeliverable?: boolean;
+    /** What this agent carries between runs. Default: nothing (fresh session and workspace). */
+    session?: SessionPolicy;
+    /** Hard cap for one run. Default 15 minutes. */
+    timeoutMs?: number;
+}
+/** What a completed run reports. */
+interface AgentRunRecord<TOutput = unknown> {
+    agentId: string;
+    runId: string;
+    /** The run's directory — instructions, inputs, scripts and output all still there. */
+    workspaceDir: string;
+    /**
+     * 'early'   the deliverable landed and we stopped the turn — a success, kept
+     *           distinct from 'completed' so a masked early exit is visible.
+     * 'skipped' another run of this agent held the lock; nothing was done.
+     */
+    status: 'completed' | 'early' | 'aborted' | 'error' | 'skipped';
+    /** The agent's closing message. */
+    answer: string;
+    ms: number;
+    usage: AgentUsage;
+    /** Present when the agent produced and validated its deliverable. */
+    output?: TOutput;
+    /** Present when apply() ran. */
+    applied?: ApplySummary;
+    error?: string;
+    /** Harness session id, for resuming a chat. */
+    sessionId?: string;
+}
+
+/**
+ * The agent registry — one place that knows which agents this deployment has.
+ *
+ * Deliberately a plain module-level map rather than something on the SDK: a
+ * cron job, a CLI command and the websocket handler all need to reach the same
+ * agents, and only one of those has an SDK instance in hand.
+ */
+interface CodingAgentsConfig {
+    /**
+     * Where per-agent instruction folders live. Each agent reads
+     * `<promptRoot>/<agent.id>/system.md`.
+     * Default: `<cwd>/.prompts/coding-agents`, matching the .prompts convention
+     * the rest of the deployment already uses.
+     */
+    promptRoot?: string;
+    /**
+     * Root for run workspaces: `<runtimeDir>/<agentId>/<runId>/`. Regenerated
+     * per run and safe to gitignore — deliberately not inside promptRoot, which
+     * is version-controlled.
+     * Default: `<cwd>/.coding-agent-runtime`.
+     */
+    runtimeDir?: string;
+    /** Fallback harness for agents that don't name one. */
+    harness?: Harness;
+    /** Fallback model. */
+    model?: string;
+    /** Tools every agent gets, merged under each agent's own (the agent's win on a name clash). */
+    sharedTools?: Record<string, McpServerSpec>;
+    /** Keep this many run directories per agent; older ones are pruned. 0 keeps everything. */
+    keepRuns?: number;
+}
+/**
+ * Register this deployment's agents. Call once at startup.
+ *
+ * Re-registering an id replaces it — that keeps hot-reload working in dev and
+ * makes a double registration a no-op rather than a silent duplicate.
+ */
+declare function registerCodingAgents(definitions: CodingAgentDefinition<any, any>[], options?: CodingAgentsConfig): void;
+declare function getCodingAgent(id: string): CodingAgentDefinition<any, any> | undefined;
+declare function listCodingAgents(): Array<{
+    id: string;
+    title: string;
+    description?: string;
+    mode: 'task' | 'chat';
+}>;
+declare function getCodingAgentsConfig(): Required<Pick<CodingAgentsConfig, "harness" | "promptRoot" | "runtimeDir" | "keepRuns">> & CodingAgentsConfig;
+
+interface RunAgentOptions<TInput> extends AgentRunContext {
+    input?: TInput;
+    /** Scopes a 'thread' agent. Ignored by a project-scoped one. */
+    threadId?: string;
+    /**
+     * Escape hatch that pins the workspace directory outright. Almost never
+     * right — it defeats the agent's own scope, which is how a project agent
+     * ends up with a private copy per caller. Left for tests and one-offs.
+     */
+    workspaceDir?: string;
+    /** Resume the harness session — chat continuity across turns and restarts. */
+    resumeId?: string;
+    /** Overrides the definition's prompt entirely. Chat mode: this is the user's message. */
+    prompt?: string;
+    /**
+     * A person is typing, rather than a job running.
+     *
+     * For an agent whose mode is 'task' this turns off the JOB — prepare(), the
+     * deliverable contract and apply() are one unit that sets work up and
+     * consumes it, and a conversation should do neither. The turn joins the
+     * workspace as it stands and its answer is the whole result.
+     *
+     * Without this, chatting with a task agent could only ever fail: the user's
+     * message replaces the prompt that names the output path, so the agent never
+     * writes the deliverable, and the run is then reported as an error despite
+     * having answered perfectly well. Worse, prepare() ran on every turn — for a
+     * batching agent that means a chat turn quietly consumed a batch of work.
+     *
+     * An agent whose mode is 'chat' is unaffected: its prepare() is per-turn
+     * context setup, not job setup, so it still runs.
+     */
+    chat?: boolean;
+}
+/**
+ * Run one agent, end to end.
+ *
+ * Never throws for an agent-side failure — a bad run comes back as a record
+ * with status 'error', because callers are usually crons and message handlers
+ * that must keep going. Genuinely programmer errors (unknown agent id) do throw.
+ */
+declare function runCodingAgent<TInput = unknown, TOutput = unknown>(agentId: string, options?: RunAgentOptions<TInput>): Promise<AgentRunRecord<TOutput>>;
+
+/**
+ * Write `./sources` and `./query` into an agent's workspace: read-only data
+ * access as plain executables it runs with bash.
+ *
+ * Why not MCP: codex gates MCP tool calls on the sandbox. Under any sandboxed
+ * mode they need approval, and a headless run must set approvalPolicy 'never',
+ * which denies rather than grants — measured, not assumed. Only
+ * danger-full-access permits them, and that removes the filesystem sandbox
+ * entirely. Bash commands under workspace-write need no approval, so a shim
+ * buys the same capability while the agent stays confined to its workspace.
+ *
+ * An MCP server for this was written and then removed: the same approval gate
+ * applies to the Agents chat tab, which is equally headless from codex's point
+ * of view, so it was unreachable everywhere. `mcpServers` stays plumbed through
+ * the driver for third-party servers; see git history for the removed one.
+ *
+ * The cost is structured tool events: calls arrive as `bash → ./query ...`
+ * rather than typed items with parsed arguments. That matters for a chat UI
+ * with a human watching; for a headless task agent it does not.
+ *
+ * Requires networkAccessEnabled on the session — the shim reaches the bridge
+ * over HTTP, and that is the whole point of it.
+ */
+declare function writeBridgeShims(ws: Workspace, opts: {
+    bridgeUrl: string;
+    sources: Array<{
+        id: string;
+        name?: string;
+        description?: string;
+    }>;
+    maxRows?: number;
+}): void;
+
+/**
+ * Read-only SQL guard for any path that hands an agent a database.
+ *
+ * Defence in depth, NOT a boundary. The agent has a shell and can reach the
+ * bridge directly, so anything enforced only here is advisory — it stops
+ * mistakes, not determination. The real boundary is a database user without
+ * write permission; this exists so a confused agent gets a clear correction
+ * instead of a silent partial write.
+ */
+/** Throws with a message written for the agent to act on. */
+declare function assertReadOnlySql(sql: string): void;
+
+/**
+ * The 'coding-agent'.'run' collection — a chat turn against a coding agent.
+ *
+ * Generic on purpose: nothing here knows about dashboards, reports, or any
+ * particular deliverable. It owns what every harness-backed chat needs — one
+ * session per thread, a per-thread workspace, a run lock, and forwarding the
+ * driver's callbacks to the transport. Task-specific flows (prompt assembly, a
+ * draft-file contract, persistence) build on top of this rather than inside it.
+ */
+interface CodingAgentCollectionConfig {
+    /**
+     * Root for per-thread agent workspaces. Each thread gets its own directory
+     * underneath, so one chat can't read or clobber another's files, and none of
+     * them sit inside the backend's own source tree.
+     * Default: `<process.cwd()>/.coding-agent-runtime`.
+     */
+    runtimeDir?: string;
+    /** Default harness when the request doesn't name one. */
+    harness?: Harness;
+    model?: string;
+    /** Tools, as MCP servers, handed to every session. */
+    mcpServers?: Record<string, McpServerSpec>;
+}
+declare function registerCodingAgentCollection(sdk: SuperatomSDK, config?: CodingAgentCollectionConfig): void;
+
+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 most recent script-backed answer in this thread — the one an `edit`
+     * targets. Rendered as its own prompt section (never merged into the ranked
+     * catalog) so the `edit` rules have an unambiguous referent.
+     *
+     * `candidates` holds at most one entry (see doMatch) — `edit` always means
+     * "the answer I just got", so there is nothing else to show here.
+     *
+     * 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" against
+     * this one script's own context.
+     */
+    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;
+    /**
+     * Names resolved for this run, handed to getAnalysis/getComponents as their
+     * 5th argument. Supplying these is what stops "the narrative needs the
+     * subsidiary's name" from being a reason to rewrite getData and re-query.
+     */
+    entities?: ResolvedEntityRef[];
+    /**
+     * Restrictions an authorization policy imposed on this run, handed to
+     * getAnalysis/getComponents as their 6th argument.
+     *
+     * Supplied at RUN time rather than written into the recipe: a policy is
+     * per-request and mutable, a recipe is durable. Baked in, it goes stale the
+     * moment the user's scope changes — the recipe would keep naming the old
+     * scope while the seam injects the new one. Supplied here, a replay always
+     * describes what was actually applied to THAT run.
+     */
+    appliedPolicies?: string[];
+}
+/**
+ * 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;
+    private url;
+    private apiKey?;
+    private projectId;
+    private type;
+    private bundleDir;
+    private messageHandlers;
+    private messageTypeHandlers;
+    private connected;
+    private reconnectAttempts;
+    private maxReconnectAttempts;
+    private collections;
+    private components;
+    private tools;
+    private workflows;
+    private anthropicApiKey;
+    private groqApiKey;
+    private geminiApiKey;
+    private openaiApiKey;
+    private llmProviders;
+    private databaseType;
+    private modelStrategy;
+    private mainAgentModel;
+    private sourceAgentModel;
+    private dashCompModels?;
+    private conversationSimilarityThreshold;
+    private userManager;
+    private dashboardManager;
+    private reportManager;
+    private pingInterval;
+    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
+     * Tries to load from file system first, then falls back to hardcoded prompts
+     */
+    private initializePromptLoader;
+    /**
+     * Initialize UserManager for the project
+     */
+    private initializeUserManager;
+    /**
+     * Get the UserManager instance for this SDK
+     */
+    getUserManager(): UserManager;
+    /**
+     * Initialize DashboardManager for the project
+     */
+    private initializeDashboardManager;
+    /**
+     * Get the DashboardManager instance for this SDK
+     */
+    getDashboardManager(): DashboardManager;
+    /**
+     * Initialize ReportManager for the project
+     */
+    private initializeReportManager;
+    /**
+     * Get the ReportManager instance for this SDK
+     */
+    getReportManager(): ReportManager;
+    /**
+     * Connect to the Superatom WebSocket service
+     */
+    connect(): Promise<void>;
+    /**
+     * Handle incoming WebSocket messages
+     */
+    private handleMessage;
+    /**
+     * Send a message to the Superatom service.
+     * Returns true if the message was sent, false if the WebSocket is not connected.
+     * Does NOT throw on closed connections — callers can check the return value if needed.
+     */
+    send(message: Message): 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
+     */
+    onMessage(handler: (message: IncomingMessage) => void): () => void;
     /**
      * Register a handler for a specific message type
      */
@@ -2321,6 +5813,14 @@ 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
      */
@@ -2329,6 +5829,29 @@ 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.
+     *
+     * Workflows are pre-built multi-step UI flows the main agent can pick when
+     * the user's prompt matches a workflow's `whenToUse` trigger. Picking a
+     * workflow short-circuits analysis text + dashboard component generation —
+     * the workflow component is returned directly, with the LLM-extracted props.
+     */
+    setWorkflows(workflows: WorkflowDescriptor[]): void;
+    /**
+     * Get the registered workflow components.
+     */
+    getWorkflows(): WorkflowDescriptor[];
     /**
      * Apply model strategy to all LLM provider singletons
      * @param strategy - 'best', 'fast', or 'balanced'
@@ -2343,6 +5866,20 @@ declare class SuperatomSDK {
      * Get current model strategy
      */
     getModelStrategy(): ModelStrategy;
+    /**
+     * Apply conversation similarity threshold to all LLM provider singletons
+     * @param threshold - Value between 0 and 1 (e.g., 0.8 = 80% similarity required)
+     */
+    private applyConversationSimilarityThreshold;
+    /**
+     * Set conversation similarity threshold at runtime
+     * @param threshold - Value between 0 and 1 (e.g., 0.8 = 80% similarity required)
+     */
+    setConversationSimilarityThreshold(threshold: number): void;
+    /**
+     * Get current conversation similarity threshold
+     */
+    getConversationSimilarityThreshold(): number;
 }
 
-export { type Action, BM25L, type BM25LOptions, type BaseLLMConfig, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CollectionHandler, type CollectionOperation, type DBUIBlock, type DatabaseType, type HybridSearchOptions, type IncomingMessage, type KbNodesQueryFilters, type KbNodesRequestPayload, LLM, type LLMUsageEntry, type LogLevel, type Message, type ModelStrategy, type OutputField, type RerankedResult, SDK_VERSION, STORAGE_CONFIG, SuperatomSDK, type SuperatomSDKConfig, type TaskType, Thread, ThreadManager, type Tool$1 as Tool, type ToolOutputSchema, UIBlock, UILogCollector, type User, UserManager, type UsersData, anthropicLLM, geminiLLM, groqLLM, hybridRerank, llmUsageLogger, logger, openaiLLM, rerankChromaResults, rerankConversationResults, userPromptErrorLogger };
+export { type AgentConfig, type AgentEvent, type AgentResponse, type AgentRunContext, type AgentRunHandlers, type AgentRunRecord, type AgentRunResult, type AgentTrigger, type AgentUsage, type ApplySummary, BM25L, type BM25LOptions, type BaseLLMConfig, type BuildTriggerInput, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CodexSessionOptions, type CodingAgentCollectionConfig, type CodingAgentDefinition, type CodingAgentSession, type CodingAgentSessionOptions, type CodingAgentsConfig, type CollectionHandler, type CollectionOperation, type DBUIBlock, DEFAULT_AGENT_CONFIG, type DashboardAgentCollectionConfig, type DatabaseType, type Harness, type HybridSearchOptions, type IncomingMessage, type KbNodesQueryFilters, type KbNodesRequestPayload, LLM, type LLMUsageEntry, type LogLevel, MainAgent, type McpServerSpec, type Message, MissingRequestContextError, type ModelStrategy, type OutputContract, type OutputField, type OutputValidator, type Principal, type RequestContext, type RerankedResult, type RowFilter, type RunAgentOptions, STORAGE_CONFIG, type ScriptComponentSpec, ScriptMatcher, type ScriptParameter, type ScriptRecipe, type ScriptRecipeMetaRow, type ScriptRecipeStore, type ScriptResult, ScriptStore, type ScriptStoreOptions, type SelectedWorkflow, type SourcePolicy, SuperatomSDK, type SuperatomSDKConfig, type TaskType, Thread, ThreadManager, type Tool$1 as Tool, type ToolOutputSchema, type TriggerEvent, type TriggerFireInfo, UIBlock, UILogCollector, type User, UserManager, type UsersData, type WorkflowDescriptor, type Workspace, anthropicLLM, assertReadOnlySql, bindContext, captureContext, clearContextTokens, contextTokenCount, createCodexSession, createCodingAgentSession, dashboardConversationHistory, dataFingerprint, describeContext, describeTriggers, emitAgentEvent, extractNamedExport, geminiLLM, getCodingAgent, getCodingAgentsConfig, getRequestContext, groqLLM, hybridRerank, isUserContext, listCodingAgents, llmUsageLogger, logger, mintContextToken, normalizeScriptBody, onAgentRun, openaiLLM, policiesFromConfig, queryCache, registerCodingAgentCollection, registerCodingAgents, registerDashboardAgentCollection, requireRequestContext, rerankChromaResults, rerankConversationResults, resolveContextToken, resolveScriptRecipeStore, revokeContextToken, runAsSystem, runAsUser, runCodingAgent, runScript, runWithContext, runWithMessageIdentity, startAgentTriggers, stopAgentTriggers, userPromptErrorLogger, withCapturedContext, writeBridgeShims };