@superatomai/sdk-node 0.0.61-dsp → 0.0.62-dsp

package/dist/index.js

@@ -3644,7 +3644,8 @@ var searchConversationsWithReranking = async (options) => {
 var findExactMatch = async ({
   userPrompt,
   collections,
-  userId
+  userId,
+  maxAgeHours
 }) => {
   try {
     if (!collections || !collections["conversation-history"] || !collections["conversation-history"]["exactMatch"]) {
@@ -3653,12 +3654,21 @@ var findExactMatch = async ({
     }
     const result = await collections["conversation-history"]["exactMatch"]({
       userPrompt,
-      userId
+      userId,
+      maxAgeHours
     });
     if (!result || !result.uiBlock) {
       logger.info("[ConversationSearch] No exact match found");
       return null;
     }
+    const createdAt = result.metadata?.createdAt;
+    if (maxAgeHours && maxAgeHours > 0 && createdAt) {
+      const ageHours = (Date.now() - new Date(createdAt).getTime()) / 36e5;
+      if (ageHours > maxAgeHours) {
+        logger.info(`[ConversationSearch] Exact match is ${ageHours.toFixed(1)}h old (limit ${maxAgeHours}h) \u2014 not replaying`);
+        return null;
+      }
+    }
     logger.info(`[ConversationSearch] \u2713 Exact prompt match found for "${userPrompt.substring(0, 50)}..."`);
     return result;
   } catch (error) {
@@ -18001,6 +18011,63 @@ function buildUserAccessContext(userConfig) {
   if (!anyRestriction && prompts.length === 0) return "";
   return [...restrictions, ...prompts].join("\n\n");
 }
+function replayMaxAgeHours() {
+  const raw = process.env.SA_ANSWER_REPLAY_MAX_AGE_HOURS;
+  const n = raw === void 0 || raw === "" ? 24 : Number(raw);
+  return Number.isFinite(n) && n >= 0 ? n : 24;
+}
+async function replayExactMatch(opts) {
+  const { prompt, collections, userId, streamCallback, method, startTime } = opts;
+  let directReplay;
+  const conversationMatch = await conversation_search_default.findExactMatch({
+    userPrompt: prompt,
+    collections,
+    userId,
+    maxAgeHours: replayMaxAgeHours()
+  });
+  if (conversationMatch) {
+    const rawComponent = conversationMatch.uiBlock?.component || conversationMatch.uiBlock?.generatedComponentMetadata;
+    const isValidComponent = rawComponent && typeof rawComponent === "object" && Object.keys(rawComponent).length > 0;
+    const component = isValidComponent ? rawComponent : null;
+    const cachedTextResponse = conversationMatch.uiBlock?.analysis || conversationMatch.uiBlock?.textResponse || conversationMatch.uiBlock?.text || "";
+    if (component && hasExpiredScriptDataset(component)) {
+      directReplay = extractBoundRecipe(component);
+      logger.info(
+        directReplay ? `[AgentFlow] Exact match w/ expired script_dataset \u2014 will re-run bound recipe ${directReplay.recipeId} directly (skip matcher LLM)` : `[AgentFlow] Exact match found but cached UIBlock has expired script_dataset \u2014 falling through to script matcher`
+      );
+    } else {
+      if (streamCallback && cachedTextResponse) {
+        streamCallback(cachedTextResponse);
+      }
+      const elapsedTime = Date.now() - startTime;
+      logger.info(`[AgentFlow] Exact match \u2014 returning cached result (${elapsedTime}ms)`);
+      const rehydratedComponent = component ? rehydrateCachedComponent(component) : null;
+      const storedBinding = conversationMatch.uiBlock?.scriptBinding;
+      const cachedBinding = storedBinding ? {
+        recipeId: storedBinding.recipeId,
+        params: storedBinding.params || {},
+        name: storedBinding.name || "",
+        columns: storedBinding.columns
+      } : (() => {
+        const bound = component ? extractBoundRecipe(component) : void 0;
+        return bound ? { recipeId: bound.recipeId, params: bound.params, name: "" } : void 0;
+      })();
+      return { response: {
+        success: true,
+        data: {
+          text: cachedTextResponse,
+          component: rehydratedComponent,
+          reasoning: `Exact match from previous conversation`,
+          method,
+          semanticSimilarity: 1,
+          ...cachedBinding ? { scriptBinding: cachedBinding } : {}
+        },
+        errors: []
+      } };
+    }
+  }
+  return directReplay ? { directReplay } : null;
+}
 var get_agent_user_response = async (prompt, components, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, conversationHistory, streamCallback, collections, externalTools, userId, mainAgentModel, sourceAgentModel, workflows, signal, activeBindings, userConfig) => {
   const startTime = Date.now();
   const providers = llmProviders || ["anthropic"];
@@ -18013,53 +18080,9 @@ var get_agent_user_response = async (prompt, components, anthropicApiKey, groqAp
   logger.logLLMPrompt("agentUserResponse", "user", `User Prompt: ${prompt}`);
   logger.info(`[AgentFlow] Starting | provider: ${provider} | prompt: "${prompt.substring(0, 50)}..."`);
   try {
-    let directReplay;
-    const conversationMatch = await conversation_search_default.findExactMatch({
-      userPrompt: prompt,
-      collections,
-      userId
-    });
-    if (conversationMatch) {
-      const rawComponent = conversationMatch.uiBlock?.component || conversationMatch.uiBlock?.generatedComponentMetadata;
-      const isValidComponent = rawComponent && typeof rawComponent === "object" && Object.keys(rawComponent).length > 0;
-      const component = isValidComponent ? rawComponent : null;
-      const cachedTextResponse = conversationMatch.uiBlock?.analysis || conversationMatch.uiBlock?.textResponse || conversationMatch.uiBlock?.text || "";
-      if (component && hasExpiredScriptDataset(component)) {
-        directReplay = extractBoundRecipe(component);
-        logger.info(
-          directReplay ? `[AgentFlow] Exact match w/ expired script_dataset \u2014 will re-run bound recipe ${directReplay.recipeId} directly (skip matcher LLM)` : `[AgentFlow] Exact match found but cached UIBlock has expired script_dataset \u2014 falling through to script matcher`
-        );
-      } else {
-        if (streamCallback && cachedTextResponse) {
-          streamCallback(cachedTextResponse);
-        }
-        const elapsedTime2 = Date.now() - startTime;
-        logger.info(`[AgentFlow] Exact match \u2014 returning cached result (${elapsedTime2}ms)`);
-        const rehydratedComponent = component ? rehydrateCachedComponent(component) : null;
-        const storedBinding = conversationMatch.uiBlock?.scriptBinding;
-        const cachedBinding = storedBinding ? {
-          recipeId: storedBinding.recipeId,
-          params: storedBinding.params || {},
-          name: storedBinding.name || "",
-          columns: storedBinding.columns
-        } : (() => {
-          const bound = component ? extractBoundRecipe(component) : void 0;
-          return bound ? { recipeId: bound.recipeId, params: bound.params, name: "" } : void 0;
-        })();
-        return {
-          success: true,
-          data: {
-            text: cachedTextResponse,
-            component: rehydratedComponent,
-            reasoning: `Exact match from previous conversation`,
-            method: `${provider}-agent-exact-match`,
-            semanticSimilarity: 1,
-            ...cachedBinding ? { scriptBinding: cachedBinding } : {}
-          },
-          errors: []
-        };
-      }
-    }
+    const cached = await replayExactMatch({ prompt, collections, userId, streamCallback, method: `${provider}-agent-exact-match`, startTime });
+    if (cached?.response) return cached.response;
+    const directReplay = cached?.directReplay;
     logger.info(`[AgentFlow] No exact match \u2014 proceeding with agent`);
     runTrace = createRunTrace();
     const apiKey = (() => {
@@ -19497,7 +19520,8 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
   }
   let userResponse;
   try {
-    userResponse = answerProvider ? await answerProvider({
+    const replayed = answerProvider ? (await replayExactMatch({ prompt, collections, userId, streamCallback, method: "custom-exact-match", startTime: Date.now() }))?.response : void 0;
+    userResponse = replayed ? replayed : answerProvider ? await answerProvider({
       prompt,
       components,
       collections,
@@ -24829,7 +24853,8 @@ fetch(BRIDGE + '/query', {
     // 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) }),
+  // ref: ask for a handle the deliverable can cite instead of copying rows.
+  body: JSON.stringify({ toolId, sql, limit: Math.min(Number(limitArg) || MAX_ROWS, MAX_ROWS), ref: true }),
 })
   .then(async (r) => {
     const text = await r.text();
@@ -24838,11 +24863,21 @@ fetch(BRIDGE + '/query', {
     if (p && p.error) { console.error(String(p.error)); process.exit(1); }
     const rows = (p && (p.data || p.rows)) || p;
     const all = Array.isArray(rows) ? rows : [rows];
+    // The source truncates before we see the rows and rewrites count to the
+    // truncated length; only metadata keeps the real total.
+    const meta = (p && p.metadata) || {};
+    const shown = all.slice(0, MAX_ROWS);
+    const total = meta.totalCount != null ? meta.totalCount : ((p && p.count) != null ? p.count : all.length);
+    const truncated = !!meta.truncated || all.length > MAX_ROWS || total > shown.length;
     // Capped so one careless SELECT * cannot flood the agent's context.
     console.log(JSON.stringify({
-      count: (p && p.count) != null ? p.count : all.length,
-      truncated: all.length > MAX_ROWS,
-      rows: all.slice(0, MAX_ROWS),
+      ...(p && p.ref ? { ref: p.ref } : {}),
+      count: total,
+      returned: shown.length,
+      truncated,
+      ...(truncated ? { warning: 'INCOMPLETE: only the first ' + shown.length + ' of ' + total + ' rows are shown. Do not compute totals, counts, shares or rankings from these rows; aggregate in SQL instead.' } : {}),
+      ...(meta.appliedPolicies && meta.appliedPolicies.length ? { restrictedBy: meta.appliedPolicies } : {}),
+      rows: shown,
     }, null, 2));
   })
   .catch((e) => { console.error('Could not reach the data bridge: ' + (e && e.message)); process.exit(1); });

package/dist/index.mjs

@@ -3538,7 +3538,8 @@ var searchConversationsWithReranking = async (options) => {
 var findExactMatch = async ({
   userPrompt,
   collections,
-  userId
+  userId,
+  maxAgeHours
 }) => {
   try {
     if (!collections || !collections["conversation-history"] || !collections["conversation-history"]["exactMatch"]) {
@@ -3547,12 +3548,21 @@ var findExactMatch = async ({
     }
     const result = await collections["conversation-history"]["exactMatch"]({
       userPrompt,
-      userId
+      userId,
+      maxAgeHours
     });
     if (!result || !result.uiBlock) {
       logger.info("[ConversationSearch] No exact match found");
       return null;
     }
+    const createdAt = result.metadata?.createdAt;
+    if (maxAgeHours && maxAgeHours > 0 && createdAt) {
+      const ageHours = (Date.now() - new Date(createdAt).getTime()) / 36e5;
+      if (ageHours > maxAgeHours) {
+        logger.info(`[ConversationSearch] Exact match is ${ageHours.toFixed(1)}h old (limit ${maxAgeHours}h) \u2014 not replaying`);
+        return null;
+      }
+    }
     logger.info(`[ConversationSearch] \u2713 Exact prompt match found for "${userPrompt.substring(0, 50)}..."`);
     return result;
   } catch (error) {
@@ -17895,6 +17905,63 @@ function buildUserAccessContext(userConfig) {
   if (!anyRestriction && prompts.length === 0) return "";
   return [...restrictions, ...prompts].join("\n\n");
 }
+function replayMaxAgeHours() {
+  const raw = process.env.SA_ANSWER_REPLAY_MAX_AGE_HOURS;
+  const n = raw === void 0 || raw === "" ? 24 : Number(raw);
+  return Number.isFinite(n) && n >= 0 ? n : 24;
+}
+async function replayExactMatch(opts) {
+  const { prompt, collections, userId, streamCallback, method, startTime } = opts;
+  let directReplay;
+  const conversationMatch = await conversation_search_default.findExactMatch({
+    userPrompt: prompt,
+    collections,
+    userId,
+    maxAgeHours: replayMaxAgeHours()
+  });
+  if (conversationMatch) {
+    const rawComponent = conversationMatch.uiBlock?.component || conversationMatch.uiBlock?.generatedComponentMetadata;
+    const isValidComponent = rawComponent && typeof rawComponent === "object" && Object.keys(rawComponent).length > 0;
+    const component = isValidComponent ? rawComponent : null;
+    const cachedTextResponse = conversationMatch.uiBlock?.analysis || conversationMatch.uiBlock?.textResponse || conversationMatch.uiBlock?.text || "";
+    if (component && hasExpiredScriptDataset(component)) {
+      directReplay = extractBoundRecipe(component);
+      logger.info(
+        directReplay ? `[AgentFlow] Exact match w/ expired script_dataset \u2014 will re-run bound recipe ${directReplay.recipeId} directly (skip matcher LLM)` : `[AgentFlow] Exact match found but cached UIBlock has expired script_dataset \u2014 falling through to script matcher`
+      );
+    } else {
+      if (streamCallback && cachedTextResponse) {
+        streamCallback(cachedTextResponse);
+      }
+      const elapsedTime = Date.now() - startTime;
+      logger.info(`[AgentFlow] Exact match \u2014 returning cached result (${elapsedTime}ms)`);
+      const rehydratedComponent = component ? rehydrateCachedComponent(component) : null;
+      const storedBinding = conversationMatch.uiBlock?.scriptBinding;
+      const cachedBinding = storedBinding ? {
+        recipeId: storedBinding.recipeId,
+        params: storedBinding.params || {},
+        name: storedBinding.name || "",
+        columns: storedBinding.columns
+      } : (() => {
+        const bound = component ? extractBoundRecipe(component) : void 0;
+        return bound ? { recipeId: bound.recipeId, params: bound.params, name: "" } : void 0;
+      })();
+      return { response: {
+        success: true,
+        data: {
+          text: cachedTextResponse,
+          component: rehydratedComponent,
+          reasoning: `Exact match from previous conversation`,
+          method,
+          semanticSimilarity: 1,
+          ...cachedBinding ? { scriptBinding: cachedBinding } : {}
+        },
+        errors: []
+      } };
+    }
+  }
+  return directReplay ? { directReplay } : null;
+}
 var get_agent_user_response = async (prompt, components, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, conversationHistory, streamCallback, collections, externalTools, userId, mainAgentModel, sourceAgentModel, workflows, signal, activeBindings, userConfig) => {
   const startTime = Date.now();
   const providers = llmProviders || ["anthropic"];
@@ -17907,53 +17974,9 @@ var get_agent_user_response = async (prompt, components, anthropicApiKey, groqAp
   logger.logLLMPrompt("agentUserResponse", "user", `User Prompt: ${prompt}`);
   logger.info(`[AgentFlow] Starting | provider: ${provider} | prompt: "${prompt.substring(0, 50)}..."`);
   try {
-    let directReplay;
-    const conversationMatch = await conversation_search_default.findExactMatch({
-      userPrompt: prompt,
-      collections,
-      userId
-    });
-    if (conversationMatch) {
-      const rawComponent = conversationMatch.uiBlock?.component || conversationMatch.uiBlock?.generatedComponentMetadata;
-      const isValidComponent = rawComponent && typeof rawComponent === "object" && Object.keys(rawComponent).length > 0;
-      const component = isValidComponent ? rawComponent : null;
-      const cachedTextResponse = conversationMatch.uiBlock?.analysis || conversationMatch.uiBlock?.textResponse || conversationMatch.uiBlock?.text || "";
-      if (component && hasExpiredScriptDataset(component)) {
-        directReplay = extractBoundRecipe(component);
-        logger.info(
-          directReplay ? `[AgentFlow] Exact match w/ expired script_dataset \u2014 will re-run bound recipe ${directReplay.recipeId} directly (skip matcher LLM)` : `[AgentFlow] Exact match found but cached UIBlock has expired script_dataset \u2014 falling through to script matcher`
-        );
-      } else {
-        if (streamCallback && cachedTextResponse) {
-          streamCallback(cachedTextResponse);
-        }
-        const elapsedTime2 = Date.now() - startTime;
-        logger.info(`[AgentFlow] Exact match \u2014 returning cached result (${elapsedTime2}ms)`);
-        const rehydratedComponent = component ? rehydrateCachedComponent(component) : null;
-        const storedBinding = conversationMatch.uiBlock?.scriptBinding;
-        const cachedBinding = storedBinding ? {
-          recipeId: storedBinding.recipeId,
-          params: storedBinding.params || {},
-          name: storedBinding.name || "",
-          columns: storedBinding.columns
-        } : (() => {
-          const bound = component ? extractBoundRecipe(component) : void 0;
-          return bound ? { recipeId: bound.recipeId, params: bound.params, name: "" } : void 0;
-        })();
-        return {
-          success: true,
-          data: {
-            text: cachedTextResponse,
-            component: rehydratedComponent,
-            reasoning: `Exact match from previous conversation`,
-            method: `${provider}-agent-exact-match`,
-            semanticSimilarity: 1,
-            ...cachedBinding ? { scriptBinding: cachedBinding } : {}
-          },
-          errors: []
-        };
-      }
-    }
+    const cached = await replayExactMatch({ prompt, collections, userId, streamCallback, method: `${provider}-agent-exact-match`, startTime });
+    if (cached?.response) return cached.response;
+    const directReplay = cached?.directReplay;
     logger.info(`[AgentFlow] No exact match \u2014 proceeding with agent`);
     runTrace = createRunTrace();
     const apiKey = (() => {
@@ -19391,7 +19414,8 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
   }
   let userResponse;
   try {
-    userResponse = answerProvider ? await answerProvider({
+    const replayed = answerProvider ? (await replayExactMatch({ prompt, collections, userId, streamCallback, method: "custom-exact-match", startTime: Date.now() }))?.response : void 0;
+    userResponse = replayed ? replayed : answerProvider ? await answerProvider({
       prompt,
       components,
       collections,
@@ -24723,7 +24747,8 @@ fetch(BRIDGE + '/query', {
     // 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) }),
+  // ref: ask for a handle the deliverable can cite instead of copying rows.
+  body: JSON.stringify({ toolId, sql, limit: Math.min(Number(limitArg) || MAX_ROWS, MAX_ROWS), ref: true }),
 })
   .then(async (r) => {
     const text = await r.text();
@@ -24732,11 +24757,21 @@ fetch(BRIDGE + '/query', {
     if (p && p.error) { console.error(String(p.error)); process.exit(1); }
     const rows = (p && (p.data || p.rows)) || p;
     const all = Array.isArray(rows) ? rows : [rows];
+    // The source truncates before we see the rows and rewrites count to the
+    // truncated length; only metadata keeps the real total.
+    const meta = (p && p.metadata) || {};
+    const shown = all.slice(0, MAX_ROWS);
+    const total = meta.totalCount != null ? meta.totalCount : ((p && p.count) != null ? p.count : all.length);
+    const truncated = !!meta.truncated || all.length > MAX_ROWS || total > shown.length;
     // Capped so one careless SELECT * cannot flood the agent's context.
     console.log(JSON.stringify({
-      count: (p && p.count) != null ? p.count : all.length,
-      truncated: all.length > MAX_ROWS,
-      rows: all.slice(0, MAX_ROWS),
+      ...(p && p.ref ? { ref: p.ref } : {}),
+      count: total,
+      returned: shown.length,
+      truncated,
+      ...(truncated ? { warning: 'INCOMPLETE: only the first ' + shown.length + ' of ' + total + ' rows are shown. Do not compute totals, counts, shares or rankings from these rows; aggregate in SQL instead.' } : {}),
+      ...(meta.appliedPolicies && meta.appliedPolicies.length ? { restrictedBy: meta.appliedPolicies } : {}),
+      rows: shown,
     }, null, 2));
   })
   .catch((e) => { console.error('Could not reach the data bridge: ' + (e && e.message)); process.exit(1); });

package/package.json

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