@superatomai/sdk-node 0.0.70-dsp → 0.0.71-dsp

package/dist/index.d.mts

@@ -1909,6 +1909,32 @@ declare const IncomingMessageSchema: z.ZodObject<{
     payload?: unknown;
 }>;
 type IncomingMessage = z.infer<typeof IncomingMessageSchema>;
+/**
+ * A file attached to a question. Synced with sdk-web: PromptAttachmentSchema.
+ *
+ * The file itself is in R2 (uploaded through sa-api's /upload/chat-attachment
+ * routes); the message carries only its reference. The host backend fetches it
+ * with /upload/chat-attachment/signed-get.
+ */
+declare const PromptAttachmentSchema: z.ZodObject<{
+    /** The R2 object key. */
+    key: z.ZodString;
+    fileName: z.ZodString;
+    /** Size in bytes. */
+    size: z.ZodNumber;
+    contentType: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    key: string;
+    fileName: string;
+    size: number;
+    contentType?: string | undefined;
+}, {
+    key: string;
+    fileName: string;
+    size: number;
+    contentType?: string | undefined;
+}>;
+type PromptAttachment = z.infer<typeof PromptAttachmentSchema>;
 declare const ComponentSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
@@ -2172,6 +2198,8 @@ interface AnswerProviderContext {
     signal?: AbortSignal;
     /** Where the question was asked from, when the client said. */
     context?: PromptContext;
+    /** Files attached to this question (R2 references). Absent when none. */
+    attachments?: PromptAttachment[];
 }
 /**
  * One narrator tick while an answer was being produced: what the narrator was
@@ -6628,4 +6656,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 AnalyticsEventType, type AnalyticsStatus, 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, INSTRUCTIONS_FILE, 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 PiSessionListener, type PiSessionState, type PiTranscriptEntry, type Principal, type PromptContext, 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 ShimDef, type ShimSummary, type ShimTarget, 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, analyticsClient, answerCatalogForBinding, answerComponents, anthropicLLM, assertReadOnlySql, bindContext, bridgePreamble, captureContext, clearContextTokens, contextTokenCount, createCodexSession, createCodingAgentSession, dashboardConversationHistory, dataFingerprint, describeContext, describeTriggers, emitAgentEvent, extractNamedExport, formatFindingsForAgent, geminiLLM, getCodingAgent, getCodingAgentsConfig, getPiSessionState, getRequestContext, groqLLM, hybridRerank, inferColumns, isUserContext, listCodingAgents, llmUsageLogger, logger, makeFmt, mintContextToken, normalizeScriptBody, onAgentRun, onPiSessionUpdate, openaiLLM, policiesFromConfig, projectForDatasetBinding, promptLoader, queryCache, registerCodingAgentCollection, registerCodingAgents, registerDashboardAgentCollection, requireRequestContext, rerankChromaResults, rerankConversationResults, resolveContextToken, resolveScriptRecipeStore, revokeContextToken, runAsSystem, runAsUser, runCodingAgent, runScript, runWithContext, runWithMessageIdentity, startAgentTriggers, stopAgentTriggers, userPromptErrorLogger, validateComponentSpec, withCapturedContext, writeBridgeShims, writeShims };
+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 AnalyticsEventType, type AnalyticsStatus, 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, INSTRUCTIONS_FILE, 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 PiSessionListener, type PiSessionState, type PiTranscriptEntry, type Principal, type PromptAttachment, type PromptContext, 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 ShimDef, type ShimSummary, type ShimTarget, 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, analyticsClient, answerCatalogForBinding, answerComponents, anthropicLLM, assertReadOnlySql, bindContext, bridgePreamble, captureContext, clearContextTokens, contextTokenCount, createCodexSession, createCodingAgentSession, dashboardConversationHistory, dataFingerprint, describeContext, describeTriggers, emitAgentEvent, extractNamedExport, formatFindingsForAgent, geminiLLM, getCodingAgent, getCodingAgentsConfig, getPiSessionState, getRequestContext, groqLLM, hybridRerank, inferColumns, isUserContext, listCodingAgents, llmUsageLogger, logger, makeFmt, mintContextToken, normalizeScriptBody, onAgentRun, onPiSessionUpdate, openaiLLM, policiesFromConfig, projectForDatasetBinding, promptLoader, queryCache, registerCodingAgentCollection, registerCodingAgents, registerDashboardAgentCollection, requireRequestContext, rerankChromaResults, rerankConversationResults, resolveContextToken, resolveScriptRecipeStore, revokeContextToken, runAsSystem, runAsUser, runCodingAgent, runScript, runWithContext, runWithMessageIdentity, startAgentTriggers, stopAgentTriggers, userPromptErrorLogger, validateComponentSpec, withCapturedContext, writeBridgeShims, writeShims };

package/dist/index.d.ts

@@ -1909,6 +1909,32 @@ declare const IncomingMessageSchema: z.ZodObject<{
     payload?: unknown;
 }>;
 type IncomingMessage = z.infer<typeof IncomingMessageSchema>;
+/**
+ * A file attached to a question. Synced with sdk-web: PromptAttachmentSchema.
+ *
+ * The file itself is in R2 (uploaded through sa-api's /upload/chat-attachment
+ * routes); the message carries only its reference. The host backend fetches it
+ * with /upload/chat-attachment/signed-get.
+ */
+declare const PromptAttachmentSchema: z.ZodObject<{
+    /** The R2 object key. */
+    key: z.ZodString;
+    fileName: z.ZodString;
+    /** Size in bytes. */
+    size: z.ZodNumber;
+    contentType: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    key: string;
+    fileName: string;
+    size: number;
+    contentType?: string | undefined;
+}, {
+    key: string;
+    fileName: string;
+    size: number;
+    contentType?: string | undefined;
+}>;
+type PromptAttachment = z.infer<typeof PromptAttachmentSchema>;
 declare const ComponentSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
@@ -2172,6 +2198,8 @@ interface AnswerProviderContext {
     signal?: AbortSignal;
     /** Where the question was asked from, when the client said. */
     context?: PromptContext;
+    /** Files attached to this question (R2 references). Absent when none. */
+    attachments?: PromptAttachment[];
 }
 /**
  * One narrator tick while an answer was being produced: what the narrator was
@@ -6628,4 +6656,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 AnalyticsEventType, type AnalyticsStatus, 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, INSTRUCTIONS_FILE, 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 PiSessionListener, type PiSessionState, type PiTranscriptEntry, type Principal, type PromptContext, 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 ShimDef, type ShimSummary, type ShimTarget, 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, analyticsClient, answerCatalogForBinding, answerComponents, anthropicLLM, assertReadOnlySql, bindContext, bridgePreamble, captureContext, clearContextTokens, contextTokenCount, createCodexSession, createCodingAgentSession, dashboardConversationHistory, dataFingerprint, describeContext, describeTriggers, emitAgentEvent, extractNamedExport, formatFindingsForAgent, geminiLLM, getCodingAgent, getCodingAgentsConfig, getPiSessionState, getRequestContext, groqLLM, hybridRerank, inferColumns, isUserContext, listCodingAgents, llmUsageLogger, logger, makeFmt, mintContextToken, normalizeScriptBody, onAgentRun, onPiSessionUpdate, openaiLLM, policiesFromConfig, projectForDatasetBinding, promptLoader, queryCache, registerCodingAgentCollection, registerCodingAgents, registerDashboardAgentCollection, requireRequestContext, rerankChromaResults, rerankConversationResults, resolveContextToken, resolveScriptRecipeStore, revokeContextToken, runAsSystem, runAsUser, runCodingAgent, runScript, runWithContext, runWithMessageIdentity, startAgentTriggers, stopAgentTriggers, userPromptErrorLogger, validateComponentSpec, withCapturedContext, writeBridgeShims, writeShims };
+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 AnalyticsEventType, type AnalyticsStatus, 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, INSTRUCTIONS_FILE, 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 PiSessionListener, type PiSessionState, type PiTranscriptEntry, type Principal, type PromptAttachment, type PromptContext, 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 ShimDef, type ShimSummary, type ShimTarget, 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, analyticsClient, answerCatalogForBinding, answerComponents, anthropicLLM, assertReadOnlySql, bindContext, bridgePreamble, captureContext, clearContextTokens, contextTokenCount, createCodexSession, createCodingAgentSession, dashboardConversationHistory, dataFingerprint, describeContext, describeTriggers, emitAgentEvent, extractNamedExport, formatFindingsForAgent, geminiLLM, getCodingAgent, getCodingAgentsConfig, getPiSessionState, getRequestContext, groqLLM, hybridRerank, inferColumns, isUserContext, listCodingAgents, llmUsageLogger, logger, makeFmt, mintContextToken, normalizeScriptBody, onAgentRun, onPiSessionUpdate, openaiLLM, policiesFromConfig, projectForDatasetBinding, promptLoader, queryCache, registerCodingAgentCollection, registerCodingAgents, registerDashboardAgentCollection, requireRequestContext, rerankChromaResults, rerankConversationResults, resolveContextToken, resolveScriptRecipeStore, revokeContextToken, runAsSystem, runAsUser, runCodingAgent, runScript, runWithContext, runWithMessageIdentity, startAgentTriggers, stopAgentTriggers, userPromptErrorLogger, validateComponentSpec, withCapturedContext, writeBridgeShims, writeShims };

package/dist/index.js

@@ -384,6 +384,16 @@ var AuthVerifyRequestMessageSchema = import_zod3.z.object({
   type: import_zod3.z.literal("AUTH_VERIFY_REQ"),
   payload: AuthVerifyRequestPayloadSchema
 });
+var MAX_PROMPT_ATTACHMENTS = 5;
+var MAX_PROMPT_ATTACHMENT_SIZE = 25 * 1024 * 1024;
+var PromptAttachmentSchema = import_zod3.z.object({
+  /** The R2 object key. */
+  key: import_zod3.z.string(),
+  fileName: import_zod3.z.string(),
+  /** Size in bytes. */
+  size: import_zod3.z.number().int().positive().max(MAX_PROMPT_ATTACHMENT_SIZE),
+  contentType: import_zod3.z.string().optional()
+});
 var UserPromptRequestPayloadSchema = import_zod3.z.object({
   prompt: import_zod3.z.string(),
   userId: import_zod3.z.string().optional(),
@@ -396,6 +406,10 @@ var UserPromptRequestPayloadSchema = import_zod3.z.object({
     uiBlockId: import_zod3.z.string()
   }).optional(),
   responseMode: import_zod3.z.enum(["component", "text"]).optional(),
+  /** The chat agent (sa-api app id) the question was asked to. */
+  agentId: import_zod3.z.string().optional(),
+  /** Files attached to this question, already uploaded to R2. */
+  attachments: import_zod3.z.array(PromptAttachmentSchema).max(MAX_PROMPT_ATTACHMENTS).optional(),
   /**
    * Where the question was asked from — e.g. the dashboard being viewed. See
    * `PromptContext`. Accepted as anything so a client sending an unexpected shape
@@ -19397,7 +19411,7 @@ function hasTraceContent(trace) {
   return (trace.kbNodes?.global?.length ?? 0) > 0 || (trace.kbNodes?.query?.length ?? 0) > 0 || (trace.schemaNodes?.routing?.length ?? 0) > 0 || (trace.schemaNodes?.preResolve?.length ?? 0) > 0 || !!trace.schemaNodes?.mainAgentCatalog || (trace.schemaNodes?.sourceAgentSchemas?.length ?? 0) > 0 || trace.script != null || trace.scriptMatcher != null || !!trace.entityResolution?.catalogText || (trace.entityResolution?.calls?.length ?? 0) > 0 || !!trace.conversationHistory || !!trace.userAccessContext || !!trace.userKbContext || !!trace.concepts?.catalogText || !!trace.concepts?.invariantsText || (trace.concepts?.calls?.length ?? 0) > 0 || (trace.directTools?.calls?.length ?? 0) > 0 || (trace.componentGen?.length ?? 0) > 0;
 }
 async function saveConversation(params) {
-  const { userId, userPrompt, uiblock, uiBlockId, threadId, collections, status = "success", error: turnError, trace } = params;
+  const { userId, userPrompt, uiblock, uiBlockId, threadId, collections, agentId, attachments, status = "success", error: turnError, trace } = params;
   if (!userId) {
     logger.warn("[CONVERSATION_SAVER] Skipping save: userId not provided");
     return {
@@ -19452,7 +19466,9 @@ async function saveConversation(params) {
       userPrompt,
       response: dbUIBlock,
       threadId,
-      status
+      status,
+      agentId,
+      ...attachments?.length ? { attachments } : {}
     });
     if (!saveResult?.success) {
       logger.warn(`[CONVERSATION_SAVER] Failed to save conversation to PostgreSQL: ${saveResult?.message || "Unknown error"}`);
@@ -19614,6 +19630,8 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
   const userId = payload.userId;
   const userConfig = payload.config;
   const SA_RUNTIME = payload.SA_RUNTIME;
+  const agentId = payload.agentId;
+  const attachments = payload.attachments?.length ? payload.attachments : void 0;
   const wsId = userPromptRequest.from.id || "unknown";
   const reported = (response) => ({
     model: response?.data?.model,
@@ -19730,7 +19748,7 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
   };
   let userResponse;
   try {
-    const replayed = answerProvider ? (await replayExactMatch({ prompt, collections, userId, streamCallback, method: "custom-exact-match", startTime: Date.now() }))?.response : void 0;
+    const replayed = answerProvider && !attachments ? (await replayExactMatch({ prompt, collections, userId, streamCallback, method: "custom-exact-match", startTime: Date.now() }))?.response : void 0;
     userResponse = replayed ? replayed : answerProvider ? await answerProvider({
       prompt,
       components,
@@ -19743,7 +19761,8 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
       onStream: streamCallback,
       onNarration: narrationCallback,
       signal: abortController.signal,
-      context: promptContextFrom(payload.context)
+      context: promptContextFrom(payload.context),
+      attachments
     }) : await get_agent_user_response(
       prompt,
       components,
@@ -19789,6 +19808,8 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
         uiBlockId,
         threadId,
         collections,
+        agentId,
+        attachments,
         status: "aborted",
         trace: userResponse.data?.trace
       });
@@ -19806,6 +19827,7 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
         type: "chat_agent",
         userId,
         projectId: process.env.SUPERATOM_PROJECT_ID || "",
+        appId: agentId,
         threadId,
         messageIndex: 0,
         question: prompt,
@@ -19855,6 +19877,8 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
         uiBlockId,
         threadId,
         collections,
+        agentId,
+        attachments,
         status: "error",
         // The raw errors array, not the joined string below — that string
         // is only for sa-api's plain-text analytics column.
@@ -19875,6 +19899,7 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
         type: "chat_agent",
         userId,
         projectId: process.env.SUPERATOM_PROJECT_ID || "",
+        appId: agentId,
         threadId,
         messageIndex: 0,
         question: prompt,
@@ -19945,6 +19970,7 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
       if (isNoDataAnswer) {
         logger.info(`[UserPromptRequest] No tools executed \u2014 saving as status='general' (not replayable from cache)`);
       }
+      const notReplayable = isNoDataAnswer || !!attachments;
       const saveResult = await saveConversation({
         userId,
         userPrompt: prompt,
@@ -19952,7 +19978,9 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
         uiBlockId,
         threadId,
         collections,
-        ...isNoDataAnswer ? { status: "general" } : {},
+        agentId,
+        attachments,
+        ...notReplayable ? { status: "general" } : {},
         trace: userResponse.data?.trace
       });
       if (saveResult.success) {
@@ -19992,6 +20020,7 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
       type: "chat_agent",
       userId,
       projectId: process.env.SUPERATOM_PROJECT_ID || "",
+      appId: agentId,
       threadId,
       messageIndex: thread.getUIBlockCount(),
       question: prompt,

package/dist/index.mjs

@@ -271,6 +271,16 @@ var AuthVerifyRequestMessageSchema = z3.object({
   type: z3.literal("AUTH_VERIFY_REQ"),
   payload: AuthVerifyRequestPayloadSchema
 });
+var MAX_PROMPT_ATTACHMENTS = 5;
+var MAX_PROMPT_ATTACHMENT_SIZE = 25 * 1024 * 1024;
+var PromptAttachmentSchema = z3.object({
+  /** The R2 object key. */
+  key: z3.string(),
+  fileName: z3.string(),
+  /** Size in bytes. */
+  size: z3.number().int().positive().max(MAX_PROMPT_ATTACHMENT_SIZE),
+  contentType: z3.string().optional()
+});
 var UserPromptRequestPayloadSchema = z3.object({
   prompt: z3.string(),
   userId: z3.string().optional(),
@@ -283,6 +293,10 @@ var UserPromptRequestPayloadSchema = z3.object({
     uiBlockId: z3.string()
   }).optional(),
   responseMode: z3.enum(["component", "text"]).optional(),
+  /** The chat agent (sa-api app id) the question was asked to. */
+  agentId: z3.string().optional(),
+  /** Files attached to this question, already uploaded to R2. */
+  attachments: z3.array(PromptAttachmentSchema).max(MAX_PROMPT_ATTACHMENTS).optional(),
   /**
    * Where the question was asked from — e.g. the dashboard being viewed. See
    * `PromptContext`. Accepted as anything so a client sending an unexpected shape
@@ -19284,7 +19298,7 @@ function hasTraceContent(trace) {
   return (trace.kbNodes?.global?.length ?? 0) > 0 || (trace.kbNodes?.query?.length ?? 0) > 0 || (trace.schemaNodes?.routing?.length ?? 0) > 0 || (trace.schemaNodes?.preResolve?.length ?? 0) > 0 || !!trace.schemaNodes?.mainAgentCatalog || (trace.schemaNodes?.sourceAgentSchemas?.length ?? 0) > 0 || trace.script != null || trace.scriptMatcher != null || !!trace.entityResolution?.catalogText || (trace.entityResolution?.calls?.length ?? 0) > 0 || !!trace.conversationHistory || !!trace.userAccessContext || !!trace.userKbContext || !!trace.concepts?.catalogText || !!trace.concepts?.invariantsText || (trace.concepts?.calls?.length ?? 0) > 0 || (trace.directTools?.calls?.length ?? 0) > 0 || (trace.componentGen?.length ?? 0) > 0;
 }
 async function saveConversation(params) {
-  const { userId, userPrompt, uiblock, uiBlockId, threadId, collections, status = "success", error: turnError, trace } = params;
+  const { userId, userPrompt, uiblock, uiBlockId, threadId, collections, agentId, attachments, status = "success", error: turnError, trace } = params;
   if (!userId) {
     logger.warn("[CONVERSATION_SAVER] Skipping save: userId not provided");
     return {
@@ -19339,7 +19353,9 @@ async function saveConversation(params) {
       userPrompt,
       response: dbUIBlock,
       threadId,
-      status
+      status,
+      agentId,
+      ...attachments?.length ? { attachments } : {}
     });
     if (!saveResult?.success) {
       logger.warn(`[CONVERSATION_SAVER] Failed to save conversation to PostgreSQL: ${saveResult?.message || "Unknown error"}`);
@@ -19501,6 +19517,8 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
   const userId = payload.userId;
   const userConfig = payload.config;
   const SA_RUNTIME = payload.SA_RUNTIME;
+  const agentId = payload.agentId;
+  const attachments = payload.attachments?.length ? payload.attachments : void 0;
   const wsId = userPromptRequest.from.id || "unknown";
   const reported = (response) => ({
     model: response?.data?.model,
@@ -19617,7 +19635,7 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
   };
   let userResponse;
   try {
-    const replayed = answerProvider ? (await replayExactMatch({ prompt, collections, userId, streamCallback, method: "custom-exact-match", startTime: Date.now() }))?.response : void 0;
+    const replayed = answerProvider && !attachments ? (await replayExactMatch({ prompt, collections, userId, streamCallback, method: "custom-exact-match", startTime: Date.now() }))?.response : void 0;
     userResponse = replayed ? replayed : answerProvider ? await answerProvider({
       prompt,
       components,
@@ -19630,7 +19648,8 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
       onStream: streamCallback,
       onNarration: narrationCallback,
       signal: abortController.signal,
-      context: promptContextFrom(payload.context)
+      context: promptContextFrom(payload.context),
+      attachments
     }) : await get_agent_user_response(
       prompt,
       components,
@@ -19676,6 +19695,8 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
         uiBlockId,
         threadId,
         collections,
+        agentId,
+        attachments,
         status: "aborted",
         trace: userResponse.data?.trace
       });
@@ -19693,6 +19714,7 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
         type: "chat_agent",
         userId,
         projectId: process.env.SUPERATOM_PROJECT_ID || "",
+        appId: agentId,
         threadId,
         messageIndex: 0,
         question: prompt,
@@ -19742,6 +19764,8 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
         uiBlockId,
         threadId,
         collections,
+        agentId,
+        attachments,
         status: "error",
         // The raw errors array, not the joined string below — that string
         // is only for sa-api's plain-text analytics column.
@@ -19762,6 +19786,7 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
         type: "chat_agent",
         userId,
         projectId: process.env.SUPERATOM_PROJECT_ID || "",
+        appId: agentId,
         threadId,
         messageIndex: 0,
         question: prompt,
@@ -19832,6 +19857,7 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
       if (isNoDataAnswer) {
         logger.info(`[UserPromptRequest] No tools executed \u2014 saving as status='general' (not replayable from cache)`);
       }
+      const notReplayable = isNoDataAnswer || !!attachments;
       const saveResult = await saveConversation({
         userId,
         userPrompt: prompt,
@@ -19839,7 +19865,9 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
         uiBlockId,
         threadId,
         collections,
-        ...isNoDataAnswer ? { status: "general" } : {},
+        agentId,
+        attachments,
+        ...notReplayable ? { status: "general" } : {},
         trace: userResponse.data?.trace
       });
       if (saveResult.success) {
@@ -19879,6 +19907,7 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
       type: "chat_agent",
       userId,
       projectId: process.env.SUPERATOM_PROJECT_ID || "",
+      appId: agentId,
       threadId,
       messageIndex: thread.getUIBlockCount(),
       question: prompt,

package/package.json

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