@superatomai/sdk-node 0.0.42-mds → 0.0.43-mds

package/dist/index.d.mts

@@ -777,6 +777,14 @@ declare const ToolSchema: z.ZodObject<{
             description: string;
         }[];
     }>>;
+    /** Cache policy. `false` = never cache (live data, write ops). Mirrors HTTP `Cache-Control: no-store`. */
+    cache: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<false>, z.ZodObject<{
+        ttlMs: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        ttlMs?: number | undefined;
+    }, {
+        ttlMs?: number | undefined;
+    }>]>>;
 }, "strip", z.ZodTypeAny, {
     id: string;
     params: Record<string, string>;
@@ -793,6 +801,9 @@ declare const ToolSchema: z.ZodObject<{
             description: string;
         }[];
     } | undefined;
+    cache?: false | {
+        ttlMs?: number | undefined;
+    } | undefined;
 }, {
     id: string;
     params: Record<string, string>;
@@ -809,6 +820,9 @@ declare const ToolSchema: z.ZodObject<{
             description: string;
         }[];
     } | undefined;
+    cache?: false | {
+        ttlMs?: number | undefined;
+    } | undefined;
 }>;
 type Tool$1 = z.infer<typeof ToolSchema>;
 type CollectionOperation = 'getMany' | 'getOne' | 'query' | 'mutation' | 'updateOne' | 'deleteOne' | 'createOne';

package/dist/index.d.ts

@@ -777,6 +777,14 @@ declare const ToolSchema: z.ZodObject<{
             description: string;
         }[];
     }>>;
+    /** Cache policy. `false` = never cache (live data, write ops). Mirrors HTTP `Cache-Control: no-store`. */
+    cache: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<false>, z.ZodObject<{
+        ttlMs: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        ttlMs?: number | undefined;
+    }, {
+        ttlMs?: number | undefined;
+    }>]>>;
 }, "strip", z.ZodTypeAny, {
     id: string;
     params: Record<string, string>;
@@ -793,6 +801,9 @@ declare const ToolSchema: z.ZodObject<{
             description: string;
         }[];
     } | undefined;
+    cache?: false | {
+        ttlMs?: number | undefined;
+    } | undefined;
 }, {
     id: string;
     params: Record<string, string>;
@@ -809,6 +820,9 @@ declare const ToolSchema: z.ZodObject<{
             description: string;
         }[];
     } | undefined;
+    cache?: false | {
+        ttlMs?: number | undefined;
+    } | undefined;
 }>;
 type Tool$1 = z.infer<typeof ToolSchema>;
 type CollectionOperation = 'getMany' | 'getOne' | 'query' | 'mutation' | 'updateOne' | 'deleteOne' | 'createOne';

package/dist/index.js

@@ -420,8 +420,10 @@ var ToolSchema = import_zod3.z.object({
   fullSchema: import_zod3.z.string().optional(),
   params: import_zod3.z.record(import_zod3.z.string()),
   fn: import_zod3.z.function().args(import_zod3.z.any()).returns(import_zod3.z.any()),
-  outputSchema: OutputSchema.optional()
+  outputSchema: OutputSchema.optional(),
   // Optional: describes the data structure returned by this tool
+  /** Cache policy. `false` = never cache (live data, write ops). Mirrors HTTP `Cache-Control: no-store`. */
+  cache: import_zod3.z.union([import_zod3.z.literal(false), import_zod3.z.object({ ttlMs: import_zod3.z.number().optional() })]).optional()
 });
 var UserQueryFiltersSchema = import_zod3.z.object({
   username: import_zod3.z.string().optional(),
@@ -2081,6 +2083,21 @@ function formatResultAsString(formattedResult) {
   return JSON.stringify(formattedResult, null, 2);
 }
 
+// src/utils/cache-key.ts
+function stableStringify(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return "[" + value.map(stableStringify).join(",") + "]";
+  }
+  const keys = Object.keys(value).sort();
+  return "{" + keys.map((k) => JSON.stringify(k) + ":" + stableStringify(value[k])).join(",") + "}";
+}
+function buildDirectToolCacheKey(toolId, parameters) {
+  return `et-direct:${toolId}:${stableStringify(parameters || {})}`;
+}
+
 // src/handlers/data-request.ts
 function getQueryCacheKey(query) {
   if (typeof query === "string") {
@@ -2094,16 +2111,6 @@ function getQueryCacheKey(query) {
   }
   return "";
 }
-function stableStringify(value) {
-  if (value === null || typeof value !== "object") {
-    return JSON.stringify(value);
-  }
-  if (Array.isArray(value)) {
-    return "[" + value.map(stableStringify).join(",") + "]";
-  }
-  const keys = Object.keys(value).sort();
-  return "{" + keys.map((k) => JSON.stringify(k) + ":" + stableStringify(value[k])).join(",") + "}";
-}
 function getCacheKey(collection, op, params, tools) {
   if (collection === "database" && op === "execute" && params?.sql) {
     return getQueryCacheKey(params.sql);
@@ -14580,17 +14587,45 @@ function formatComponentsForPrompt(components) {
    Props Structure: ${propsPreview}`;
   }).join("\n\n");
 }
+function classifyTool(tool) {
+  if (tool.toolType === "direct") return "direct";
+  if (tool.id.endsWith("_query")) return "sql";
+  if (tool.id.endsWith("_call")) return "rest";
+  if (tool.id.endsWith("_graphql")) return "graphql";
+  return "direct";
+}
 function formatToolsForPrompt(tools) {
   if (!tools || tools.length === 0) {
     return "No external tools available.";
   }
-  return tools.map((tool, idx) => {
+  const directTools = [];
+  const sourceTools = [];
+  for (const t of tools) {
+    (classifyTool(t) === "direct" ? directTools : sourceTools).push(t);
+  }
+  const renderTool = (tool, idx, label) => {
     const paramsStr = Object.entries(tool.params || {}).map(([key, type]) => `${key}: ${type}`).join(", ");
-    return `${idx + 1}. ID: ${tool.id}
+    return `${idx + 1}. [${label}] ID: ${tool.id}
    Name: ${tool.name}
    Description: ${tool.description}
    Parameters: { ${paramsStr} }`;
-  }).join("\n\n");
+  };
+  const sections = [];
+  if (directTools.length > 0) {
+    const body = directTools.map((t, i) => renderTool(t, i, "DIRECT \u2014 PREFER")).join("\n\n");
+    sections.push(`### Direct Tools (try these first \u2014 they answer most questions without SQL)
+${body}`);
+  }
+  if (sourceTools.length > 0) {
+    const body = sourceTools.map((t, i) => {
+      const kind = classifyTool(t);
+      const label = kind === "sql" ? "SQL" : kind === "rest" ? "REST" : "GRAPHQL";
+      return renderTool(t, i, label);
+    }).join("\n\n");
+    sections.push(`### Source Tools (fallback \u2014 use only when no direct tool fits)
+${body}`);
+  }
+  return sections.join("\n\n");
 }
 function formatExistingComponentsForPrompt(existingComponents) {
   if (!existingComponents || existingComponents.length === 0) {
@@ -15005,6 +15040,18 @@ Fixed SQL query:`;
       logger.info(`[DASH_COMP_REQ] Replaced direct query with queryId: ${queryId}`);
     }
     finalComponent = { ...finalComponent, props };
+    const ext = finalComponent.props?.externalTool;
+    if (ext?.toolId && !ext?.parameters?.sql) {
+      const matchedTool = tools?.find((t) => t.id === ext.toolId);
+      if (matchedTool && matchedTool.cache !== false) {
+        const match = executedTools.find((t) => t.id === ext.toolId);
+        if (match) {
+          const cacheKey = buildDirectToolCacheKey(ext.toolId, ext.parameters);
+          queryCache.set(cacheKey, { success: true, data: match.result });
+          logger.info(`[DASH_COMP_REQ] Pre-populated et-direct cache for ${ext.toolId}`);
+        }
+      }
+    }
     if (parsedResult.props.query) {
       logger.info(`[DASH_COMP_REQ] Data source: Database query`);
     }
@@ -15176,7 +15223,35 @@ async function createFilterWithLLM(prompt, components, existingComponents, anthr
     const updatedComponents = result.updatedComponents || [];
     for (const comp of updatedComponents) {
       const extTool = comp.props?.externalTool;
-      if (!extTool?.parameters?.sql || !extTool?.toolId) continue;
+      if (!extTool?.toolId) continue;
+      const isDirectTool = !extTool?.parameters?.sql;
+      if (isDirectTool) {
+        const directTool = tools?.find((t) => t.id === extTool.toolId);
+        if (!directTool) {
+          logger.warn(`[DASH_COMP_REQ:FILTER] direct tool ${extTool.toolId} not found in tool registry`);
+          continue;
+        }
+        const declared = new Set(Object.keys(directTool.params || {}));
+        const sentKeys = Object.keys(extTool.parameters || {});
+        const unknown = sentKeys.filter((k) => !declared.has(k));
+        if (unknown.length > 0) {
+          logger.warn(`[DASH_COMP_REQ:FILTER] dropping unknown params on ${extTool.toolId}: ${unknown.join(", ")}`);
+          unknown.forEach((k) => delete extTool.parameters[k]);
+        }
+        if (directTool.cache !== false) {
+          try {
+            const directResult = await directTool.fn(extTool.parameters || {});
+            const cacheKey2 = buildDirectToolCacheKey(extTool.toolId, extTool.parameters);
+            queryCache.set(cacheKey2, { success: true, data: directResult });
+            logger.info(`[DASH_COMP_REQ:FILTER] direct tool ${extTool.toolId} validated and cached for component: ${comp.id}`);
+          } catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            logger.warn(`[DASH_COMP_REQ:FILTER] direct tool validation failed for ${extTool.toolId} on component ${comp.id}: ${errMsg}`);
+          }
+        }
+        continue;
+      }
+      if (!extTool?.parameters?.sql) continue;
       let sql = extTool.parameters.sql;
       const defaultParams = extTool.parameters.params || {};
       const toolId = extTool.toolId;