@superatomai/sdk-node 0.0.8-s → 0.0.9-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 */
@@ -1773,10 +1785,12 @@ 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. */
@@ -2115,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.
@@ -2212,7 +2235,37 @@ 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. 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;
@@ -2260,11 +2313,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;
     /**
@@ -2273,8 +2359,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

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 */
@@ -1773,10 +1785,12 @@ 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. */
@@ -2115,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.
@@ -2212,7 +2235,37 @@ 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. 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;
@@ -2260,11 +2313,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;
     /**
@@ -2273,8 +2359,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