@superatomai/sdk-node 0.0.6-s → 0.0.7-dsp

package/dist/index.d.mts

@@ -1406,6 +1406,10 @@ interface ExecutedToolInfo {
         _recordsShown: number;
         _metadata?: any;
         _sampleData: any[];
+        /** Bounded summary over the FULL fetched result (complete structure). */
+        _summary?: any;
+        /** Up to MAIN_AGENT_COMPLETE_ROWS rows — the complete result when small. */
+        _mainAgentRows?: any[];
     };
     outputSchema?: any;
     sourceSchema?: string;
@@ -1619,8 +1623,16 @@ interface AgentWrittenScript {
  * Controls limits, models, and behavior.
  */
 interface AgentConfig {
-    /** Max rows a source agent can return (default: 50) */
+    /** 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 */
@@ -1674,8 +1686,18 @@ interface ScriptRecipe {
     tables: string[];
     /** Parameter definitions — what can vary */
     parameters: ScriptParameter[];
-    /** The script function body as a string */
+    /** 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 */
@@ -1713,7 +1735,7 @@ interface ScriptRecipe {
     /**
      * Lifecycle stage of this recipe on disk.
      * - 'draft':    written by MainAgent's write_script during a turn; filtered out
-     *               of `ScriptStore.getAll()` so the matcher never picks it.
+     *               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.
@@ -1763,34 +1785,219 @@ interface ScriptParameter {
 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'), or 'federation' for a cross-source component. */
+    /** `executedQuery.sourceId` to bind to (e.g. a tool id or 'computed:_final'), 'federation' for a cross-source component, or 'markdown' for a content-only narrative block (no data source). */
     sourceRef: string;
     /** Present only when sourceRef === 'federation' — the DuckDB SQL to re-execute on replay. */
     federationSql?: string;
+    /** Present only when sourceRef === 'markdown' — the narrative text to render on replay (markdown has no data source, so its content must be persisted). */
+    content?: string;
     title?: string;
     description?: string;
     /** Validated axis/value keys + aggregation — all referencing real columns of the bound source. */
     config: Record<string, any>;
 }
+/**
+ * Result from executing a script via ScriptRunner.
+ */
+interface ScriptResult {
+    /** Whether the script executed successfully */
+    success: boolean;
+    /** Combined data from all queries */
+    data: any[];
+    /** Individual query results tracked during execution */
+    executedQueries: ScriptQueryResult[];
+    /** Error message if failed */
+    error?: string;
+    /**
+     * Where in the lifecycle the error occurred. Lets MainAgent's fix-loop
+     * decide between "rewrite the whole draft" (compile) and "patch the
+     * specific line" (runtime).
+     */
+    errorPhase?: 'compile' | 'runtime' | 'timeout' | 'ipc';
+    /** Total execution time in milliseconds */
+    executionTimeMs: number;
+}
+/**
+ * A single query executed during script runtime.
+ * Tracked by ScriptContext for component generation and debugging.
+ */
+interface ScriptQueryResult {
+    /** Source tool ID */
+    sourceId: string;
+    /** Human-readable source name */
+    sourceName: string;
+    /** The SQL that was executed */
+    sql: string;
+    /** Result data rows */
+    data: any[];
+    /** Number of rows returned */
+    count: number;
+    /** Total rows that matched before limit (if available) */
+    totalCount?: number;
+    /** Query execution time in milliseconds */
+    executionTimeMs: number;
+    /**
+     * True for rows that did NOT come from a real SQL execution — either a
+     * ctx.emit() dataset or the synthesized "computed:_final" entry that
+     * carries the script's post-JS returned data. The component generator
+     * uses this to route the resulting component through the script_dataset
+     * sentinel toolId so the frontend resolves it via the queryCache short-circuit.
+     */
+    virtual?: boolean;
+}
+/**
+ * Match tier returned by the LLM script matcher.
+ *
+ * - 'high': the script answers the question directly; only parameter values
+ *   may differ. The runtime replays it with extracted params (cheapest path).
+ * - 'near': the script answers a STRUCTURALLY similar question but needs
+ *   body modification (different metric, dimension, table, filter shape).
+ *   The runtime forks the parent and adapts the body via MainAgent's normal
+ *   write_script + execute_script loop — no SourceAgent dispatch needed.
+ *   See backend/docs/SCRIPT-FLOW-FORK-ADAPT.md for the full design.
+ * - 'none': no script is relevant; full agent flow runs.
+ */
+type MatchTier = 'high' | 'near' | 'none';
+/**
+ * Result from the LLM-based script matcher.
+ *
+ * For `tier: 'high'`, `extractedParams` carries the values to pass to the
+ * existing script. For `tier: 'near'`, `gaps` and `modificationHint` describe
+ * what the fork-author needs to change in the parent body.
+ */
+interface ScriptMatch {
+    /** The matched script recipe */
+    recipe: ScriptRecipe;
+    /** Match tier — see MatchTier docs */
+    tier: MatchTier;
+    /** Similarity score (0-1, derived from LLM tier) */
+    similarity: number;
+    /**
+     * Legacy confidence level. Mirrors `tier === 'high'`/`'near'` for now;
+     * kept so existing callers compile while we migrate to tier-based logic.
+     */
+    confidence: 'high' | 'medium';
+    /** Parameters extracted from the user question by the LLM (tier='high') */
+    extractedParams?: Record<string, any>;
+    /** What the user question needs that the parent doesn't cover (tier='near') */
+    gaps?: string[];
+    /** One-sentence description of the change the fork-author should make (tier='near') */
+    modificationHint?: string;
+    /** Why the matcher made this choice (for logs and telemetry) */
+    reasoning?: string;
+}
 
 /**
- * ScriptStore — Persistent Storage for Script Recipes
+ * ScriptRecipeStore — injected metadata backend for the script flow.
  *
- * Layout:
- *   scripts-store/
- *     metadata/<name>.json   ← recipe metadata (params, tables, counts, ...)
- *     <name>.ts              ← the getData() function body, editable in your IDE
+ * 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.
  *
- * Each VM deployment is a single project, so no project ID prefix needed.
- * Legacy single-file format (JSON with embedded scriptBody) is still loadable
- * for backwards compatibility and auto-migrated to the split format on next save.
+ * All metadata rows are plain JSON (no scriptBody — that lives on disk).
+ * See backend/docs/SCRIPT-FLOW-SCALING-ISSUES.md (#1, #3, #7).
  */
 
+/** One recipe's metadata as stored in Postgres (mirrors the script_recipes table). */
+interface ScriptRecipeMetaRow {
+    id: string;
+    projectId?: string | null;
+    version: number;
+    name: string;
+    intentDescription: string;
+    tags: string[] | null;
+    createdFrom: string | null;
+    sourceIds: string[] | null;
+    tables: string[] | null;
+    parameters: ScriptParameter[] | null;
+    components?: ScriptComponentSpec[] | null;
+    fileBase: string;
+    bodyHash?: string | null;
+    successCount: number;
+    failureCount: number;
+    lastUsed: string | null;
+    parentId?: string | null;
+    forkDepth?: number | null;
+    forkReason?: string | null;
+    status: 'draft' | 'verified' | string;
+    turnId?: string | null;
+    lastError?: {
+        phase: 'compile' | 'runtime' | 'timeout' | 'ipc';
+        message: string;
+        at: string;
+        attempt: number;
+    } | null;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+}
+interface ScriptRecipeStore {
+    /** FTS shortlist of healthy verified recipes for the matcher (metadata only). */
+    search(params: {
+        prompt: string;
+        projectId?: string;
+        limit?: number;
+    }): Promise<ScriptRecipeMetaRow[]>;
+    /** Fetch one recipe by id (any status). */
+    getById(id: string): Promise<ScriptRecipeMetaRow | null>;
+    /** Count healthy verified recipes (drives the "any scripts?" gate). */
+    count(params?: {
+        projectId?: string;
+    }): Promise<number>;
+    /** Insert or update a recipe row (keyed by id). */
+    upsert(row: ScriptRecipeMetaRow): Promise<void>;
+    /** Atomically bump counters / last-used. */
+    updateStats(id: string, patch: {
+        successDelta?: number;
+        failureDelta?: number;
+        lastUsed?: string;
+    }): Promise<void>;
+    /** Flip a draft to verified, applying provenance + optional fork lineage. */
+    promote(id: string, patch: {
+        sourceIds: string[];
+        tables: string[];
+        fileBase?: string;
+        parentId?: string;
+        forkDepth?: number;
+        forkReason?: string;
+        components?: ScriptComponentSpec[];
+    }): Promise<ScriptRecipeMetaRow | null>;
+    /** Stamp a draft's last execution error. */
+    recordDraftError(id: string, err: {
+        phase: string;
+        message: string;
+        attempt: number;
+        at: string;
+    }): Promise<void>;
+    /** Delete a recipe row (body file removed separately). */
+    remove(id: string): Promise<void>;
+    /** True if `fileBase` is taken by a different recipe in this project. */
+    fileBaseTaken(fileBase: string, excludeId: string, projectId?: string): Promise<boolean>;
+}
+/** Pull the injected store off the collections bag (or null if not wired). */
+declare function resolveScriptRecipeStore(collections: any): ScriptRecipeStore | null;
+
 /**
- * Input for `ScriptStore.saveDraft()`. Identifies the draft by `recipeId` so
- * retries within the same turn overwrite the same files (or omit `recipeId`
- * on the first call to mint a fresh draft).
+ * 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;
@@ -1803,142 +2010,92 @@ interface SaveDraftInput {
     scriptBody: string;
     createdFrom: string;
 }
-/**
- * Lineage + provenance fields applied when a draft is promoted to verified.
- * MainAgent gathers `sourceIds` and `tables` from the verified execution; the
- * caller (agent-user-response.ts) supplies the optional fork lineage.
- */
 interface PromoteToVerifiedInput {
     sourceIds: string[];
     tables: string[];
     parentId?: string;
     forkDepth?: number;
     forkReason?: string;
-    /** Validated component specs to persist on the recipe (component recipe). */
     components?: ScriptComponentSpec[];
 }
+interface ScriptStoreOptions {
+    /** Explicit metadata store, or resolved from `collections['script-recipes']`. */
+    store?: ScriptRecipeStore | null;
+    collections?: any;
+    /** Body directory (defaults to <cwd>/scripts-store). */
+    baseDir?: string;
+    /** Project scope stamped on every row. */
+    projectId?: string;
+}
+/**
+ * Normalize a scriptBody into the on-disk form (strip a leading comment block,
+ * ensure `export async function getData`). Exported for MainAgent.
+ */
+declare function normalizeScriptBody(scriptBody: string): string;
 declare class ScriptStore {
-    private recipes;
+    private store;
     private storeDir;
-    private loaded;
-    constructor(baseDir?: string);
-    private metadataDir;
-    /**
-     * Filename base for a recipe. Drafts include the per-turn suffix so two
-     * concurrent turns can never clobber each other's draft files; verified
-     * recipes use the bare slug.
-     */
-    private fileBaseName;
-    /**
-     * Absolute path to the .ts file for a recipe. Callers (e.g. ScriptRunner,
-     * MainAgent's execute_script) use this to hand off the path to the tsx child.
-     */
-    getScriptPath(recipe: ScriptRecipe): string;
-    /**
-     * Absolute path to the metadata JSON for a recipe.
-     */
-    private getMetadataPath;
-    /**
-     * Get all VERIFIED recipes — drafts are filtered out so the matcher never
-     * considers an unverified script. Loads from disk on first access.
-     */
-    getAll(): ScriptRecipe[];
-    /**
-     * Get a recipe by ID — returns drafts as well as verified scripts.
-     * Used by MainAgent and the promotion path.
-     */
-    get(id: string): ScriptRecipe | null;
-    /**
-     * Number of verified recipes (matches `getAll().length`).
-     */
-    count(): number;
-    /**
-     * Save a recipe (create or update).
-     * File is named after the script: "order-status-distribution.json"
-     */
-    save(recipe: ScriptRecipe): void;
-    /**
-     * Persist (or update) a draft recipe to disk. Always writes immediately so
-     * the `.ts` body is visible in the IDE the moment MainAgent calls
-     * `write_script`. Within one turn, retries that pass the same `recipeId`
-     * overwrite the same files (the LLM rewriting itself); a fresh `recipeId`
-     * is minted only on the first call of the turn.
-     *
-     * Filename includes the `turnId` suffix so concurrent turns never collide.
-     */
-    saveDraft(input: SaveDraftInput): ScriptRecipe;
-    /**
-     * Stamp the draft with the most recent execution failure so it is visible
-     * in the metadata JSON without grepping logs. No-op if the recipe doesn't
-     * exist or has already been promoted.
-     */
+    private projectId?;
+    constructor(opts?: ScriptStoreOptions);
+    /** Whether a metadata store is wired (matcher / authoring are gated on this). */
+    hasStore(): boolean;
+    /** Number of healthy verified recipes (gates the script-matching path). */
+    count(): Promise<number>;
+    /**
+     * FTS shortlist for the matcher (metadata only — bodies are loaded lazily by
+     * `get()` once the LLM picks one). Returns verified, healthy recipes ranked
+     * by relevance.
+     */
+    search(prompt: string, limit?: number): Promise<ScriptRecipe[]>;
+    /** Fetch one recipe by id with its body loaded from disk. */
+    get(id: string): Promise<ScriptRecipe | null>;
+    /** Create or update a recipe (metadata upsert + body write when changed). */
+    save(recipe: ScriptRecipe): Promise<void>;
+    /**
+     * Persist (or update) a draft. Within a turn, retries that pass the same
+     * `recipeId` overwrite the same row + file; a fresh `recipeId` mints a new
+     * draft. The body is visible at scripts-store/<fileBase>.ts immediately.
+     */
+    saveDraft(input: SaveDraftInput): Promise<ScriptRecipe>;
+    /** Stamp a draft's last execution error (metadata only). */
     recordDraftError(recipeId: string, err: {
         phase: 'compile' | 'runtime' | 'timeout' | 'ipc';
         message: string;
         attempt: number;
-    }): void;
+    }): Promise<void>;
     /**
      * Promote a successfully-executed draft into a verified script.
-     *
-     * - Renames the on-disk files from `<slug>-<turnId>.{ts,json}` to the bare
-     *   `<slug>.{ts,json}`. If a verified file with the same slug already exists
-     *   (concurrent turn won the race, or a prior session has it), the recipe
-     *   keeps its turn-suffixed filename so we never overwrite verified work —
-     *   the matcher keys on `recipe.id`, so two siblings with similar slugs is fine.
-     * - Flips `status: 'verified'`, clears `lastError`, applies provenance
-     *   (`sourceIds`, `tables`) and optional fork lineage.
-     */
-    promoteToVerified(recipeId: string, input: PromoteToVerifiedInput): ScriptRecipe | null;
-    /**
-     * Drop a draft from disk + memory (e.g. when an outer error path wants to
-     * clean up). Per the agreed policy, MainAgent's normal failure path does
-     * NOT call this — failed drafts are kept on disk for the user to inspect.
-     */
-    discardDraft(recipeId: string): void;
-    /**
-     * Delete a recipe by ID.
-     */
-    delete(id: string): void;
-    /**
-     * Record a successful execution for a recipe.
-     */
-    recordSuccess(id: string): void;
-    /**
-     * Record a failed execution for a recipe.
-     */
-    recordFailure(id: string): void;
-    /**
-     * Get the failure rate for a recipe (0 to 1).
-     * Returns 0 if the recipe has fewer than 5 total uses.
-     */
-    getFailureRate(id: string): number;
-    private ensureLoaded;
-    /**
-     * Convert a script name to a safe filename.
-     * "Order Status Distribution" → "order-status-distribution"
-     */
-    private toFileName;
-    /**
-     * Load all script files from disk.
-     *
-     * Supports two layouts:
-     *   - New (preferred): metadata/<name>.json + <name>.ts
-     *   - Legacy: <name>.json with embedded scriptBody (auto-migrated on next save)
-     */
-    private loadAllFromDisk;
-    /**
-     * Save a recipe to disk in split format:
-     *   metadata/<name>.json  (metadata, no scriptBody)
-     *   <name>.ts             (just the function body)
-     *
-     * If a legacy top-level <name>.json exists for the same recipe, remove it
-     * so we don't end up with duplicate sources of truth.
-     */
-    private saveRecipeToDisk;
-    /**
-     * Delete a recipe's files from disk (both metadata + body, plus any legacy file).
-     */
-    private deleteRecipeFromDisk;
+     * The on-disk body already exists at <fileBase>.ts (written at write_script
+     * time) and keeps its name — only the DB row flips status + provenance.
+     */
+    promoteToVerified(recipeId: string, input: PromoteToVerifiedInput): Promise<ScriptRecipe | null>;
+    /**
+     * Drop a draft (row + body file). MainAgent calls this at end-of-turn when a
+     * draft was authored but never verified — failed drafts are never matched, so
+     * deleting them immediately avoids unbounded accumulation (#5). No-op if the
+     * recipe isn't a draft (so a promoted/verified script is never removed here).
+     */
+    discardDraft(recipeId: string): Promise<void>;
+    /** Delete a recipe (row + body file). */
+    delete(id: string): Promise<void>;
+    /** Record a successful execution (atomic counter bump). */
+    recordSuccess(id: string): Promise<void>;
+    /** Record a failed execution (atomic counter bump). */
+    recordFailure(id: string): Promise<void>;
+    /** Absolute path to the .ts body for a recipe (used by the runner/MainAgent). */
+    getScriptPath(recipe: ScriptRecipe): string;
+    private removeById;
+    private rowToRecipe;
+    private recipeToRow;
+    /** slug of name, with a short id suffix when the bare slug is already taken. */
+    private computeFileBase;
+    private toSlug;
+    private hash;
+    private bodyPath;
+    private readBody;
+    /** Atomic body write (temp + rename) so concurrent reads never see a partial file. */
+    private writeBody;
+    private unlinkBody;
 }
 
 /**
@@ -1972,7 +2129,16 @@ declare class MainAgent {
     private turnId;
     private createdFromPrompt;
     private scriptState;
-    constructor(externalTools: ExternalTool[], config: AgentConfig, scriptStore?: ScriptStore, turnId?: string, streamBuffer?: StreamBuffer, workflows?: WorkflowDescriptor[]);
+    /**
+     * 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;
+    constructor(externalTools: ExternalTool[], config: AgentConfig, scriptStore?: ScriptStore, turnId?: string, streamBuffer?: StreamBuffer, workflows?: WorkflowDescriptor[], forkMode?: boolean);
     private get scriptingEnabled();
     /**
      * Handle a user question using the multi-agent system.
@@ -2069,7 +2235,22 @@ interface LLMOptions {
     temperature?: number;
     topP?: number;
     apiKey?: string;
+    baseURL?: string;
     partial?: (chunk: string) => void;
+    /**
+     * 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. Anthropic only.
+     */
+    firstIterationToolChoice?: {
+        type: 'any';
+    } | {
+        type: 'tool';
+        name: string;
+    };
 }
 interface Tool {
     name: string;
@@ -2117,6 +2298,15 @@ 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;
+    private static _openrouterOptions;
+    private static _openrouterText;
+    private static _openrouterStream;
+    private static _openrouterStreamWithTools;
     private static _anthropicText;
     private static _anthropicStream;
     private static _anthropicStreamWithTools;
@@ -3262,6 +3452,65 @@ declare class DashboardConversationHistory {
 }
 declare const dashboardConversationHistory: DashboardConversationHistory;
 
+/**
+ * ScriptMatcher — LLM-Based Script Matching + Parameter Extraction
+ *
+ * Uses ONE LLM call to:
+ * 1. Pick the best matching script from the library (or "none")
+ * 2. Extract parameter values from the user question
+ *
+ * Why LLM over embeddings:
+ * - Embeddings capture topic similarity ("overstock" ≈ "inventory" ≈ "revenue")
+ *   but can't distinguish structurally different questions about the same domain
+ * - LLM understands that "overstock by warehouse" needs a different script than
+ *   "revenue by warehouse" even though they're semantically close
+ * - One call does both matching AND parameter extraction
+ *
+ * When script library grows past ~50, add an embedding pre-filter
+ * (ChromaDB narrows to top 10 → LLM picks from those 10).
+ */
+
+declare class ScriptMatcher {
+    private store;
+    constructor(store: ScriptStore);
+    /**
+     * Find the best matching script for a user question.
+     * Uses ONE LLM call that picks the script AND extracts parameters.
+     * Returns null if no script matches.
+     */
+    match(userPrompt: string, apiKey?: string, model?: string): Promise<ScriptMatch | null>;
+    /**
+     * Build the script catalog string for the LLM prompt.
+     * Each script gets: index, ID, name, description, and parameter definitions.
+     */
+    private buildScriptCatalog;
+}
+
+/**
+ * ScriptRunner — Execute scripts in an isolated tsx subprocess.
+ *
+ * The subprocess approach replaces the earlier `new Function()` eval and gives us:
+ *   - Real sandbox (separate process, SIGKILL on timeout).
+ *   - Real TypeScript (tsx transpiles on the fly).
+ *   - npm imports available to scripts (clustering, stats, geo, etc.).
+ *
+ * Protocol: NDJSON over the child's stdin/stdout. See script-ipc.ts + backend/docs/SCRIPT-FLOW-IMPLEMENTATION.md.
+ */
+
+interface RunScriptOptions {
+    /** Data sources the script is allowed to query via ctx.query */
+    externalTools: ExternalTool[];
+    /** Optional — for propagating per-query UI progress to the user */
+    streamBuffer?: StreamBuffer;
+    /** Override the wall-clock timeout (default `SCRIPT_TIMEOUT_MS`, 60s). */
+    timeoutMs?: number;
+}
+/**
+ * Execute a recipe by spawning a tsx child on the script's .ts file.
+ * `scriptPath` is the absolute path to the saved `.ts` body.
+ */
+declare function runScript(recipe: ScriptRecipe, scriptPath: string, params: Record<string, any>, options: RunScriptOptions): Promise<ScriptResult>;
+
 type MessageTypeHandler = (message: IncomingMessage) => void | Promise<void>;
 declare class SuperatomSDK {
     private ws;
@@ -3431,4 +3680,4 @@ declare class SuperatomSDK {
     getConversationSimilarityThreshold(): number;
 }
 
-export { type Action, type AgentConfig, type AgentResponse, BM25L, type BM25LOptions, type BaseLLMConfig, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CollectionHandler, type CollectionOperation, type DBUIBlock, DEFAULT_AGENT_CONFIG, type DatabaseType, type HybridSearchOptions, type IncomingMessage, type KbNodesQueryFilters, type KbNodesRequestPayload, LLM, type LLMUsageEntry, type LogLevel, MainAgent, type Message, type ModelStrategy, type OutputField, type RerankedResult, STORAGE_CONFIG, type SelectedWorkflow, SuperatomSDK, type SuperatomSDKConfig, type TaskType, Thread, ThreadManager, type Tool$1 as Tool, type ToolOutputSchema, UIBlock, UILogCollector, type User, UserManager, type UsersData, type WorkflowDescriptor, anthropicLLM, dashboardConversationHistory, geminiLLM, groqLLM, hybridRerank, llmUsageLogger, logger, openaiLLM, queryCache, rerankChromaResults, rerankConversationResults, userPromptErrorLogger };
+export { type Action, type AgentConfig, type AgentResponse, BM25L, type BM25LOptions, type BaseLLMConfig, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CollectionHandler, type CollectionOperation, type DBUIBlock, DEFAULT_AGENT_CONFIG, type DatabaseType, type HybridSearchOptions, type IncomingMessage, type KbNodesQueryFilters, type KbNodesRequestPayload, LLM, type LLMUsageEntry, type LogLevel, MainAgent, type Message, type ModelStrategy, type OutputField, type RerankedResult, STORAGE_CONFIG, type ScriptComponentSpec, ScriptMatcher, type ScriptParameter, type ScriptRecipe, type ScriptRecipeMetaRow, type ScriptRecipeStore, type ScriptResult, ScriptStore, type ScriptStoreOptions, type SelectedWorkflow, SuperatomSDK, type SuperatomSDKConfig, type TaskType, Thread, ThreadManager, type Tool$1 as Tool, type ToolOutputSchema, UIBlock, UILogCollector, type User, UserManager, type UsersData, type WorkflowDescriptor, anthropicLLM, dashboardConversationHistory, geminiLLM, groqLLM, hybridRerank, llmUsageLogger, logger, normalizeScriptBody, openaiLLM, queryCache, rerankChromaResults, rerankConversationResults, resolveScriptRecipeStore, runScript, userPromptErrorLogger };