@superatomai/sdk-node 0.0.65-dsp → 0.0.66-dsp

package/dist/index.d.mts

@@ -1257,6 +1257,10 @@ interface DBUIBlock {
         name?: string;
         columns?: string[];
     };
+    /** Progress updates written while this answer was produced, in order. */
+    narration?: NarrationUpdate[];
+    /** How long the answer took, in milliseconds. */
+    durationMs?: number;
 }
 
 /**
@@ -2113,14 +2117,49 @@ interface AnswerProviderContext {
     conversationHistory?: string;
     /** Stream user-facing prose. Do NOT stream tool/command output through this. */
     onStream?: (chunk: string) => void;
+    /**
+     * Send one narrator update to the client live, as its OWN message
+     * (USER_PROMPT_NARRATION) — never into the answer stream, so it is not part of
+     * the saved answer text. Every response mode. The saved copy travels
+     * separately, as `data.narration`.
+     */
+    onNarration?: (update: {
+        elapsedMs: number;
+        text: string;
+    }) => void;
     signal?: AbortSignal;
 }
+/**
+ * One narrator tick while an answer was being produced: what the narrator was
+ * given, and what it wrote. Returned as `data.narration` (an array, in order)
+ * and saved with the answer as `response.narration`, unchanged. A UI shows the
+ * `shown` entries; the rest are kept for judging the narrator against its input.
+ */
+interface NarrationUpdate {
+    /** Milliseconds since the question arrived. */
+    elapsedMs: number;
+    /** shown | skipped | dropped (refused by an output filter) | failed. */
+    status?: 'shown' | 'skipped' | 'dropped' | 'failed';
+    /** The update itself; null when nothing was shown. */
+    text: string | null;
+    /** Why an update was dropped or failed. */
+    reason?: string;
+    /**
+     * What the narrator was given for this tick — the agent's notes, commands
+     * with their output, queries with SQL and sample rows. Shape is the
+     * deployment's; the SDK stores it as-is.
+     */
+    activity?: unknown[];
+}
 /**
  * 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.
+ *
+ * `data.narration` (NarrationUpdate[]) is optional and saved with the answer on
+ * every outcome — success, error and abort — so return it on each of them.
  */
 type AnswerProvider = (ctx: AnswerProviderContext) => Promise<T_RESPONSE>;
 interface SuperatomSDKConfig {
@@ -3651,6 +3690,18 @@ declare class UIBlock {
     setTextResponse(textResponse: string | null): void;
     /** The program-generated half of the answer — see setProgramAnswer. */
     programAnswer?: string | null;
+    /** Progress updates written while the answer was produced — see setNarration. */
+    narration?: NarrationUpdate[] | null;
+    /**
+     * Progress updates a narrator wrote while this answer was being produced,
+     * in order. Not part of the answer text: kept beside it so it is saved with
+     * the answer it describes, and can be shown or left out on its own.
+     */
+    setNarration(updates: NarrationUpdate[] | null): void;
+    getNarration(): NarrationUpdate[] | null;
+    /** How long the answer took, from the request arriving to the flow returning. */
+    durationMs?: number | null;
+    setDurationMs(ms: number | null): void;
     /**
      * Bind this block to the script recipe that produced its answer.
      */
@@ -6089,4 +6140,4 @@ declare class SuperatomSDK {
     getConversationSimilarityThreshold(): number;
 }
 
-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 };
+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 NarrationUpdate, 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

@@ -1257,6 +1257,10 @@ interface DBUIBlock {
         name?: string;
         columns?: string[];
     };
+    /** Progress updates written while this answer was produced, in order. */
+    narration?: NarrationUpdate[];
+    /** How long the answer took, in milliseconds. */
+    durationMs?: number;
 }
 
 /**
@@ -2113,14 +2117,49 @@ interface AnswerProviderContext {
     conversationHistory?: string;
     /** Stream user-facing prose. Do NOT stream tool/command output through this. */
     onStream?: (chunk: string) => void;
+    /**
+     * Send one narrator update to the client live, as its OWN message
+     * (USER_PROMPT_NARRATION) — never into the answer stream, so it is not part of
+     * the saved answer text. Every response mode. The saved copy travels
+     * separately, as `data.narration`.
+     */
+    onNarration?: (update: {
+        elapsedMs: number;
+        text: string;
+    }) => void;
     signal?: AbortSignal;
 }
+/**
+ * One narrator tick while an answer was being produced: what the narrator was
+ * given, and what it wrote. Returned as `data.narration` (an array, in order)
+ * and saved with the answer as `response.narration`, unchanged. A UI shows the
+ * `shown` entries; the rest are kept for judging the narrator against its input.
+ */
+interface NarrationUpdate {
+    /** Milliseconds since the question arrived. */
+    elapsedMs: number;
+    /** shown | skipped | dropped (refused by an output filter) | failed. */
+    status?: 'shown' | 'skipped' | 'dropped' | 'failed';
+    /** The update itself; null when nothing was shown. */
+    text: string | null;
+    /** Why an update was dropped or failed. */
+    reason?: string;
+    /**
+     * What the narrator was given for this tick — the agent's notes, commands
+     * with their output, queries with SQL and sample rows. Shape is the
+     * deployment's; the SDK stores it as-is.
+     */
+    activity?: unknown[];
+}
 /**
  * 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.
+ *
+ * `data.narration` (NarrationUpdate[]) is optional and saved with the answer on
+ * every outcome — success, error and abort — so return it on each of them.
  */
 type AnswerProvider = (ctx: AnswerProviderContext) => Promise<T_RESPONSE>;
 interface SuperatomSDKConfig {
@@ -3651,6 +3690,18 @@ declare class UIBlock {
     setTextResponse(textResponse: string | null): void;
     /** The program-generated half of the answer — see setProgramAnswer. */
     programAnswer?: string | null;
+    /** Progress updates written while the answer was produced — see setNarration. */
+    narration?: NarrationUpdate[] | null;
+    /**
+     * Progress updates a narrator wrote while this answer was being produced,
+     * in order. Not part of the answer text: kept beside it so it is saved with
+     * the answer it describes, and can be shown or left out on its own.
+     */
+    setNarration(updates: NarrationUpdate[] | null): void;
+    getNarration(): NarrationUpdate[] | null;
+    /** How long the answer took, from the request arriving to the flow returning. */
+    durationMs?: number | null;
+    setDurationMs(ms: number | null): void;
     /**
      * Bind this block to the script recipe that produced its answer.
      */
@@ -6089,4 +6140,4 @@ declare class SuperatomSDK {
     getConversationSimilarityThreshold(): number;
 }
 
-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 };
+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 NarrationUpdate, 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

@@ -1319,6 +1319,20 @@ var UIBlock = class {
   setTextResponse(textResponse) {
     this.textResponse = textResponse;
   }
+  /**
+   * Progress updates a narrator wrote while this answer was being produced,
+   * in order. Not part of the answer text: kept beside it so it is saved with
+   * the answer it describes, and can be shown or left out on its own.
+   */
+  setNarration(updates) {
+    this.narration = updates && updates.length ? updates : null;
+  }
+  getNarration() {
+    return this.narration ?? null;
+  }
+  setDurationMs(ms) {
+    this.durationMs = typeof ms === "number" && Number.isFinite(ms) && ms >= 0 ? Math.round(ms) : null;
+  }
   /**
    * Bind this block to the script recipe that produced its answer.
    */
@@ -1356,7 +1370,9 @@ var UIBlock = class {
       textResponse: this.textResponse,
       createdAt: this.createdAt.toISOString(),
       ...this.scriptBinding ? { scriptBinding: this.scriptBinding } : {},
-      ...this.programAnswer ? { programAnswer: this.programAnswer } : {}
+      ...this.programAnswer ? { programAnswer: this.programAnswer } : {},
+      ...this.narration ? { narration: this.narration } : {},
+      ...this.durationMs != null ? { durationMs: this.durationMs } : {}
     };
   }
 };
@@ -19210,7 +19226,10 @@ function transformUIBlockForDB(uiblock, userPrompt, uiBlockId) {
     ...uiblock?.scriptBinding?.recipeId ? { scriptBinding: uiblock.scriptBinding } : {},
     // The program-generated half, stored verbatim so a reload can regenerate
     // just that portion of `analysis` and leave the narration alone.
-    ...uiblock?.programAnswer ? { programAnswer: uiblock.programAnswer } : {}
+    ...uiblock?.programAnswer ? { programAnswer: uiblock.programAnswer } : {},
+    // Beside the answer, not in it: `analysis` stays the answer text alone.
+    ...Array.isArray(uiblock?.narration) && uiblock.narration.length ? { narration: uiblock.narration } : {},
+    ...typeof uiblock?.durationMs === "number" ? { durationMs: uiblock.durationMs } : {}
   };
 }
 function hasTraceContent(trace) {
@@ -19518,6 +19537,20 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
       }
     };
   }
+  let narrationSeq = 0;
+  const narrationCallback = (update) => {
+    try {
+      sendMessage({
+        id: `narration_${existingUiBlockId}`,
+        type: "USER_PROMPT_NARRATION",
+        from: { type: "data-agent" },
+        to: { type: "runtime", id: wsId },
+        payload: { uiBlockId: existingUiBlockId, threadId, seq: narrationSeq++, ...update }
+      });
+    } catch (err) {
+      logger.warn(`[UserPromptRequest] Narration send failed (WebSocket may be closed): ${err instanceof Error ? err.message : String(err)}`);
+    }
+  };
   let userResponse;
   try {
     const replayed = answerProvider ? (await replayExactMatch({ prompt, collections, userId, streamCallback, method: "custom-exact-match", startTime: Date.now() }))?.response : void 0;
@@ -19531,6 +19564,7 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
       userConfig,
       conversationHistory,
       onStream: streamCallback,
+      onNarration: narrationCallback,
       signal: abortController.signal
     }) : await get_agent_user_response(
       prompt,
@@ -19556,6 +19590,9 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
     inFlightAborts.delete(existingUiBlockId);
   }
   logger.info("User prompt request completed");
+  const narration = userResponse?.data?.narration;
+  if (Array.isArray(narration) && narration.length) uiBlock.setNarration(narration);
+  uiBlock.setDurationMs(Date.now() - requestStartTime);
   const uiBlockId = existingUiBlockId;
   const wasAborted = abortController.signal.aborted || !userResponse.success && Array.isArray(userResponse.errors) && userResponse.errors.includes("aborted");
   if (wasAborted) {

package/dist/index.mjs

@@ -1213,6 +1213,20 @@ var UIBlock = class {
   setTextResponse(textResponse) {
     this.textResponse = textResponse;
   }
+  /**
+   * Progress updates a narrator wrote while this answer was being produced,
+   * in order. Not part of the answer text: kept beside it so it is saved with
+   * the answer it describes, and can be shown or left out on its own.
+   */
+  setNarration(updates) {
+    this.narration = updates && updates.length ? updates : null;
+  }
+  getNarration() {
+    return this.narration ?? null;
+  }
+  setDurationMs(ms) {
+    this.durationMs = typeof ms === "number" && Number.isFinite(ms) && ms >= 0 ? Math.round(ms) : null;
+  }
   /**
    * Bind this block to the script recipe that produced its answer.
    */
@@ -1250,7 +1264,9 @@ var UIBlock = class {
       textResponse: this.textResponse,
       createdAt: this.createdAt.toISOString(),
       ...this.scriptBinding ? { scriptBinding: this.scriptBinding } : {},
-      ...this.programAnswer ? { programAnswer: this.programAnswer } : {}
+      ...this.programAnswer ? { programAnswer: this.programAnswer } : {},
+      ...this.narration ? { narration: this.narration } : {},
+      ...this.durationMs != null ? { durationMs: this.durationMs } : {}
     };
   }
 };
@@ -19104,7 +19120,10 @@ function transformUIBlockForDB(uiblock, userPrompt, uiBlockId) {
     ...uiblock?.scriptBinding?.recipeId ? { scriptBinding: uiblock.scriptBinding } : {},
     // The program-generated half, stored verbatim so a reload can regenerate
     // just that portion of `analysis` and leave the narration alone.
-    ...uiblock?.programAnswer ? { programAnswer: uiblock.programAnswer } : {}
+    ...uiblock?.programAnswer ? { programAnswer: uiblock.programAnswer } : {},
+    // Beside the answer, not in it: `analysis` stays the answer text alone.
+    ...Array.isArray(uiblock?.narration) && uiblock.narration.length ? { narration: uiblock.narration } : {},
+    ...typeof uiblock?.durationMs === "number" ? { durationMs: uiblock.durationMs } : {}
   };
 }
 function hasTraceContent(trace) {
@@ -19412,6 +19431,20 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
       }
     };
   }
+  let narrationSeq = 0;
+  const narrationCallback = (update) => {
+    try {
+      sendMessage({
+        id: `narration_${existingUiBlockId}`,
+        type: "USER_PROMPT_NARRATION",
+        from: { type: "data-agent" },
+        to: { type: "runtime", id: wsId },
+        payload: { uiBlockId: existingUiBlockId, threadId, seq: narrationSeq++, ...update }
+      });
+    } catch (err) {
+      logger.warn(`[UserPromptRequest] Narration send failed (WebSocket may be closed): ${err instanceof Error ? err.message : String(err)}`);
+    }
+  };
   let userResponse;
   try {
     const replayed = answerProvider ? (await replayExactMatch({ prompt, collections, userId, streamCallback, method: "custom-exact-match", startTime: Date.now() }))?.response : void 0;
@@ -19425,6 +19458,7 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
       userConfig,
       conversationHistory,
       onStream: streamCallback,
+      onNarration: narrationCallback,
       signal: abortController.signal
     }) : await get_agent_user_response(
       prompt,
@@ -19450,6 +19484,9 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
     inFlightAborts.delete(existingUiBlockId);
   }
   logger.info("User prompt request completed");
+  const narration = userResponse?.data?.narration;
+  if (Array.isArray(narration) && narration.length) uiBlock.setNarration(narration);
+  uiBlock.setDurationMs(Date.now() - requestStartTime);
   const uiBlockId = existingUiBlockId;
   const wasAborted = abortController.signal.aborted || !userResponse.success && Array.isArray(userResponse.errors) && userResponse.errors.includes("aborted");
   if (wasAborted) {

package/package.json

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