@superatomai/sdk-node 0.0.14-s → 0.0.15-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 */
@@ -2117,7 +2129,22 @@ 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;
+    /**
+     * 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);
     private get scriptingEnabled();
     /**
      * Handle a user question using the multi-agent system.
@@ -2129,7 +2156,7 @@ declare class MainAgent {
      * 4. Direct tools → fn() called directly with LLM params → returns data
      * 5. Generates final analysis text
      */
-    handleQuestion(userPrompt: string, apiKey?: string, conversationHistory?: string, streamCallback?: (chunk: string) => void): Promise<AgentResponse>;
+    handleQuestion(userPrompt: string, apiKey?: string, conversationHistory?: string, streamCallback?: (chunk: string) => void, signal?: AbortSignal): Promise<AgentResponse>;
     private handleWriteScript;
     private handleExecuteScript;
     /**
@@ -2214,7 +2241,45 @@ interface LLMOptions {
     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;
@@ -2262,11 +2327,44 @@ 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 _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;
     /**
@@ -2275,8 +2373,28 @@ declare class LLM {
      */
     private static _cleanSchemaForGemini;
     private static _geminiStreamWithTools;
+    /** True for Anthropic/Claude model ids — gates OpenRouter prompt caching. */
+    private static _isClaudeModel;
+    /**
+     * Build the OpenAI-wire system message. For OpenRouter + Claude
+     * (cacheClaude=true) it emits content parts carrying Anthropic
+     * `cache_control` breakpoints (preserving any the caller set, else marking
+     * the last block), so OpenRouter forwards them to Anthropic for prompt
+     * caching. Otherwise it returns a plain flattened string — unchanged for
+     * direct OpenAI/Groq.
+     */
+    private static _openaiSystemMessage;
+    /**
+     * Split an OpenAI-wire usage object. `prompt_tokens` INCLUDES cached tokens,
+     * so we subtract them out (Anthropic-style: input excludes cache reads) and
+     * report cached separately — this makes calculateCost price cache reads at
+     * the discounted rate and reflects OpenRouter prompt-cache savings in logs.
+     */
+    private static _openaiUsage;
     private static _openaiText;
     private static _openaiStream;
+    /** Map the Anthropic-style firstIterationToolChoice to OpenAI's tool_choice. */
+    private static _openaiToolChoice;
     private static _openaiStreamWithTools;
     /**
      * Parse JSON string, handling markdown code blocks and surrounding text
@@ -3201,7 +3319,7 @@ declare abstract class BaseLLM {
      * This helps provide intelligent suggestions for follow-up queries
      * For general/conversational questions without components, pass textResponse instead
      */
-    generateNextQuestions(originalUserPrompt: string, component?: Component | null, componentData?: Record<string, unknown>, apiKey?: string, conversationHistory?: string, textResponse?: string): Promise<string[]>;
+    generateNextQuestions(originalUserPrompt: string, component?: Component | null, componentData?: Record<string, unknown>, apiKey?: string, conversationHistory?: string, textResponse?: string, signal?: AbortSignal): Promise<string[]>;
 }
 
 interface AnthropicLLMConfig extends BaseLLMConfig {
@@ -3433,7 +3551,7 @@ declare class ScriptMatcher {
      * 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>;
+    match(userPrompt: string, apiKey?: string, model?: string, signal?: AbortSignal): Promise<ScriptMatch | null>;
     /**
      * Build the script catalog string for the LLM prompt.
      * Each script gets: index, ID, name, description, and parameter definitions.
@@ -3459,6 +3577,12 @@ interface RunScriptOptions {
     streamBuffer?: StreamBuffer;
     /** Override the wall-clock timeout (default `SCRIPT_TIMEOUT_MS`, 60s). */
     timeoutMs?: number;
+    /**
+     * Per-turn cancellation signal. When the user hits "Stop" mid-run, the child
+     * process group is SIGKILLed and the run resolves as an aborted failure (the
+     * caller is already unwinding, so the result is discarded).
+     */
+    signal?: AbortSignal;
 }
 /**
  * Execute a recipe by spawning a tsx child on the script's .ts file.

package/dist/index.d.ts

@@ -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 */
@@ -2117,7 +2129,22 @@ 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;
+    /**
+     * 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);
     private get scriptingEnabled();
     /**
      * Handle a user question using the multi-agent system.
@@ -2129,7 +2156,7 @@ declare class MainAgent {
      * 4. Direct tools → fn() called directly with LLM params → returns data
      * 5. Generates final analysis text
      */
-    handleQuestion(userPrompt: string, apiKey?: string, conversationHistory?: string, streamCallback?: (chunk: string) => void): Promise<AgentResponse>;
+    handleQuestion(userPrompt: string, apiKey?: string, conversationHistory?: string, streamCallback?: (chunk: string) => void, signal?: AbortSignal): Promise<AgentResponse>;
     private handleWriteScript;
     private handleExecuteScript;
     /**
@@ -2214,7 +2241,45 @@ interface LLMOptions {
     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;
@@ -2262,11 +2327,44 @@ 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 _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;
     /**
@@ -2275,8 +2373,28 @@ declare class LLM {
      */
     private static _cleanSchemaForGemini;
     private static _geminiStreamWithTools;
+    /** True for Anthropic/Claude model ids — gates OpenRouter prompt caching. */
+    private static _isClaudeModel;
+    /**
+     * Build the OpenAI-wire system message. For OpenRouter + Claude
+     * (cacheClaude=true) it emits content parts carrying Anthropic
+     * `cache_control` breakpoints (preserving any the caller set, else marking
+     * the last block), so OpenRouter forwards them to Anthropic for prompt
+     * caching. Otherwise it returns a plain flattened string — unchanged for
+     * direct OpenAI/Groq.
+     */
+    private static _openaiSystemMessage;
+    /**
+     * Split an OpenAI-wire usage object. `prompt_tokens` INCLUDES cached tokens,
+     * so we subtract them out (Anthropic-style: input excludes cache reads) and
+     * report cached separately — this makes calculateCost price cache reads at
+     * the discounted rate and reflects OpenRouter prompt-cache savings in logs.
+     */
+    private static _openaiUsage;
     private static _openaiText;
     private static _openaiStream;
+    /** Map the Anthropic-style firstIterationToolChoice to OpenAI's tool_choice. */
+    private static _openaiToolChoice;
     private static _openaiStreamWithTools;
     /**
      * Parse JSON string, handling markdown code blocks and surrounding text
@@ -3201,7 +3319,7 @@ declare abstract class BaseLLM {
      * This helps provide intelligent suggestions for follow-up queries
      * For general/conversational questions without components, pass textResponse instead
      */
-    generateNextQuestions(originalUserPrompt: string, component?: Component | null, componentData?: Record<string, unknown>, apiKey?: string, conversationHistory?: string, textResponse?: string): Promise<string[]>;
+    generateNextQuestions(originalUserPrompt: string, component?: Component | null, componentData?: Record<string, unknown>, apiKey?: string, conversationHistory?: string, textResponse?: string, signal?: AbortSignal): Promise<string[]>;
 }
 
 interface AnthropicLLMConfig extends BaseLLMConfig {
@@ -3433,7 +3551,7 @@ declare class ScriptMatcher {
      * 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>;
+    match(userPrompt: string, apiKey?: string, model?: string, signal?: AbortSignal): Promise<ScriptMatch | null>;
     /**
      * Build the script catalog string for the LLM prompt.
      * Each script gets: index, ID, name, description, and parameter definitions.
@@ -3459,6 +3577,12 @@ interface RunScriptOptions {
     streamBuffer?: StreamBuffer;
     /** Override the wall-clock timeout (default `SCRIPT_TIMEOUT_MS`, 60s). */
     timeoutMs?: number;
+    /**
+     * Per-turn cancellation signal. When the user hits "Stop" mid-run, the child
+     * process group is SIGKILLed and the run resolves as an aborted failure (the
+     * caller is already unwinding, so the result is discarded).
+     */
+    signal?: AbortSignal;
 }
 /**
  * Execute a recipe by spawning a tsx child on the script's .ts file.