@superatomai/sdk-node 0.0.55-dsp → 0.0.56-dsp

package/dist/index.d.mts

@@ -395,6 +395,23 @@ interface ScriptMatch {
  * 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
@@ -498,6 +515,19 @@ interface ExecutedToolInfo {
         /** Up to MAIN_AGENT_COMPLETE_ROWS rows — the complete result when small. */
         _mainAgentRows?: any[];
     };
+    /**
+     * 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;
@@ -2702,6 +2732,29 @@ interface ScriptStoreOptions {
     /** 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;
@@ -5316,6 +5369,12 @@ interface RunScriptOptions {
      * 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[];
 }
 /**
  * Execute a recipe by spawning a tsx child on the script's .ts file.
@@ -5526,4 +5585,4 @@ declare class SuperatomSDK {
     getConversationSimilarityThreshold(): number;
 }
 
-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, type ModelStrategy, type OutputContract, type OutputField, type OutputValidator, type RerankedResult, type RunAgentOptions, 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, type TriggerEvent, type TriggerFireInfo, UIBlock, UILogCollector, type User, UserManager, type UsersData, type WorkflowDescriptor, type Workspace, anthropicLLM, assertReadOnlySql, createCodexSession, createCodingAgentSession, dashboardConversationHistory, describeTriggers, emitAgentEvent, geminiLLM, getCodingAgent, getCodingAgentsConfig, groqLLM, hybridRerank, listCodingAgents, llmUsageLogger, logger, normalizeScriptBody, onAgentRun, openaiLLM, queryCache, registerCodingAgentCollection, registerCodingAgents, registerDashboardAgentCollection, rerankChromaResults, rerankConversationResults, resolveScriptRecipeStore, runCodingAgent, runScript, startAgentTriggers, stopAgentTriggers, userPromptErrorLogger, writeBridgeShims };
+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, type ModelStrategy, type OutputContract, type OutputField, type OutputValidator, type RerankedResult, type RunAgentOptions, 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, type TriggerEvent, type TriggerFireInfo, UIBlock, UILogCollector, type User, UserManager, type UsersData, type WorkflowDescriptor, type Workspace, anthropicLLM, assertReadOnlySql, createCodexSession, createCodingAgentSession, dashboardConversationHistory, dataFingerprint, describeTriggers, emitAgentEvent, extractNamedExport, geminiLLM, getCodingAgent, getCodingAgentsConfig, groqLLM, hybridRerank, listCodingAgents, llmUsageLogger, logger, normalizeScriptBody, onAgentRun, openaiLLM, queryCache, registerCodingAgentCollection, registerCodingAgents, registerDashboardAgentCollection, rerankChromaResults, rerankConversationResults, resolveScriptRecipeStore, runCodingAgent, runScript, startAgentTriggers, stopAgentTriggers, userPromptErrorLogger, writeBridgeShims };

package/dist/index.d.ts

@@ -395,6 +395,23 @@ interface ScriptMatch {
  * 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
@@ -498,6 +515,19 @@ interface ExecutedToolInfo {
         /** Up to MAIN_AGENT_COMPLETE_ROWS rows — the complete result when small. */
         _mainAgentRows?: any[];
     };
+    /**
+     * 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;
@@ -2702,6 +2732,29 @@ interface ScriptStoreOptions {
     /** 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;
@@ -5316,6 +5369,12 @@ interface RunScriptOptions {
      * 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[];
 }
 /**
  * Execute a recipe by spawning a tsx child on the script's .ts file.
@@ -5526,4 +5585,4 @@ declare class SuperatomSDK {
     getConversationSimilarityThreshold(): number;
 }
 
-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, type ModelStrategy, type OutputContract, type OutputField, type OutputValidator, type RerankedResult, type RunAgentOptions, 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, type TriggerEvent, type TriggerFireInfo, UIBlock, UILogCollector, type User, UserManager, type UsersData, type WorkflowDescriptor, type Workspace, anthropicLLM, assertReadOnlySql, createCodexSession, createCodingAgentSession, dashboardConversationHistory, describeTriggers, emitAgentEvent, geminiLLM, getCodingAgent, getCodingAgentsConfig, groqLLM, hybridRerank, listCodingAgents, llmUsageLogger, logger, normalizeScriptBody, onAgentRun, openaiLLM, queryCache, registerCodingAgentCollection, registerCodingAgents, registerDashboardAgentCollection, rerankChromaResults, rerankConversationResults, resolveScriptRecipeStore, runCodingAgent, runScript, startAgentTriggers, stopAgentTriggers, userPromptErrorLogger, writeBridgeShims };
+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, type ModelStrategy, type OutputContract, type OutputField, type OutputValidator, type RerankedResult, type RunAgentOptions, 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, type TriggerEvent, type TriggerFireInfo, UIBlock, UILogCollector, type User, UserManager, type UsersData, type WorkflowDescriptor, type Workspace, anthropicLLM, assertReadOnlySql, createCodexSession, createCodingAgentSession, dashboardConversationHistory, dataFingerprint, describeTriggers, emitAgentEvent, extractNamedExport, geminiLLM, getCodingAgent, getCodingAgentsConfig, groqLLM, hybridRerank, listCodingAgents, llmUsageLogger, logger, normalizeScriptBody, onAgentRun, openaiLLM, queryCache, registerCodingAgentCollection, registerCodingAgents, registerDashboardAgentCollection, rerankChromaResults, rerankConversationResults, resolveScriptRecipeStore, runCodingAgent, runScript, startAgentTriggers, stopAgentTriggers, userPromptErrorLogger, writeBridgeShims };