@superatomai/sdk-node 0.0.58-dsp → 0.0.59-dsp

package/dist/index.d.mts

@@ -2095,6 +2095,34 @@ interface DashCompModelConfig {
      */
     fastModel?: string;
 }
+/**
+ * Everything a replacement answer flow is handed for one question. Deliberately
+ * the same material the built-in flow gets, so a provider is a drop-in and not a
+ * second-class path.
+ */
+interface AnswerProviderContext {
+    prompt: string;
+    /** The live frontend component catalog. */
+    components: Component[];
+    collections?: any;
+    externalTools?: any[];
+    userId?: string;
+    threadId?: string;
+    /** Per-user authorization config (users.config) — row policies come from here. */
+    userConfig?: any;
+    conversationHistory?: string;
+    /** Stream user-facing prose. Do NOT stream tool/command output through this. */
+    onStream?: (chunk: string) => void;
+    signal?: AbortSignal;
+}
+/**
+ * An alternative to the built-in MainAgent/SourceAgent flow.
+ *
+ * Returns the same T_RESPONSE the built-in flow does, so everything downstream —
+ * the UIBlock, streaming, abort, the conversation save, component rendering — is
+ * unchanged and the two flows stay comparable.
+ */
+type AnswerProvider = (ctx: AnswerProviderContext) => Promise<T_RESPONSE>;
 interface SuperatomSDKConfig {
     url?: string;
     apiKey?: string;
@@ -2132,6 +2160,16 @@ interface SuperatomSDKConfig {
      * If not set, uses the provider's default model.
      */
     sourceAgentModel?: string;
+    /**
+     * Which flow answers a user question.
+     *   'agents' — the built-in MainAgent + SourceAgent flow (default).
+     *   'custom' — call `answerProvider` instead.
+     * Set 'custom' WITHOUT a provider and the SDK warns and uses 'agents', rather
+     * than failing every question.
+     */
+    answerFlow?: 'agents' | 'custom';
+    /** Required when answerFlow is 'custom'. See AnswerProvider. */
+    answerProvider?: AnswerProvider;
     /**
      * Separate model configuration for DASH_COMP flow (dashboard component picking)
      * If not provided, falls back to provider-based model selection
@@ -3258,6 +3296,26 @@ declare class MainAgent {
     getSourceSummaries(): SourceSummary[];
 }
 
+interface FmtConfig {
+    /** BCP-47 tag driving grouping and the scale vocabulary, e.g. 'en-IN', 'en-US'. */
+    locale: string;
+    /** ISO-4217 code for money, e.g. 'INR', 'USD'. */
+    currency: string;
+}
+declare const DEFAULT_FMT_CONFIG: FmtConfig;
+interface Fmt {
+    money(v: unknown, decimals?: number): string;
+    num(v: unknown, decimals?: number): string;
+    count(v: unknown, decimals?: number): string;
+    pct(part: unknown, whole: unknown, decimals?: number): string;
+    delta(current: unknown, previous: unknown, decimals?: number): string;
+    date(v: unknown): string;
+    range(from: unknown, to: unknown): string;
+    list(items: unknown[], conjunction?: string): string;
+}
+/** Build a `fmt` bound to one locale/currency. */
+declare function makeFmt(cfg?: Partial<FmtConfig>): Fmt;
+
 type SystemPrompt = string | Anthropic.Messages.TextBlockParam[];
 interface LLMMessages {
     sys: SystemPrompt;
@@ -5237,6 +5295,12 @@ interface AgentRunContext {
     /** Live progress. Populated for chat mode; a task run may also stream to a log. */
     onOutput?: (chunk: string) => void;
     onEvent?: (event: AgentEvent) => void;
+    /**
+     * Assistant prose only — safe to show a non-technical user as progress.
+     * Distinct from onOutput, which also carries command and tool lines and so
+     * would leak SQL and shell text into a user-facing stream.
+     */
+    onNarration?: (text: string) => void;
     onUsage?: (usage: AgentUsage) => void;
 }
 /**
@@ -5532,6 +5596,19 @@ declare function writeBridgeShims(ws: Workspace, opts: {
         description?: string;
     }>;
     maxRows?: number;
+    /**
+     * Identity for the queries this agent runs, from mintContextToken().
+     *
+     * The agent is a separate OS process calling the bridge over loopback
+     * HTTP, so nothing ambient crosses that gap — the same break the script
+     * flow has (see utils/context-token.ts). Without this the bridge sees an
+     * anonymous query, and under SA_SQL_REWRITE_MODE=enforce the data seam
+     * refuses it outright rather than guessing whose data it is.
+     *
+     * Omit ONLY when the caller genuinely has no identity to grant; the
+     * queries are then anonymous, which is the truth rather than a default.
+     */
+    contextToken?: string;
 }): void;
 
 /**
@@ -5679,6 +5756,117 @@ interface RunScriptOptions {
  */
 declare function runScript(recipe: ScriptRecipe, scriptPath: string, params: Record<string, any>, options: RunScriptOptions): Promise<ScriptResult>;
 
+/**
+ * Answer-flow component catalog (§2.6 a/e).
+ *
+ * The frontend sends ONE catalog to the SDK; five consumers read it and four of
+ * them narrow it for their own purpose (dashComp strips the container,
+ * create-filter selects Filter*, suggestions selects isDisplayComp). The answer
+ * flow was the only one that didn't. These helpers are its narrowing.
+ *
+ * Nothing here mutates the stored `Metadata` — dashboard and report generation
+ * legitimately need the SQL-authoring contract that the answer flow must not see,
+ * so the answer flow gets a PROJECTION instead.
+ *
+ * See backend/docs/COMPONENT-GENERATION-V2.md §2.6.
+ */
+
+/**
+ * The only components that can answer a data question. Everything else in the
+ * catalog belongs to dashboards (filters, forms), is a whole page (Home,
+ * DatabaseOverview), is a UI primitive, or is the wrapper this flow builds.
+ *
+ * DynamicWaterfallChart is deliberately excluded — see §2.6(e). Adding it back
+ * is a one-line change here.
+ */
+declare const ANSWER_COMPONENT_NAMES: readonly string[];
+/**
+ * Narrow the registered catalog to the components that can answer a question.
+ * Safe for every answer-flow generator — none of them should ever nominate a
+ * filter widget, a text input, or the MultiComponentContainer the flow itself
+ * builds around their output.
+ */
+declare function answerComponents(components: Component[] | undefined): Component[];
+/**
+ * Rewrite the catalog for a flow that binds pre-executed datasets rather than
+ * authoring SQL. Apply ONLY where the flow discards component-authored SQL —
+ * `generateScriptComponents` and the `write_components` tool.
+ *
+ * Do NOT apply to `generateAgentComponents`: that path really does write SQL
+ * into externalTool.parameters.sql and validates it by executing it.
+ */
+declare function projectForDatasetBinding(components: Component[]): Component[];
+/** Filter + project in one call — the catalog the tool and script generator see. */
+declare function answerCatalogForBinding(components: Component[] | undefined): Component[];
+
+/**
+ * Component Spec Validator — V1–V8
+ *
+ * Deterministic checks of a component spec against the REAL columns of the
+ * dataset it binds. Pure: no LLM, no mutation, no I/O. Shared by the fallback
+ * generator (report-only today) and the `write_components` tool, which hands the
+ * findings back to the agent so it can fix getComponents and retry.
+ *
+ * See backend/docs/COMPONENT-GENERATION-V2.md §2.3.
+ */
+type ColType = 'NUMBER' | 'TEXT' | 'DATE' | 'BOOLEAN';
+interface ColInfo {
+    name: string;
+    type: ColType;
+    /** Every sampled non-null value is identical — a per-row invariant (e.g. a
+     * total the script computed the same on every row). Must not be summed. */
+    invariant: boolean;
+}
+/** Infer column name + type + invariance from a sample of rows. */
+declare function inferColumns(rows: any[]): Map<string, ColInfo>;
+/** Keys that must resolve to a NUMBER column. */
+declare const NUMERIC_KEYS: readonly ["yAxisKey", "valueKey", "aggregationField", "sizeKey", "latitudeField", "longitudeField", "orderField"];
+/** Keys that must resolve to a TEXT or DATE column. */
+declare const CATEGORY_KEYS: readonly ["xAxisKey", "nameKey", "seriesKey", "groupBy", "categoryKey", "dimensionKey", "labelField", "stageField"];
+/**
+ * Every config key that names a column. Superset of the generator's original
+ * list — it omitted dimensionKey (Radar), sizeKey (Scatter) and the five
+ * MapView geo fields, so those passed through unvalidated. §2.6(d).
+ */
+declare const ALL_COLUMN_KEYS: string[];
+type FindingCode = 'V1' | 'V2' | 'V3' | 'V4' | 'V5' | 'V6' | 'V7' | 'V8';
+interface ValidationFinding {
+    code: FindingCode;
+    /** `error` blocks the spec; `warn` is advisory (logged, never rejects). */
+    severity: 'error' | 'warn';
+    componentType: string;
+    /** Message written FOR THE AGENT — states the problem and the fix. */
+    message: string;
+}
+interface SpecToValidate {
+    componentType: string;
+    sourceRef?: string;
+    title?: string;
+    description?: string;
+    content?: string;
+    config?: Record<string, any>;
+}
+interface ValidationContext {
+    /** Columns of the bound dataset. */
+    cols: Map<string, ColInfo>;
+    /** UNCAPPED row count of the bound dataset — the cap is applied later, so
+     *  validating on the capped count would hide exactly the truncation we check. */
+    rowCount: number;
+    /** Rows for the mark-identity check (V4). Pass every row: a sample that happens
+     *  to hold no duplicate would report a collapsing chart as sound. */
+    rows: any[];
+    /** Valid `sourceRef` values for this run. */
+    availableSourceRefs: string[];
+    renderCap?: number;
+}
+/**
+ * Validate one component spec. Returns every finding; the caller decides
+ * whether to reject (tool path) or log (fallback path).
+ */
+declare function validateComponentSpec(spec: SpecToValidate, ctx: ValidationContext): ValidationFinding[];
+/** Render findings as the text tool-result the agent reads on a rejection. */
+declare function formatFindingsForAgent(findings: ValidationFinding[]): string;
+
 type MessageTypeHandler = (message: IncomingMessage) => void | Promise<void>;
 declare class SuperatomSDK {
     private ws;
@@ -5705,6 +5893,8 @@ declare class SuperatomSDK {
     private modelStrategy;
     private mainAgentModel;
     private sourceAgentModel;
+    private answerFlow;
+    private answerProvider?;
     private dashCompModels?;
     private conversationSimilarityThreshold;
     private userManager;
@@ -5882,4 +6072,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, 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 };
+export { ALL_COLUMN_KEYS, ANSWER_COMPONENT_NAMES, type AgentConfig, type AgentEvent, type AgentResponse, type AgentRunContext, type AgentRunHandlers, type AgentRunRecord, type AgentRunResult, type AgentTrigger, type AgentUsage, type AnswerProvider, type AnswerProviderContext, type ApplySummary, BM25L, type BM25LOptions, type BaseLLMConfig, type BuildTriggerInput, CATEGORY_KEYS, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CodexSessionOptions, type CodingAgentCollectionConfig, type CodingAgentDefinition, type CodingAgentSession, type CodingAgentSessionOptions, type CodingAgentsConfig, type ColInfo, type ColType, type CollectionHandler, type CollectionOperation, type Component, type DBUIBlock, DEFAULT_AGENT_CONFIG, DEFAULT_FMT_CONFIG, type DashboardAgentCollectionConfig, type DatabaseType, type FindingCode, type Fmt, type FmtConfig, type Harness, type HybridSearchOptions, type IncomingMessage, type KbNodesQueryFilters, type KbNodesRequestPayload, LLM, type LLMUsageEntry, type LogLevel, MainAgent, type McpServerSpec, type Message, MissingRequestContextError, type ModelStrategy, NUMERIC_KEYS, 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, type SpecToValidate, SuperatomSDK, type SuperatomSDKConfig, type T_RESPONSE, type TaskType, Thread, ThreadManager, type Tool$1 as Tool, type ToolOutputSchema, type TriggerEvent, type TriggerFireInfo, UIBlock, UILogCollector, type User, UserManager, type UsersData, type ValidationContext, type ValidationFinding, type WorkflowDescriptor, type Workspace, answerCatalogForBinding, answerComponents, anthropicLLM, assertReadOnlySql, bindContext, captureContext, clearContextTokens, contextTokenCount, createCodexSession, createCodingAgentSession, dashboardConversationHistory, dataFingerprint, describeContext, describeTriggers, emitAgentEvent, extractNamedExport, formatFindingsForAgent, geminiLLM, getCodingAgent, getCodingAgentsConfig, getRequestContext, groqLLM, hybridRerank, inferColumns, isUserContext, listCodingAgents, llmUsageLogger, logger, makeFmt, mintContextToken, normalizeScriptBody, onAgentRun, openaiLLM, policiesFromConfig, projectForDatasetBinding, queryCache, registerCodingAgentCollection, registerCodingAgents, registerDashboardAgentCollection, requireRequestContext, rerankChromaResults, rerankConversationResults, resolveContextToken, resolveScriptRecipeStore, revokeContextToken, runAsSystem, runAsUser, runCodingAgent, runScript, runWithContext, runWithMessageIdentity, startAgentTriggers, stopAgentTriggers, userPromptErrorLogger, validateComponentSpec, withCapturedContext, writeBridgeShims };

package/dist/index.d.ts

@@ -2095,6 +2095,34 @@ interface DashCompModelConfig {
      */
     fastModel?: string;
 }
+/**
+ * Everything a replacement answer flow is handed for one question. Deliberately
+ * the same material the built-in flow gets, so a provider is a drop-in and not a
+ * second-class path.
+ */
+interface AnswerProviderContext {
+    prompt: string;
+    /** The live frontend component catalog. */
+    components: Component[];
+    collections?: any;
+    externalTools?: any[];
+    userId?: string;
+    threadId?: string;
+    /** Per-user authorization config (users.config) — row policies come from here. */
+    userConfig?: any;
+    conversationHistory?: string;
+    /** Stream user-facing prose. Do NOT stream tool/command output through this. */
+    onStream?: (chunk: string) => void;
+    signal?: AbortSignal;
+}
+/**
+ * An alternative to the built-in MainAgent/SourceAgent flow.
+ *
+ * Returns the same T_RESPONSE the built-in flow does, so everything downstream —
+ * the UIBlock, streaming, abort, the conversation save, component rendering — is
+ * unchanged and the two flows stay comparable.
+ */
+type AnswerProvider = (ctx: AnswerProviderContext) => Promise<T_RESPONSE>;
 interface SuperatomSDKConfig {
     url?: string;
     apiKey?: string;
@@ -2132,6 +2160,16 @@ interface SuperatomSDKConfig {
      * If not set, uses the provider's default model.
      */
     sourceAgentModel?: string;
+    /**
+     * Which flow answers a user question.
+     *   'agents' — the built-in MainAgent + SourceAgent flow (default).
+     *   'custom' — call `answerProvider` instead.
+     * Set 'custom' WITHOUT a provider and the SDK warns and uses 'agents', rather
+     * than failing every question.
+     */
+    answerFlow?: 'agents' | 'custom';
+    /** Required when answerFlow is 'custom'. See AnswerProvider. */
+    answerProvider?: AnswerProvider;
     /**
      * Separate model configuration for DASH_COMP flow (dashboard component picking)
      * If not provided, falls back to provider-based model selection
@@ -3258,6 +3296,26 @@ declare class MainAgent {
     getSourceSummaries(): SourceSummary[];
 }
 
+interface FmtConfig {
+    /** BCP-47 tag driving grouping and the scale vocabulary, e.g. 'en-IN', 'en-US'. */
+    locale: string;
+    /** ISO-4217 code for money, e.g. 'INR', 'USD'. */
+    currency: string;
+}
+declare const DEFAULT_FMT_CONFIG: FmtConfig;
+interface Fmt {
+    money(v: unknown, decimals?: number): string;
+    num(v: unknown, decimals?: number): string;
+    count(v: unknown, decimals?: number): string;
+    pct(part: unknown, whole: unknown, decimals?: number): string;
+    delta(current: unknown, previous: unknown, decimals?: number): string;
+    date(v: unknown): string;
+    range(from: unknown, to: unknown): string;
+    list(items: unknown[], conjunction?: string): string;
+}
+/** Build a `fmt` bound to one locale/currency. */
+declare function makeFmt(cfg?: Partial<FmtConfig>): Fmt;
+
 type SystemPrompt = string | Anthropic.Messages.TextBlockParam[];
 interface LLMMessages {
     sys: SystemPrompt;
@@ -5237,6 +5295,12 @@ interface AgentRunContext {
     /** Live progress. Populated for chat mode; a task run may also stream to a log. */
     onOutput?: (chunk: string) => void;
     onEvent?: (event: AgentEvent) => void;
+    /**
+     * Assistant prose only — safe to show a non-technical user as progress.
+     * Distinct from onOutput, which also carries command and tool lines and so
+     * would leak SQL and shell text into a user-facing stream.
+     */
+    onNarration?: (text: string) => void;
     onUsage?: (usage: AgentUsage) => void;
 }
 /**
@@ -5532,6 +5596,19 @@ declare function writeBridgeShims(ws: Workspace, opts: {
         description?: string;
     }>;
     maxRows?: number;
+    /**
+     * Identity for the queries this agent runs, from mintContextToken().
+     *
+     * The agent is a separate OS process calling the bridge over loopback
+     * HTTP, so nothing ambient crosses that gap — the same break the script
+     * flow has (see utils/context-token.ts). Without this the bridge sees an
+     * anonymous query, and under SA_SQL_REWRITE_MODE=enforce the data seam
+     * refuses it outright rather than guessing whose data it is.
+     *
+     * Omit ONLY when the caller genuinely has no identity to grant; the
+     * queries are then anonymous, which is the truth rather than a default.
+     */
+    contextToken?: string;
 }): void;
 
 /**
@@ -5679,6 +5756,117 @@ interface RunScriptOptions {
  */
 declare function runScript(recipe: ScriptRecipe, scriptPath: string, params: Record<string, any>, options: RunScriptOptions): Promise<ScriptResult>;
 
+/**
+ * Answer-flow component catalog (§2.6 a/e).
+ *
+ * The frontend sends ONE catalog to the SDK; five consumers read it and four of
+ * them narrow it for their own purpose (dashComp strips the container,
+ * create-filter selects Filter*, suggestions selects isDisplayComp). The answer
+ * flow was the only one that didn't. These helpers are its narrowing.
+ *
+ * Nothing here mutates the stored `Metadata` — dashboard and report generation
+ * legitimately need the SQL-authoring contract that the answer flow must not see,
+ * so the answer flow gets a PROJECTION instead.
+ *
+ * See backend/docs/COMPONENT-GENERATION-V2.md §2.6.
+ */
+
+/**
+ * The only components that can answer a data question. Everything else in the
+ * catalog belongs to dashboards (filters, forms), is a whole page (Home,
+ * DatabaseOverview), is a UI primitive, or is the wrapper this flow builds.
+ *
+ * DynamicWaterfallChart is deliberately excluded — see §2.6(e). Adding it back
+ * is a one-line change here.
+ */
+declare const ANSWER_COMPONENT_NAMES: readonly string[];
+/**
+ * Narrow the registered catalog to the components that can answer a question.
+ * Safe for every answer-flow generator — none of them should ever nominate a
+ * filter widget, a text input, or the MultiComponentContainer the flow itself
+ * builds around their output.
+ */
+declare function answerComponents(components: Component[] | undefined): Component[];
+/**
+ * Rewrite the catalog for a flow that binds pre-executed datasets rather than
+ * authoring SQL. Apply ONLY where the flow discards component-authored SQL —
+ * `generateScriptComponents` and the `write_components` tool.
+ *
+ * Do NOT apply to `generateAgentComponents`: that path really does write SQL
+ * into externalTool.parameters.sql and validates it by executing it.
+ */
+declare function projectForDatasetBinding(components: Component[]): Component[];
+/** Filter + project in one call — the catalog the tool and script generator see. */
+declare function answerCatalogForBinding(components: Component[] | undefined): Component[];
+
+/**
+ * Component Spec Validator — V1–V8
+ *
+ * Deterministic checks of a component spec against the REAL columns of the
+ * dataset it binds. Pure: no LLM, no mutation, no I/O. Shared by the fallback
+ * generator (report-only today) and the `write_components` tool, which hands the
+ * findings back to the agent so it can fix getComponents and retry.
+ *
+ * See backend/docs/COMPONENT-GENERATION-V2.md §2.3.
+ */
+type ColType = 'NUMBER' | 'TEXT' | 'DATE' | 'BOOLEAN';
+interface ColInfo {
+    name: string;
+    type: ColType;
+    /** Every sampled non-null value is identical — a per-row invariant (e.g. a
+     * total the script computed the same on every row). Must not be summed. */
+    invariant: boolean;
+}
+/** Infer column name + type + invariance from a sample of rows. */
+declare function inferColumns(rows: any[]): Map<string, ColInfo>;
+/** Keys that must resolve to a NUMBER column. */
+declare const NUMERIC_KEYS: readonly ["yAxisKey", "valueKey", "aggregationField", "sizeKey", "latitudeField", "longitudeField", "orderField"];
+/** Keys that must resolve to a TEXT or DATE column. */
+declare const CATEGORY_KEYS: readonly ["xAxisKey", "nameKey", "seriesKey", "groupBy", "categoryKey", "dimensionKey", "labelField", "stageField"];
+/**
+ * Every config key that names a column. Superset of the generator's original
+ * list — it omitted dimensionKey (Radar), sizeKey (Scatter) and the five
+ * MapView geo fields, so those passed through unvalidated. §2.6(d).
+ */
+declare const ALL_COLUMN_KEYS: string[];
+type FindingCode = 'V1' | 'V2' | 'V3' | 'V4' | 'V5' | 'V6' | 'V7' | 'V8';
+interface ValidationFinding {
+    code: FindingCode;
+    /** `error` blocks the spec; `warn` is advisory (logged, never rejects). */
+    severity: 'error' | 'warn';
+    componentType: string;
+    /** Message written FOR THE AGENT — states the problem and the fix. */
+    message: string;
+}
+interface SpecToValidate {
+    componentType: string;
+    sourceRef?: string;
+    title?: string;
+    description?: string;
+    content?: string;
+    config?: Record<string, any>;
+}
+interface ValidationContext {
+    /** Columns of the bound dataset. */
+    cols: Map<string, ColInfo>;
+    /** UNCAPPED row count of the bound dataset — the cap is applied later, so
+     *  validating on the capped count would hide exactly the truncation we check. */
+    rowCount: number;
+    /** Rows for the mark-identity check (V4). Pass every row: a sample that happens
+     *  to hold no duplicate would report a collapsing chart as sound. */
+    rows: any[];
+    /** Valid `sourceRef` values for this run. */
+    availableSourceRefs: string[];
+    renderCap?: number;
+}
+/**
+ * Validate one component spec. Returns every finding; the caller decides
+ * whether to reject (tool path) or log (fallback path).
+ */
+declare function validateComponentSpec(spec: SpecToValidate, ctx: ValidationContext): ValidationFinding[];
+/** Render findings as the text tool-result the agent reads on a rejection. */
+declare function formatFindingsForAgent(findings: ValidationFinding[]): string;
+
 type MessageTypeHandler = (message: IncomingMessage) => void | Promise<void>;
 declare class SuperatomSDK {
     private ws;
@@ -5705,6 +5893,8 @@ declare class SuperatomSDK {
     private modelStrategy;
     private mainAgentModel;
     private sourceAgentModel;
+    private answerFlow;
+    private answerProvider?;
     private dashCompModels?;
     private conversationSimilarityThreshold;
     private userManager;
@@ -5882,4 +6072,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, 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 };
+export { ALL_COLUMN_KEYS, ANSWER_COMPONENT_NAMES, type AgentConfig, type AgentEvent, type AgentResponse, type AgentRunContext, type AgentRunHandlers, type AgentRunRecord, type AgentRunResult, type AgentTrigger, type AgentUsage, type AnswerProvider, type AnswerProviderContext, type ApplySummary, BM25L, type BM25LOptions, type BaseLLMConfig, type BuildTriggerInput, CATEGORY_KEYS, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CodexSessionOptions, type CodingAgentCollectionConfig, type CodingAgentDefinition, type CodingAgentSession, type CodingAgentSessionOptions, type CodingAgentsConfig, type ColInfo, type ColType, type CollectionHandler, type CollectionOperation, type Component, type DBUIBlock, DEFAULT_AGENT_CONFIG, DEFAULT_FMT_CONFIG, type DashboardAgentCollectionConfig, type DatabaseType, type FindingCode, type Fmt, type FmtConfig, type Harness, type HybridSearchOptions, type IncomingMessage, type KbNodesQueryFilters, type KbNodesRequestPayload, LLM, type LLMUsageEntry, type LogLevel, MainAgent, type McpServerSpec, type Message, MissingRequestContextError, type ModelStrategy, NUMERIC_KEYS, 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, type SpecToValidate, SuperatomSDK, type SuperatomSDKConfig, type T_RESPONSE, type TaskType, Thread, ThreadManager, type Tool$1 as Tool, type ToolOutputSchema, type TriggerEvent, type TriggerFireInfo, UIBlock, UILogCollector, type User, UserManager, type UsersData, type ValidationContext, type ValidationFinding, type WorkflowDescriptor, type Workspace, answerCatalogForBinding, answerComponents, anthropicLLM, assertReadOnlySql, bindContext, captureContext, clearContextTokens, contextTokenCount, createCodexSession, createCodingAgentSession, dashboardConversationHistory, dataFingerprint, describeContext, describeTriggers, emitAgentEvent, extractNamedExport, formatFindingsForAgent, geminiLLM, getCodingAgent, getCodingAgentsConfig, getRequestContext, groqLLM, hybridRerank, inferColumns, isUserContext, listCodingAgents, llmUsageLogger, logger, makeFmt, mintContextToken, normalizeScriptBody, onAgentRun, openaiLLM, policiesFromConfig, projectForDatasetBinding, queryCache, registerCodingAgentCollection, registerCodingAgents, registerDashboardAgentCollection, requireRequestContext, rerankChromaResults, rerankConversationResults, resolveContextToken, resolveScriptRecipeStore, revokeContextToken, runAsSystem, runAsUser, runCodingAgent, runScript, runWithContext, runWithMessageIdentity, startAgentTriggers, stopAgentTriggers, userPromptErrorLogger, validateComponentSpec, withCapturedContext, writeBridgeShims };

package/dist/index.js

@@ -30,13 +30,18 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ALL_COLUMN_KEYS: () => ALL_COLUMN_KEYS,
+  ANSWER_COMPONENT_NAMES: () => ANSWER_COMPONENT_NAMES,
   BM25L: () => BM25L,
+  CATEGORY_KEYS: () => CATEGORY_KEYS,
   CONTEXT_CONFIG: () => CONTEXT_CONFIG,
   CleanupService: () => CleanupService,
   DEFAULT_AGENT_CONFIG: () => DEFAULT_AGENT_CONFIG,
+  DEFAULT_FMT_CONFIG: () => DEFAULT_FMT_CONFIG,
   LLM: () => LLM,
   MainAgent: () => MainAgent,
   MissingRequestContextError: () => MissingRequestContextError,
+  NUMERIC_KEYS: () => NUMERIC_KEYS,
   STORAGE_CONFIG: () => STORAGE_CONFIG,
   ScriptMatcher: () => ScriptMatcher,
   ScriptStore: () => ScriptStore,
@@ -46,6 +51,8 @@ __export(index_exports, {
   UIBlock: () => UIBlock,
   UILogCollector: () => UILogCollector,
   UserManager: () => UserManager,
+  answerCatalogForBinding: () => answerCatalogForBinding,
+  answerComponents: () => answerComponents,
   anthropicLLM: () => anthropicLLM,
   assertReadOnlySql: () => assertReadOnlySql,
   bindContext: () => bindContext,
@@ -60,21 +67,25 @@ __export(index_exports, {
   describeTriggers: () => describeTriggers,
   emitAgentEvent: () => emitAgentEvent,
   extractNamedExport: () => extractNamedExport,
+  formatFindingsForAgent: () => formatFindingsForAgent,
   geminiLLM: () => geminiLLM,
   getCodingAgent: () => getCodingAgent,
   getCodingAgentsConfig: () => getCodingAgentsConfig,
   getRequestContext: () => getRequestContext,
   groqLLM: () => groqLLM,
   hybridRerank: () => hybridRerank,
+  inferColumns: () => inferColumns,
   isUserContext: () => isUserContext,
   listCodingAgents: () => listCodingAgents,
   llmUsageLogger: () => llmUsageLogger,
   logger: () => logger,
+  makeFmt: () => makeFmt,
   mintContextToken: () => mintContextToken,
   normalizeScriptBody: () => normalizeScriptBody,
   onAgentRun: () => onAgentRun,
   openaiLLM: () => openaiLLM,
   policiesFromConfig: () => policiesFromConfig,
+  projectForDatasetBinding: () => projectForDatasetBinding,
   queryCache: () => queryCache,
   registerCodingAgentCollection: () => registerCodingAgentCollection,
   registerCodingAgents: () => registerCodingAgents,
@@ -94,6 +105,7 @@ __export(index_exports, {
   startAgentTriggers: () => startAgentTriggers,
   stopAgentTriggers: () => stopAgentTriggers,
   userPromptErrorLogger: () => userPromptErrorLogger,
+  validateComponentSpec: () => validateComponentSpec,
   withCapturedContext: () => withCapturedContext,
   writeBridgeShims: () => writeBridgeShims
 });
@@ -15896,6 +15908,9 @@ function projectForDatasetBinding(components) {
     props: projectProps(c.props)
   }));
 }
+function answerCatalogForBinding(components) {
+  return projectForDatasetBinding(answerComponents(components));
+}
 
 // src/userResponse/anthropic.ts
 var import_dotenv = __toESM(require("dotenv"));
@@ -19368,7 +19383,7 @@ function handleUserPromptAbort(data, sendMessage) {
     logger.warn(`[UserPromptAbort] Failed to send abort ack: ${err instanceof Error ? err.message : String(err)}`);
   }
 }
-var get_user_request = async (data, components, sendMessage, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, collections, externalTools, mainAgentModel, sourceAgentModel, workflows) => {
+var get_user_request = async (data, components, sendMessage, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, collections, externalTools, mainAgentModel, sourceAgentModel, workflows, answerProvider) => {
   const errors = [];
   const parseResult = UserPromptRequestMessageSchema.safeParse(data);
   if (!parseResult.success) {
@@ -19482,7 +19497,18 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
   }
   let userResponse;
   try {
-    userResponse = await get_agent_user_response(
+    userResponse = answerProvider ? await answerProvider({
+      prompt,
+      components,
+      collections,
+      externalTools,
+      userId,
+      threadId,
+      userConfig,
+      conversationHistory,
+      onStream: streamCallback,
+      signal: abortController.signal
+    }) : await get_agent_user_response(
       prompt,
       components,
       anthropicApiKey,
@@ -19746,8 +19772,8 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
     wsId
   };
 };
-async function handleUserPromptRequest(data, components, sendMessage, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, collections, externalTools, mainAgentModel, sourceAgentModel, workflows) {
-  const response = await runWithMessageIdentity(data, () => get_user_request(data, components, sendMessage, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, collections, externalTools, mainAgentModel, sourceAgentModel, workflows));
+async function handleUserPromptRequest(data, components, sendMessage, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, collections, externalTools, mainAgentModel, sourceAgentModel, workflows, answerProvider) {
+  const response = await runWithMessageIdentity(data, () => get_user_request(data, components, sendMessage, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, collections, externalTools, mainAgentModel, sourceAgentModel, workflows, answerProvider));
   if (response.data?.component?.props?.config?.components) {
     response.data.component.props.config.components = response.data.component.props.config.components.map((comp) => ({
       ...comp,
@@ -24531,6 +24557,7 @@ async function runCodingAgent(agentId, options = {}) {
     signal: options.signal,
     onOutput: options.onOutput,
     onEvent: options.onEvent,
+    onNarration: options.onNarration,
     onUsage: options.onUsage
   };
   const input = options.input ?? {};
@@ -24573,6 +24600,17 @@ async function runCodingAgent(agentId, options = {}) {
         {
           onOutput: ctx.onOutput,
           onEvent: ctx.onEvent,
+          // Narration is user-facing, so drop anything that mentions the
+          // workspace. The harness closes a turn with its own line about the
+          // deliverable ("Completed and validated [out/answer.json](/abs/path…)"),
+          // which is internal chatter AND leaks a server path to whoever asked
+          // the question. The real answer reaches the caller through the
+          // deliverable and `answer`, never through this stream, so nothing is
+          // lost by suppressing it. onOutput still sees everything.
+          onNarration: ctx.onNarration ? (text) => {
+            if (text.includes(dir)) return;
+            ctx.onNarration(text.endsWith("\n") ? text : text + "\n\n");
+          } : void 0,
           onUsage: ctx.onUsage,
           // Opt-in only: see stopOnDeliverable. Letting the turn end naturally
           // is what makes usage reporting work at all.
@@ -24702,6 +24740,7 @@ function writeBridgeShims(ws, opts) {
 ${READ_ONLY_SQL_SOURCE}
 const BRIDGE = ${JSON.stringify(opts.bridgeUrl)};
 const MAX_ROWS = ${maxRows};
+const CONTEXT_TOKEN = ${JSON.stringify(opts.contextToken ?? null)};
 
 const [toolId, sql, limitArg] = process.argv.slice(2);
 if (!toolId || !sql) {
@@ -24712,7 +24751,12 @@ try { assertReadOnlySql(sql); } catch (e) { console.error(String(e.message || e)
 
 fetch(BRIDGE + '/query', {
   method: 'POST',
-  headers: { 'content-type': 'application/json' },
+  headers: {
+    'content-type': 'application/json',
+    // Carries WHO this query runs as. The bridge resolves it back to the
+    // request context; absent, the data seam treats the query as anonymous.
+    ...(CONTEXT_TOKEN ? { 'x-sa-context': CONTEXT_TOKEN } : {}),
+  },
   body: JSON.stringify({ toolId, sql, limit: Math.min(Number(limitArg) || MAX_ROWS, MAX_ROWS) }),
 })
   .then(async (r) => {
@@ -26759,6 +26803,127 @@ var ReportManager = class {
   }
 };
 
+// src/userResponse/scripts/fmt.ts
+var DASH = "\u2014";
+var DEFAULT_FMT_CONFIG = { locale: "en-IN", currency: "INR" };
+var MONEY_TIERS = {
+  "en-IN": [[1e7, "Cr"], [1e5, "L"]],
+  "hi-IN": [[1e7, "Cr"], [1e5, "L"]]
+};
+var DEFAULT_MONEY_TIERS = [[1e9, "B"], [1e6, "M"]];
+function moneyTiers(locale) {
+  return MONEY_TIERS[locale] ?? DEFAULT_MONEY_TIERS;
+}
+var COUNT_SCALE_MIN = 1e7;
+function toNum(v) {
+  if (v === null || v === void 0 || v === "") return null;
+  const n = typeof v === "number" ? v : Number(v);
+  return Number.isFinite(n) ? n : null;
+}
+var MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+var ISO_DATE = /^\d{4}-\d{2}-\d{2}([T ]|$)/;
+function toDate(v) {
+  if (v === null || v === void 0 || v === "") return null;
+  if (v instanceof Date) return Number.isNaN(v.getTime()) ? null : v;
+  if (typeof v === "number") {
+    const d = new Date(v);
+    return Number.isNaN(d.getTime()) ? null : d;
+  }
+  if (typeof v === "string" && ISO_DATE.test(v.trim())) {
+    const d = new Date(v.trim());
+    return Number.isNaN(d.getTime()) ? null : d;
+  }
+  return null;
+}
+function makeFmt(cfg = {}) {
+  const locale = cfg.locale || DEFAULT_FMT_CONFIG.locale;
+  const currency = cfg.currency || DEFAULT_FMT_CONFIG.currency;
+  const group = (n, decimals = 0) => n.toLocaleString(locale, { minimumFractionDigits: decimals, maximumFractionDigits: decimals });
+  const symbol = (() => {
+    try {
+      const parts = new Intl.NumberFormat(locale, { style: "currency", currency }).formatToParts(0);
+      return parts.find((p) => p.type === "currency")?.value ?? "";
+    } catch {
+      return "";
+    }
+  })();
+  const scaled = (abs, tiers, decimals) => {
+    for (const [threshold, unit] of tiers) {
+      if (abs >= threshold) return `${group(abs / threshold, decimals)} ${unit}`;
+    }
+    return null;
+  };
+  function money(v, decimals = 2) {
+    const n = toNum(v);
+    if (n === null) return DASH;
+    const sign = n < 0 ? "-" : "";
+    const abs = Math.abs(n);
+    const tiers = moneyTiers(locale);
+    for (let i = 0; i < tiers.length; i++) {
+      const [threshold, unit] = tiers[i];
+      if (abs < threshold) continue;
+      const value = Number((abs / threshold).toFixed(decimals));
+      const higher = tiers[i - 1];
+      if (higher && value * threshold >= higher[0]) {
+        return `${sign}${symbol}${group(abs / higher[0], decimals)} ${higher[1]}`;
+      }
+      return `${sign}${symbol}${group(abs / threshold, decimals)} ${unit}`;
+    }
+    try {
+      return new Intl.NumberFormat(locale, {
+        style: "currency",
+        currency,
+        minimumFractionDigits: Number.isInteger(n) ? 0 : decimals,
+        maximumFractionDigits: decimals
+      }).format(n);
+    } catch {
+      return `${sign}${symbol}${group(abs, Number.isInteger(abs) ? 0 : decimals)}`;
+    }
+  }
+  function num(v, decimals) {
+    const n = toNum(v);
+    if (n === null) return DASH;
+    return group(n, decimals ?? (Number.isInteger(n) ? 0 : 2));
+  }
+  function count(v, decimals = 2) {
+    const n = toNum(v);
+    if (n === null) return DASH;
+    const abs = Math.abs(n);
+    const s = abs >= COUNT_SCALE_MIN ? scaled(abs, moneyTiers(locale), decimals) : null;
+    if (s) return `${n < 0 ? "-" : ""}${s}`;
+    return group(n, Number.isInteger(n) ? 0 : decimals);
+  }
+  function pct(part, whole, decimals = 1) {
+    const p = toNum(part), w = toNum(whole);
+    if (p === null || w === null || w === 0) return DASH;
+    return `${group(p / w * 100, decimals)}%`;
+  }
+  function delta(current, previous, decimals = 1) {
+    const c = toNum(current), p = toNum(previous);
+    if (c === null || p === null || p === 0) return DASH;
+    const change = (c - p) / Math.abs(p) * 100;
+    return `${change >= 0 ? "+" : "-"}${group(Math.abs(change), decimals)}%`;
+  }
+  function date(v) {
+    const d = toDate(v);
+    if (!d) return DASH;
+    return `${d.getUTCDate()} ${MONTHS[d.getUTCMonth()]} ${d.getUTCFullYear()}`;
+  }
+  function range(from, to) {
+    const a = toDate(from), b = toDate(to);
+    if (!a || !b) return DASH;
+    const left = a.getUTCFullYear() === b.getUTCFullYear() ? `${a.getUTCDate()} ${MONTHS[a.getUTCMonth()]}` : date(a);
+    return `${left} \u2013 ${date(b)}`;
+  }
+  function list(items, conjunction = "and") {
+    const parts = (items || []).map((i) => String(i ?? "").trim()).filter(Boolean);
+    if (!parts.length) return DASH;
+    if (parts.length === 1) return parts[0];
+    return `${parts.slice(0, -1).join(", ")} ${conjunction} ${parts[parts.length - 1]}`;
+  }
+  return { money, num, count, pct, delta, date, range, list };
+}
+
 // src/utils/log-collector.ts
 var LOG_LEVEL_PRIORITY2 = {
   errors: 0,
@@ -27986,6 +28151,13 @@ var SuperatomSDK = class {
     this.modelStrategy = config2.modelStrategy || "fast";
     this.mainAgentModel = config2.mainAgentModel || "anthropic/claude-sonnet-4-5-20250929";
     this.sourceAgentModel = config2.sourceAgentModel || "anthropic/claude-sonnet-4-5-20250929";
+    this.answerProvider = config2.answerProvider;
+    this.answerFlow = config2.answerFlow || "agents";
+    if (this.answerFlow === "custom" && !this.answerProvider) {
+      logger.warn('[SDK] answerFlow is "custom" but no answerProvider was given \u2014 using the built-in agent flow.');
+      this.answerFlow = "agents";
+    }
+    logger.info(`[SDK] Answer flow: ${this.answerFlow}${this.answerFlow === "custom" ? " (answerProvider)" : " (MainAgent + SourceAgent)"}`);
     this.dashCompModels = config2.dashCompModels;
     this.conversationSimilarityThreshold = config2.conversationSimilarityThreshold ?? 0.8;
     this.applyModelStrategy(this.modelStrategy);
@@ -28145,7 +28317,22 @@ var SuperatomSDK = class {
           });
           break;
         case "USER_PROMPT_REQ":
-          handleUserPromptRequest(parsed, this.components, (msg) => this.send(msg), this.anthropicApiKey, this.groqApiKey, this.geminiApiKey, this.openaiApiKey, this.llmProviders, this.collections, this.tools, this.mainAgentModel, this.sourceAgentModel, this.workflows).catch((error) => {
+          handleUserPromptRequest(
+            parsed,
+            this.components,
+            (msg) => this.send(msg),
+            this.anthropicApiKey,
+            this.groqApiKey,
+            this.geminiApiKey,
+            this.openaiApiKey,
+            this.llmProviders,
+            this.collections,
+            this.tools,
+            this.mainAgentModel,
+            this.sourceAgentModel,
+            this.workflows,
+            this.answerFlow === "custom" ? this.answerProvider : void 0
+          ).catch((error) => {
             logger.error("Failed to handle user prompt request:", error);
           });
           break;
@@ -28554,13 +28741,18 @@ var SuperatomSDK = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ALL_COLUMN_KEYS,
+  ANSWER_COMPONENT_NAMES,
   BM25L,
+  CATEGORY_KEYS,
   CONTEXT_CONFIG,
   CleanupService,
   DEFAULT_AGENT_CONFIG,
+  DEFAULT_FMT_CONFIG,
   LLM,
   MainAgent,
   MissingRequestContextError,
+  NUMERIC_KEYS,
   STORAGE_CONFIG,
   ScriptMatcher,
   ScriptStore,
@@ -28570,6 +28762,8 @@ var SuperatomSDK = class {
   UIBlock,
   UILogCollector,
   UserManager,
+  answerCatalogForBinding,
+  answerComponents,
   anthropicLLM,
   assertReadOnlySql,
   bindContext,
@@ -28584,21 +28778,25 @@ var SuperatomSDK = class {
   describeTriggers,
   emitAgentEvent,
   extractNamedExport,
+  formatFindingsForAgent,
   geminiLLM,
   getCodingAgent,
   getCodingAgentsConfig,
   getRequestContext,
   groqLLM,
   hybridRerank,
+  inferColumns,
   isUserContext,
   listCodingAgents,
   llmUsageLogger,
   logger,
+  makeFmt,
   mintContextToken,
   normalizeScriptBody,
   onAgentRun,
   openaiLLM,
   policiesFromConfig,
+  projectForDatasetBinding,
   queryCache,
   registerCodingAgentCollection,
   registerCodingAgents,
@@ -28618,6 +28816,7 @@ var SuperatomSDK = class {
   startAgentTriggers,
   stopAgentTriggers,
   userPromptErrorLogger,
+  validateComponentSpec,
   withCapturedContext,
   writeBridgeShims
 });

package/dist/index.mjs

@@ -15802,6 +15802,9 @@ function projectForDatasetBinding(components) {
     props: projectProps(c.props)
   }));
 }
+function answerCatalogForBinding(components) {
+  return projectForDatasetBinding(answerComponents(components));
+}
 
 // src/userResponse/anthropic.ts
 import dotenv from "dotenv";
@@ -19274,7 +19277,7 @@ function handleUserPromptAbort(data, sendMessage) {
     logger.warn(`[UserPromptAbort] Failed to send abort ack: ${err instanceof Error ? err.message : String(err)}`);
   }
 }
-var get_user_request = async (data, components, sendMessage, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, collections, externalTools, mainAgentModel, sourceAgentModel, workflows) => {
+var get_user_request = async (data, components, sendMessage, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, collections, externalTools, mainAgentModel, sourceAgentModel, workflows, answerProvider) => {
   const errors = [];
   const parseResult = UserPromptRequestMessageSchema.safeParse(data);
   if (!parseResult.success) {
@@ -19388,7 +19391,18 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
   }
   let userResponse;
   try {
-    userResponse = await get_agent_user_response(
+    userResponse = answerProvider ? await answerProvider({
+      prompt,
+      components,
+      collections,
+      externalTools,
+      userId,
+      threadId,
+      userConfig,
+      conversationHistory,
+      onStream: streamCallback,
+      signal: abortController.signal
+    }) : await get_agent_user_response(
       prompt,
       components,
       anthropicApiKey,
@@ -19652,8 +19666,8 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
     wsId
   };
 };
-async function handleUserPromptRequest(data, components, sendMessage, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, collections, externalTools, mainAgentModel, sourceAgentModel, workflows) {
-  const response = await runWithMessageIdentity(data, () => get_user_request(data, components, sendMessage, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, collections, externalTools, mainAgentModel, sourceAgentModel, workflows));
+async function handleUserPromptRequest(data, components, sendMessage, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, collections, externalTools, mainAgentModel, sourceAgentModel, workflows, answerProvider) {
+  const response = await runWithMessageIdentity(data, () => get_user_request(data, components, sendMessage, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, collections, externalTools, mainAgentModel, sourceAgentModel, workflows, answerProvider));
   if (response.data?.component?.props?.config?.components) {
     response.data.component.props.config.components = response.data.component.props.config.components.map((comp) => ({
       ...comp,
@@ -24437,6 +24451,7 @@ async function runCodingAgent(agentId, options = {}) {
     signal: options.signal,
     onOutput: options.onOutput,
     onEvent: options.onEvent,
+    onNarration: options.onNarration,
     onUsage: options.onUsage
   };
   const input = options.input ?? {};
@@ -24479,6 +24494,17 @@ async function runCodingAgent(agentId, options = {}) {
         {
           onOutput: ctx.onOutput,
           onEvent: ctx.onEvent,
+          // Narration is user-facing, so drop anything that mentions the
+          // workspace. The harness closes a turn with its own line about the
+          // deliverable ("Completed and validated [out/answer.json](/abs/path…)"),
+          // which is internal chatter AND leaks a server path to whoever asked
+          // the question. The real answer reaches the caller through the
+          // deliverable and `answer`, never through this stream, so nothing is
+          // lost by suppressing it. onOutput still sees everything.
+          onNarration: ctx.onNarration ? (text) => {
+            if (text.includes(dir)) return;
+            ctx.onNarration(text.endsWith("\n") ? text : text + "\n\n");
+          } : void 0,
           onUsage: ctx.onUsage,
           // Opt-in only: see stopOnDeliverable. Letting the turn end naturally
           // is what makes usage reporting work at all.
@@ -24608,6 +24634,7 @@ function writeBridgeShims(ws, opts) {
 ${READ_ONLY_SQL_SOURCE}
 const BRIDGE = ${JSON.stringify(opts.bridgeUrl)};
 const MAX_ROWS = ${maxRows};
+const CONTEXT_TOKEN = ${JSON.stringify(opts.contextToken ?? null)};
 
 const [toolId, sql, limitArg] = process.argv.slice(2);
 if (!toolId || !sql) {
@@ -24618,7 +24645,12 @@ try { assertReadOnlySql(sql); } catch (e) { console.error(String(e.message || e)
 
 fetch(BRIDGE + '/query', {
   method: 'POST',
-  headers: { 'content-type': 'application/json' },
+  headers: {
+    'content-type': 'application/json',
+    // Carries WHO this query runs as. The bridge resolves it back to the
+    // request context; absent, the data seam treats the query as anonymous.
+    ...(CONTEXT_TOKEN ? { 'x-sa-context': CONTEXT_TOKEN } : {}),
+  },
   body: JSON.stringify({ toolId, sql, limit: Math.min(Number(limitArg) || MAX_ROWS, MAX_ROWS) }),
 })
   .then(async (r) => {
@@ -26665,6 +26697,127 @@ var ReportManager = class {
   }
 };
 
+// src/userResponse/scripts/fmt.ts
+var DASH = "\u2014";
+var DEFAULT_FMT_CONFIG = { locale: "en-IN", currency: "INR" };
+var MONEY_TIERS = {
+  "en-IN": [[1e7, "Cr"], [1e5, "L"]],
+  "hi-IN": [[1e7, "Cr"], [1e5, "L"]]
+};
+var DEFAULT_MONEY_TIERS = [[1e9, "B"], [1e6, "M"]];
+function moneyTiers(locale) {
+  return MONEY_TIERS[locale] ?? DEFAULT_MONEY_TIERS;
+}
+var COUNT_SCALE_MIN = 1e7;
+function toNum(v) {
+  if (v === null || v === void 0 || v === "") return null;
+  const n = typeof v === "number" ? v : Number(v);
+  return Number.isFinite(n) ? n : null;
+}
+var MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+var ISO_DATE = /^\d{4}-\d{2}-\d{2}([T ]|$)/;
+function toDate(v) {
+  if (v === null || v === void 0 || v === "") return null;
+  if (v instanceof Date) return Number.isNaN(v.getTime()) ? null : v;
+  if (typeof v === "number") {
+    const d = new Date(v);
+    return Number.isNaN(d.getTime()) ? null : d;
+  }
+  if (typeof v === "string" && ISO_DATE.test(v.trim())) {
+    const d = new Date(v.trim());
+    return Number.isNaN(d.getTime()) ? null : d;
+  }
+  return null;
+}
+function makeFmt(cfg = {}) {
+  const locale = cfg.locale || DEFAULT_FMT_CONFIG.locale;
+  const currency = cfg.currency || DEFAULT_FMT_CONFIG.currency;
+  const group = (n, decimals = 0) => n.toLocaleString(locale, { minimumFractionDigits: decimals, maximumFractionDigits: decimals });
+  const symbol = (() => {
+    try {
+      const parts = new Intl.NumberFormat(locale, { style: "currency", currency }).formatToParts(0);
+      return parts.find((p) => p.type === "currency")?.value ?? "";
+    } catch {
+      return "";
+    }
+  })();
+  const scaled = (abs, tiers, decimals) => {
+    for (const [threshold, unit] of tiers) {
+      if (abs >= threshold) return `${group(abs / threshold, decimals)} ${unit}`;
+    }
+    return null;
+  };
+  function money(v, decimals = 2) {
+    const n = toNum(v);
+    if (n === null) return DASH;
+    const sign = n < 0 ? "-" : "";
+    const abs = Math.abs(n);
+    const tiers = moneyTiers(locale);
+    for (let i = 0; i < tiers.length; i++) {
+      const [threshold, unit] = tiers[i];
+      if (abs < threshold) continue;
+      const value = Number((abs / threshold).toFixed(decimals));
+      const higher = tiers[i - 1];
+      if (higher && value * threshold >= higher[0]) {
+        return `${sign}${symbol}${group(abs / higher[0], decimals)} ${higher[1]}`;
+      }
+      return `${sign}${symbol}${group(abs / threshold, decimals)} ${unit}`;
+    }
+    try {
+      return new Intl.NumberFormat(locale, {
+        style: "currency",
+        currency,
+        minimumFractionDigits: Number.isInteger(n) ? 0 : decimals,
+        maximumFractionDigits: decimals
+      }).format(n);
+    } catch {
+      return `${sign}${symbol}${group(abs, Number.isInteger(abs) ? 0 : decimals)}`;
+    }
+  }
+  function num(v, decimals) {
+    const n = toNum(v);
+    if (n === null) return DASH;
+    return group(n, decimals ?? (Number.isInteger(n) ? 0 : 2));
+  }
+  function count(v, decimals = 2) {
+    const n = toNum(v);
+    if (n === null) return DASH;
+    const abs = Math.abs(n);
+    const s = abs >= COUNT_SCALE_MIN ? scaled(abs, moneyTiers(locale), decimals) : null;
+    if (s) return `${n < 0 ? "-" : ""}${s}`;
+    return group(n, Number.isInteger(n) ? 0 : decimals);
+  }
+  function pct(part, whole, decimals = 1) {
+    const p = toNum(part), w = toNum(whole);
+    if (p === null || w === null || w === 0) return DASH;
+    return `${group(p / w * 100, decimals)}%`;
+  }
+  function delta(current, previous, decimals = 1) {
+    const c = toNum(current), p = toNum(previous);
+    if (c === null || p === null || p === 0) return DASH;
+    const change = (c - p) / Math.abs(p) * 100;
+    return `${change >= 0 ? "+" : "-"}${group(Math.abs(change), decimals)}%`;
+  }
+  function date(v) {
+    const d = toDate(v);
+    if (!d) return DASH;
+    return `${d.getUTCDate()} ${MONTHS[d.getUTCMonth()]} ${d.getUTCFullYear()}`;
+  }
+  function range(from, to) {
+    const a = toDate(from), b = toDate(to);
+    if (!a || !b) return DASH;
+    const left = a.getUTCFullYear() === b.getUTCFullYear() ? `${a.getUTCDate()} ${MONTHS[a.getUTCMonth()]}` : date(a);
+    return `${left} \u2013 ${date(b)}`;
+  }
+  function list(items, conjunction = "and") {
+    const parts = (items || []).map((i) => String(i ?? "").trim()).filter(Boolean);
+    if (!parts.length) return DASH;
+    if (parts.length === 1) return parts[0];
+    return `${parts.slice(0, -1).join(", ")} ${conjunction} ${parts[parts.length - 1]}`;
+  }
+  return { money, num, count, pct, delta, date, range, list };
+}
+
 // src/utils/log-collector.ts
 var LOG_LEVEL_PRIORITY2 = {
   errors: 0,
@@ -27892,6 +28045,13 @@ var SuperatomSDK = class {
     this.modelStrategy = config2.modelStrategy || "fast";
     this.mainAgentModel = config2.mainAgentModel || "anthropic/claude-sonnet-4-5-20250929";
     this.sourceAgentModel = config2.sourceAgentModel || "anthropic/claude-sonnet-4-5-20250929";
+    this.answerProvider = config2.answerProvider;
+    this.answerFlow = config2.answerFlow || "agents";
+    if (this.answerFlow === "custom" && !this.answerProvider) {
+      logger.warn('[SDK] answerFlow is "custom" but no answerProvider was given \u2014 using the built-in agent flow.');
+      this.answerFlow = "agents";
+    }
+    logger.info(`[SDK] Answer flow: ${this.answerFlow}${this.answerFlow === "custom" ? " (answerProvider)" : " (MainAgent + SourceAgent)"}`);
     this.dashCompModels = config2.dashCompModels;
     this.conversationSimilarityThreshold = config2.conversationSimilarityThreshold ?? 0.8;
     this.applyModelStrategy(this.modelStrategy);
@@ -28051,7 +28211,22 @@ var SuperatomSDK = class {
           });
           break;
         case "USER_PROMPT_REQ":
-          handleUserPromptRequest(parsed, this.components, (msg) => this.send(msg), this.anthropicApiKey, this.groqApiKey, this.geminiApiKey, this.openaiApiKey, this.llmProviders, this.collections, this.tools, this.mainAgentModel, this.sourceAgentModel, this.workflows).catch((error) => {
+          handleUserPromptRequest(
+            parsed,
+            this.components,
+            (msg) => this.send(msg),
+            this.anthropicApiKey,
+            this.groqApiKey,
+            this.geminiApiKey,
+            this.openaiApiKey,
+            this.llmProviders,
+            this.collections,
+            this.tools,
+            this.mainAgentModel,
+            this.sourceAgentModel,
+            this.workflows,
+            this.answerFlow === "custom" ? this.answerProvider : void 0
+          ).catch((error) => {
             logger.error("Failed to handle user prompt request:", error);
           });
           break;
@@ -28459,13 +28634,18 @@ var SuperatomSDK = class {
   }
 };
 export {
+  ALL_COLUMN_KEYS,
+  ANSWER_COMPONENT_NAMES,
   BM25L,
+  CATEGORY_KEYS,
   CONTEXT_CONFIG,
   CleanupService,
   DEFAULT_AGENT_CONFIG,
+  DEFAULT_FMT_CONFIG,
   LLM,
   MainAgent,
   MissingRequestContextError,
+  NUMERIC_KEYS,
   STORAGE_CONFIG,
   ScriptMatcher,
   ScriptStore,
@@ -28475,6 +28655,8 @@ export {
   UIBlock,
   UILogCollector,
   UserManager,
+  answerCatalogForBinding,
+  answerComponents,
   anthropicLLM,
   assertReadOnlySql,
   bindContext,
@@ -28489,21 +28671,25 @@ export {
   describeTriggers,
   emitAgentEvent,
   extractNamedExport,
+  formatFindingsForAgent,
   geminiLLM,
   getCodingAgent,
   getCodingAgentsConfig,
   getRequestContext,
   groqLLM,
   hybridRerank,
+  inferColumns,
   isUserContext,
   listCodingAgents,
   llmUsageLogger,
   logger,
+  makeFmt,
   mintContextToken,
   normalizeScriptBody,
   onAgentRun,
   openaiLLM,
   policiesFromConfig,
+  projectForDatasetBinding,
   queryCache,
   registerCodingAgentCollection,
   registerCodingAgents,
@@ -28523,6 +28709,7 @@ export {
   startAgentTriggers,
   stopAgentTriggers,
   userPromptErrorLogger,
+  validateComponentSpec,
   withCapturedContext,
   writeBridgeShims
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superatomai/sdk-node",
-  "version": "0.0.58-dsp",
+  "version": "0.0.59-dsp",
   "description": "Node.js TypeScript SDK for Superatom",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",