@superatomai/sdk-node 0.0.54-dsp → 0.0.55-dsp

package/dist/index.mjs

@@ -3582,7 +3582,8 @@ var getGlobalKnowledgeBase = async ({
 var getUserKnowledgeBase = async ({
   collections,
   userId,
-  limit = 100
+  limit = 100,
+  trace
 }) => {
   try {
     if (!userId) {
@@ -3602,6 +3603,13 @@ var getUserKnowledgeBase = async ({
       return "";
     }
     logger.info(`[KnowledgeBase] Retrieved ${result.count || 0} user knowledge base nodes for userId: ${userId}`);
+    if (trace) {
+      try {
+        trace.userKbContext = result.content;
+      } catch (traceErr) {
+        logger.warn(`[KnowledgeBase] Trace capture failed for user KB context (non-blocking): ${traceErr}`);
+      }
+    }
     return result.content;
   } catch (error) {
     const errorMsg = error instanceof Error ? error.message : String(error);
@@ -3618,7 +3626,7 @@ var getAllKnowledgeBase = async ({
 }) => {
   const [globalContext, userContext, queryContext] = await Promise.all([
     getGlobalKnowledgeBase({ collections, trace }),
-    getUserKnowledgeBase({ collections, userId }),
+    getUserKnowledgeBase({ collections, userId, trace }),
     getKnowledgeBase({ prompt, collections, topK, trace })
   ]);
   let combinedContext = "";
@@ -9912,6 +9920,11 @@ var SourceAgent = class {
       logger.logLLMPrompt(`sourceAgent:${this.tool.name}`, "system", extractPromptText(prompts.system));
       logger.logLLMPrompt(`sourceAgent:${this.tool.name}`, "user", prompts.user);
       const tools = this.buildToolDefinitions();
+      try {
+        if (this.traceSchemaEntry) this.traceSchemaEntry.toolsSent = tools;
+      } catch (traceErr) {
+        logger.warn(`[SourceAgent:${this.tool.name}] Trace capture failed for toolsSent (non-blocking): ${traceErr}`);
+      }
       let executedTool = null;
       let allExecutedTools = [];
       let resultData = [];
@@ -10103,6 +10116,18 @@ Analyze the error and try again with a corrected query.`;
       const extraSearches = hasSchemaSearch ? 2 : 0;
       const responseIterations = 1;
       const maxIterations = totalQueryAttempts * perQueryCost + extraSearches + responseIterations;
+      try {
+        if (this.traceSchemaEntry) {
+          this.traceSchemaEntry.callConfig = {
+            model: this.config.sourceAgentModel || void 0,
+            maxTokens: 2048,
+            temperature: 0,
+            maxIterations
+          };
+        }
+      } catch (traceErr) {
+        logger.warn(`[SourceAgent:${this.tool.name}] Trace capture failed for callConfig (non-blocking): ${traceErr}`);
+      }
       await LLM.streamWithTools(
         { sys: prompts.system, user: prompts.user },
         tools,
@@ -10220,6 +10245,11 @@ Analyze the error and try again with a corrected query.`;
       logger.warn(`[SourceAgent:${this.tool.name}] Trace capture failed for schema prompt (non-blocking): ${traceErr}`);
     }
     const databaseRules = await promptLoader.loadDatabaseRulesForType(sourceType);
+    try {
+      if (this.traceSchemaEntry) this.traceSchemaEntry.databaseRulesText = databaseRules;
+    } catch (traceErr) {
+      logger.warn(`[SourceAgent:${this.tool.name}] Trace capture failed for databaseRulesText (non-blocking): ${traceErr}`);
+    }
     const rowLimitSyntax = {
       "mssql": `Use SELECT TOP ${this.config.maxRowsFetched} in every SELECT statement`,
       "postgres": `Add LIMIT ${this.config.maxRowsFetched} at the end of every query`,
@@ -10231,6 +10261,11 @@ Analyze the error and try again with a corrected query.`;
       "netsuite": `Add LIMIT ${this.config.maxRowsFetched} at the end of every query (this tool converts it internally \u2014 SuiteQL itself has no LIMIT keyword, so never write FETCH FIRST/OFFSET/TOP yourself)`
     };
     const rowLimitInstruction = rowLimitSyntax[sourceType] || `Limit results to ${this.config.maxRowsFetched} rows`;
+    try {
+      if (this.traceSchemaEntry) this.traceSchemaEntry.rowLimitSyntaxText = rowLimitInstruction;
+    } catch (traceErr) {
+      logger.warn(`[SourceAgent:${this.tool.name}] Trace capture failed for rowLimitSyntaxText (non-blocking): ${traceErr}`);
+    }
     const hasSchemaSearch = !this.options.skipSchemaSearch && !!this.tool.schemaSearchFn;
     const schemaTier = this.tool.schemaTier || "";
     let schemaSearchInstructions = "";
@@ -10264,7 +10299,18 @@ This source has a large schema. The top tables are shown in detail above, but no
 Even if a table appears in the detailed schema above, search_schema returns sample values that help you write correct WHERE filters.
 **Never skip the search step \u2014 it prevents failed queries and retries.**`;
     }
+    try {
+      if (this.traceSchemaEntry) this.traceSchemaEntry.schemaSearchInstructionsText = schemaSearchInstructions;
+    } catch (traceErr) {
+      logger.warn(`[SourceAgent:${this.tool.name}] Trace capture failed for schemaSearchInstructionsText (non-blocking): ${traceErr}`);
+    }
     const displaySourceType = sourceType === "excel" || sourceType === "csv" ? `${sourceType} \u2014 uses DuckDB SQL engine` : sourceType;
+    const userAccessContextText = this.config.userAccessContext || "No user-specific access restrictions.";
+    try {
+      if (this.traceSchemaEntry) this.traceSchemaEntry.userAccessContextText = userAccessContextText;
+    } catch (traceErr) {
+      logger.warn(`[SourceAgent:${this.tool.name}] Trace capture failed for userAccessContextText (non-blocking): ${traceErr}`);
+    }
     const prompts = await promptLoader.loadPrompts("agent-source-query", {
       SOURCE_NAME: sourceName,
       SOURCE_TYPE: displaySourceType,
@@ -10282,7 +10328,7 @@ Even if a table appears in the detailed schema above, search_schema returns samp
       GLOBAL_KNOWLEDGE_BASE: this.config.globalKnowledgeBase || "No global knowledge base available.",
       CURRENT_DATETIME: getCurrentDateTimeForPrompt(),
       KNOWLEDGE_BASE_CONTEXT: this.config.knowledgeBaseContext || "No additional knowledge base context available.",
-      USER_ACCESS_CONTEXT: this.config.userAccessContext || "No user-specific access restrictions.",
+      USER_ACCESS_CONTEXT: userAccessContextText,
       INTENT: intent
     });
     return { system: prompts.system, user: prompts.user };
@@ -11480,7 +11526,7 @@ var WRITE_ANALYSIS_TOOL_DEF = {
     required: ["analysisBody"]
   }
 };
-var MAX_SCRIPT_ATTEMPTS = 3;
+var MAX_SCRIPT_ATTEMPTS = 8;
 var MAX_ANALYSIS_ATTEMPTS = 3;
 var MainAgent = class {
   constructor(externalTools, config2, scriptStore, turnId, streamBuffer, workflows = [], forkMode = false, editContext, componentCatalog = [], displayPreference) {
@@ -11596,6 +11642,16 @@ var MainAgent = class {
     } catch (traceErr) {
       logger.warn(`[MainAgent] Trace capture failed for entity catalog (non-blocking): ${traceErr}`);
     }
+    try {
+      if (this.config.trace) this.config.trace.concepts.catalogText = conceptCatalog.text ?? "";
+    } catch (traceErr) {
+      logger.warn(`[MainAgent] Trace capture failed for concept catalog (non-blocking): ${traceErr}`);
+    }
+    try {
+      if (this.config.trace) this.config.trace.concepts.invariantsText = conceptInvariants.text ?? "";
+    } catch (traceErr) {
+      logger.warn(`[MainAgent] Trace capture failed for concept invariants (non-blocking): ${traceErr}`);
+    }
     const systemPrompt = await this.buildSystemPrompt(
       summaries,
       directTools,
@@ -11621,9 +11677,15 @@ var MainAgent = class {
       // flow falls back to generateScriptComponents exactly as before.
       ...this.scriptingEnabled && this.componentCatalog.length > 0 ? [this.buildWriteComponentsToolDef()] : []
     ];
+    try {
+      if (this.config.trace) this.config.trace.toolsSent = tools;
+    } catch (traceErr) {
+      logger.warn(`[MainAgent] Trace capture failed for tools sent (non-blocking): ${traceErr}`);
+    }
     const sourceResults = [];
     const executedTools = [];
     let sourceCallCounter = 0;
+    const toolIdCallCounts = {};
     let selectedWorkflow;
     const toolHandler = async (toolName, toolInput) => {
       const workflow = this.workflows.find((w) => w.id === toolName);
@@ -11701,6 +11763,17 @@ var MainAgent = class {
         ...sourceInput,
         intent: sourceInput.intent + entityBlock + conceptBlock
       });
+      const callNumber = toolIdCallCounts[externalTool.id] = (toolIdCallCounts[externalTool.id] ?? 0) + 1;
+      if (callNumber > 1) {
+        const suffix = `#${callNumber}`;
+        result.sourceId = `${result.sourceId}${suffix}`;
+        if (result.executedTool) {
+          result.executedTool = { ...result.executedTool, id: `${result.executedTool.id}${suffix}` };
+        }
+        if (result.allExecutedTools && result.allExecutedTools.length > 0) {
+          result.allExecutedTools = result.allExecutedTools.map((t) => ({ ...t, id: `${t.id}${suffix}` }));
+        }
+      }
       sourceResults.push(result);
       if (result.success) {
         if (result.allExecutedTools && result.allExecutedTools.length > 0) {
@@ -11715,6 +11788,7 @@ var MainAgent = class {
         if (entry) {
           entry.result = formatted;
           if (this.resolvedConcepts.length) entry.resolvedConcepts = [...this.resolvedConcepts];
+          entry.aggregation = sourceInput.aggregation;
         }
       } catch (traceErr) {
         logger.warn(`[MainAgent] Trace capture failed for source result (non-blocking): ${traceErr}`);
@@ -11722,6 +11796,7 @@ var MainAgent = class {
       return formatted;
     };
     let text = "";
+    const firstIterationToolChoice = entitySearchActive ? { type: "tool", name: "resolve_entities" } : (this.forkMode || this.editMode) && this.scriptingEnabled ? { type: "any" } : void 0;
     try {
       text = await LLM.streamWithTools(
         {
@@ -11740,14 +11815,7 @@ var MainAgent = class {
           apiKey: apiKey || this.config.apiKey,
           partial: streamCallback,
           signal,
-          // PIN resolve_entities to iteration 1 in EVERY mode — edit and fork
-          // included. An optional tool reproduces the bug it exists to fix (the
-          // agent skipped resolution and hand-wrote `LIKE '%FDC%'`), and an edit
-          // like "same thing for Premier Energies" needs resolution just as much
-          // as a fresh ask does. It also satisfies what fork/edit used `any` for —
-          // a tool call on iteration 1 so the model cannot stop at a bare "I'll
-          // adapt…" preamble; iterations 2+ revert to auto so write_script follows.
-          ...entitySearchActive ? { firstIterationToolChoice: { type: "tool", name: "resolve_entities" } } : (this.forkMode || this.editMode) && this.scriptingEnabled ? { firstIterationToolChoice: { type: "any" } } : {}
+          ...firstIterationToolChoice ? { firstIterationToolChoice } : {}
         },
         this.config.maxIterations
       );
@@ -11901,6 +11969,11 @@ ${catalog}`,
   async handleWriteComponents(input) {
     const body = String(input?.componentsBody || "").trim();
     if (!body) return "write_components needs `componentsBody`.";
+    try {
+      if (this.config.trace) this.config.trace.writeComponentsBody = body;
+    } catch (traceErr) {
+      logger.warn(`[MainAgent] Trace capture failed for write_components body (non-blocking): ${traceErr}`);
+    }
     const result = this.scriptState.lastSuccessfulResult;
     if (!result) {
       return "write_components requires data: run write_script then execute_script successfully first.";
@@ -11987,6 +12060,11 @@ Now write your answer for the user. Do not restate the component list.`;
   async handleWriteAnalysis(input) {
     const body = String(input?.analysisBody || "").trim();
     if (!body) return "write_analysis needs `analysisBody`.";
+    try {
+      if (this.config.trace) this.config.trace.writeAnalysisBody = body;
+    } catch (traceErr) {
+      logger.warn(`[MainAgent] Trace capture failed for write_analysis body (non-blocking): ${traceErr}`);
+    }
     const verified = this.scriptState.lastSuccessfulResult;
     if (!verified) {
       return "No verified script result yet \u2014 call write_script then execute_script first, so the analysis is written against real data.";
@@ -12491,7 +12569,6 @@ ${r.body}`).join("\n\n");
    * whole answer down.
    */
   async handleResolveConcepts(toolInput) {
-    var _a;
     const fn = this.config.collections?.["concepts"]?.["resolve"];
     const names = Array.isArray(toolInput?.names) ? toolInput.names.filter(Boolean) : [];
     if (!fn) {
@@ -12530,8 +12607,16 @@ ${r.body}`).join("\n\n");
       };
       try {
         if (this.config.trace) {
-          (_a = this.config.trace).conceptResolution ?? (_a.conceptResolution = { calls: [] });
-          this.config.trace.conceptResolution.calls.push({ via: "resolve_concepts", asked: names, implied: res?.implied || [], ...seenByLLM });
+          this.config.trace.concepts.calls.push({
+            via: "resolve_concepts",
+            asked: names,
+            implied: res?.implied || [],
+            returned: seenByLLM.concepts,
+            ...corrected.length ? { corrected } : {},
+            ...suggestions.length ? { suggestions } : {},
+            unmatched: res?.unmatched || [],
+            note: notes.join(" ")
+          });
         }
       } catch (traceErr) {
         logger.warn(`[MainAgent] Trace capture failed for resolve_concepts (non-blocking): ${traceErr}`);
@@ -12574,7 +12659,6 @@ ${r.body}`).join("\n\n");
    * leave the agent exactly as it was, not take the whole answer down.
    */
   async handleResolveEntities(toolInput, userPrompt) {
-    var _a;
     const fn = this.config.collections?.["entity-search"]?.["resolveEntities"];
     const mentions = Array.isArray(toolInput?.mentions) ? toolInput.mentions.filter((m) => m?.text) : [];
     const entityTypes = Array.isArray(toolInput?.entityTypes) ? toolInput.entityTypes.filter(Boolean) : [];
@@ -12583,8 +12667,7 @@ ${r.body}`).join("\n\n");
     if (conceptTrace) {
       try {
         if (this.config.trace) {
-          (_a = this.config.trace).conceptResolution ?? (_a.conceptResolution = { calls: [] });
-          this.config.trace.conceptResolution.calls.push({ via: "resolve_entities", ...conceptTrace });
+          this.config.trace.concepts.calls.push({ via: "resolve_entities", ...conceptTrace });
         }
       } catch (traceErr) {
         logger.warn(`[MainAgent] Trace capture failed for concepts-in-resolve_entities (non-blocking): ${traceErr}`);
@@ -12851,6 +12934,11 @@ ${formatted}`;
   ${t.description || "No description"}${paramList ? "\n  Parameters:\n" + paramList : ""}`;
       }).join("\n\n");
     }
+    try {
+      if (this.config.trace) this.config.trace.directToolsText = directToolsText;
+    } catch (traceErr) {
+      logger.warn(`[MainAgent] Trace capture failed for direct tools text (non-blocking): ${traceErr}`);
+    }
     let workflowsText = "";
     if (workflows.length > 0) {
       workflowsText = workflows.map((w, idx) => {
@@ -12866,10 +12954,20 @@ ${propLines}` : ""
     } else {
       workflowsText = "No workflow components registered for this project.";
     }
+    try {
+      if (this.config.trace) this.config.trace.workflowsText = workflowsText;
+    } catch (traceErr) {
+      logger.warn(`[MainAgent] Trace capture failed for workflows text (non-blocking): ${traceErr}`);
+    }
     const scriptBodyContract = await promptLoader.loadScriptBodyContract({
       MAX_ROWS_RENDERED: String(MAX_ROWS_RENDERED),
       MAX_ROWS_FETCHED: String(MAX_ROWS_FETCHED)
     });
+    try {
+      if (this.config.trace) this.config.trace.scriptBodyContractText = scriptBodyContract;
+    } catch (traceErr) {
+      logger.warn(`[MainAgent] Trace capture failed for script body contract text (non-blocking): ${traceErr}`);
+    }
     const commonVars = {
       SOURCE_SUMMARIES: summariesText,
       DIRECT_TOOLS: directToolsText,
@@ -12893,6 +12991,20 @@ ${propLines}` : ""
     };
     if (this.editContext) {
       const ec = this.editContext;
+      try {
+        if (this.config.trace) {
+          this.config.trace.editContext = {
+            recipeId: ec.recipeId,
+            parentName: ec.parentName,
+            parentBody: ec.parentBody,
+            instruction: ec.instruction,
+            lastResultColumns: ec.lastResultColumns,
+            parentParams: ec.parentParams
+          };
+        }
+      } catch (traceErr) {
+        logger.warn(`[MainAgent] Trace capture failed for edit context (non-blocking): ${traceErr}`);
+      }
       const prompts2 = await promptLoader.loadPrompts("agent-main-edit", {
         ...commonVars,
         PARENT_SCRIPT_NAME: ec.parentName,
@@ -13167,7 +13279,9 @@ function createRunTrace() {
     schemaNodes: { routing: [], preResolve: [], sourceAgentSchemas: [] },
     script: null,
     scriptMatcher: null,
-    entityResolution: { calls: [] }
+    entityResolution: { calls: [] },
+    concepts: { calls: [] },
+    componentGen: []
   };
 }
 var DEFAULT_AGENT_CONFIG = {
@@ -13179,7 +13293,7 @@ var DEFAULT_AGENT_CONFIG = {
   // will use the provider's default model
   maxRetries: 2,
   // 2 retries = 3 total query attempts (1 initial + 2 retries for SQL errors)
-  maxIterations: 20
+  maxIterations: 30
   // schema search (2-3) + query attempts (2) + write_script/execute_script (2-3) + write_analysis (up to 3) + LLM responses + final
 };
 
@@ -14080,6 +14194,9 @@ var ScriptMatcher = class {
       );
       logger.logLLMPrompt("scriptMatcher", "system", extractPromptText(prompts.system));
       logger.logLLMPrompt("scriptMatcher", "user", extractPromptText(prompts.user));
+      traceEntry.sent.model = model || void 0;
+      traceEntry.sent.maxTokens = 500;
+      traceEntry.sent.temperature = 0;
       const response = await LLM.stream(
         { sys: prompts.system, user: prompts.user },
         {
@@ -14649,10 +14766,20 @@ async function buildScriptComponent(comp, ctx) {
   return { component, spec };
 }
 async function generateScriptComponents(params) {
-  const { userPrompt, scriptResult, queryIds, availableComponents, apiKey, model, componentStreamCallback, analysisText, analysisSummary, signal } = params;
+  const { userPrompt, scriptResult, queryIds, availableComponents, apiKey, model, componentStreamCallback, analysisText, analysisSummary, signal, trace } = params;
+  const traceEntry = { via: "generateScriptComponents" };
+  const pushTrace = () => {
+    if (!trace) return;
+    try {
+      trace.componentGen.push(traceEntry);
+    } catch (traceErr) {
+      logger.warn(`[ScriptComponentGen] Trace capture failed for generateScriptComponents (non-blocking): ${traceErr}`);
+    }
+  };
   const queries = scriptResult.executedQueries;
   if (!queries || queries.length === 0) {
     logger.warn(`[ScriptComponentGen] No query data available \u2014 returning empty`);
+    pushTrace();
     return { components: [], layoutTitle: "", layoutDescription: "", componentSpecs: [] };
   }
   logger.info(`[ScriptComponentGen] Starting | ${queries.length} queries | ${availableComponents.length} available components`);
@@ -14670,6 +14797,7 @@ async function generateScriptComponents(params) {
    Keywords: ${keywords}
    Props Structure: ${propsPreview}`;
   }).join("\n\n");
+  traceEntry.componentCatalog = availableCompsText;
   const sourceDescriptions = queries.map((q, idx) => {
     if (!q.data || q.data.length === 0) return null;
     const cols = columnsByIndex[idx];
@@ -14686,15 +14814,22 @@ async function generateScriptComponents(params) {
 ${sampleData}
 \`\`\``;
   }).filter(Boolean).join("\n\n");
+  traceEntry.columnDescriptions = sourceDescriptions;
   try {
+    const sourceNameValue = queries.map((q) => q.sourceName).join(", ");
+    const rowCountValue = queries.map((q) => `${q.sourceName}: ${Math.min(q.count, MAX_ROWS_RENDERED)}${q.count > MAX_ROWS_RENDERED ? ` of ${q.count}` : ""}`).join(", ");
+    const analysisTextValue = analysisText && analysisText.trim() ? analysisText.trim() : "No analysis text provided \u2014 infer intent from the user question and the returned data.";
+    traceEntry.sourceName = sourceNameValue;
+    traceEntry.rowCount = rowCountValue;
+    traceEntry.analysisText = analysisTextValue;
     const prompts = await promptLoader.loadPrompts("script-components", {
       USER_PROMPT: userPrompt,
       AVAILABLE_COMPONENTS: availableCompsText,
-      SOURCE_NAME: queries.map((q) => q.sourceName).join(", "),
-      ROW_COUNT: queries.map((q) => `${q.sourceName}: ${Math.min(q.count, MAX_ROWS_RENDERED)}${q.count > MAX_ROWS_RENDERED ? ` of ${q.count}` : ""}`).join(", "),
+      SOURCE_NAME: sourceNameValue,
+      ROW_COUNT: rowCountValue,
       COLUMN_DESCRIPTIONS: sourceDescriptions,
       SAMPLE_DATA: "",
-      ANALYSIS_TEXT: analysisText && analysisText.trim() ? analysisText.trim() : "No analysis text provided \u2014 infer intent from the user question and the returned data."
+      ANALYSIS_TEXT: analysisTextValue
     });
     const ctx = {
       queries,
@@ -14725,19 +14860,21 @@ ${sampleData}
     } : void 0;
     logger.logLLMPrompt("scriptComponentGen", "system", prompts.system);
     logger.logLLMPrompt("scriptComponentGen", "user", prompts.user);
+    const callConfig = { model: model || void 0, maxTokens: 5e3, temperature: 0 };
+    traceEntry.callConfig = callConfig;
     const response = await LLM.stream(
       { sys: prompts.system, user: prompts.user },
       {
-        model: model || void 0,
-        maxTokens: 5e3,
-        temperature: 0,
+        ...callConfig,
         apiKey,
         partial,
         signal
       },
       true
     );
-    logger.logLLMPrompt("scriptComponentGen:response", "user", JSON.stringify(response, null, 2));
+    const responseText = JSON.stringify(response, null, 2);
+    logger.logLLMPrompt("scriptComponentGen:response", "user", responseText);
+    traceEntry.rawResponse = responseText;
     if (!response || !response.components || !Array.isArray(response.components)) {
       logger.warn(`[ScriptComponentGen] LLM returned invalid response`);
       return { components: [], layoutTitle: "", layoutDescription: "", componentSpecs: [] };
@@ -14805,26 +14942,45 @@ ${sampleData}
     const msg = error instanceof Error ? error.message : String(error);
     logger.error(`[ScriptComponentGen] Failed: ${msg}`);
     return { components: [], layoutTitle: "", layoutDescription: "", componentSpecs: [] };
+  } finally {
+    pushTrace();
   }
 }
-async function summarizeToMarkdown(analysis, apiKey, model) {
-  if (!analysis || !analysis.trim()) return "";
+async function summarizeToMarkdown(analysis, apiKey, model, trace) {
+  const traceEntry = { via: "summarizeToMarkdown", analysisText: analysis };
+  const pushTrace = () => {
+    if (!trace) return;
+    try {
+      trace.componentGen.push(traceEntry);
+    } catch (traceErr) {
+      logger.warn(`[ScriptComponentGen] Trace capture failed for summarizeToMarkdown (non-blocking): ${traceErr}`);
+    }
+  };
+  if (!analysis || !analysis.trim()) {
+    pushTrace();
+    return "";
+  }
   try {
     const prompts = await promptLoader.loadPrompts("script-component-summary", { ANALYSIS_TEXT: analysis });
-    const text = await LLM.text({ sys: prompts.system, user: prompts.user }, { model: model || void 0, maxTokens: 400, temperature: 0, apiKey });
+    const callConfig = { model: model || void 0, maxTokens: 400, temperature: 0 };
+    traceEntry.callConfig = callConfig;
+    const text = await LLM.text({ sys: prompts.system, user: prompts.user }, { ...callConfig, apiKey });
+    traceEntry.rawResponse = text;
     return (text || "").trim();
   } catch (err) {
     logger.warn(`[ScriptComponentGen] summarizeToMarkdown failed, falling back: ${err instanceof Error ? err.message : String(err)}`);
     return "";
+  } finally {
+    pushTrace();
   }
 }
-async function markdownContent(analysisSummary, analysisText, apiKey, model) {
+async function markdownContent(analysisSummary, analysisText, apiKey, model, trace) {
   const bullets = (analysisSummary || []).map((b) => String(b).trim()).filter(Boolean);
   if (bullets.length) return bullets.map((b) => `- ${b}`).join("\n");
-  return await summarizeToMarkdown(analysisText || "", apiKey, model) || analysisText || "";
+  return await summarizeToMarkdown(analysisText || "", apiKey, model, trace) || analysisText || "";
 }
 async function assembleComponentsFromSpecs(params) {
-  const { specs, scriptResult, queryIds, availableComponents, componentStreamCallback, analysisText, analysisSummary, apiKey, model } = params;
+  const { specs, scriptResult, queryIds, availableComponents, componentStreamCallback, analysisText, analysisSummary, apiKey, model, trace } = params;
   if (!specs || specs.length === 0) return null;
   const queries = scriptResult.executedQueries || [];
   const byId = new Map(queries.map((q) => [q.sourceId, q]));
@@ -14850,7 +15006,7 @@ async function assembleComponentsFromSpecs(params) {
       return null;
     }
     if (spec.sourceRef === "markdown") {
-      const summary = await markdownContent(analysisSummary, analysisText, apiKey, model) || spec.content || "";
+      const summary = await markdownContent(analysisSummary, analysisText, apiKey, model, trace) || spec.content || "";
       const md = buildMarkdown(summary, spec.title, spec.description);
       if (md) {
         out.push(md);
@@ -14906,7 +15062,7 @@ async function assembleComponentsFromSpecs(params) {
     }
   }
   if (out.length > 0 && !out.some((c) => c.type === "MarkdownBlock")) {
-    const summary = await markdownContent(analysisSummary, analysisText, apiKey, model);
+    const summary = await markdownContent(analysisSummary, analysisText, apiKey, model, trace);
     const md = buildMarkdown(summary);
     if (md) {
       out.push(md);
@@ -14927,31 +15083,47 @@ async function authorComponentsProgram(params) {
     externalTools,
     apiKey,
     model,
-    signal
+    signal,
+    trace
   } = params;
   const maxAttempts = params.maxAttempts ?? 2;
-  const queries = scriptResult.executedQueries || [];
-  if (!queries.length) return null;
-  const datasets = {};
-  for (const q of queries) {
-    if (q.virtual && q.sourceId?.startsWith("computed:")) {
-      datasets[q.sourceId.slice("computed:".length)] = q.data;
+  const traceEntry = { via: "authorComponentsProgram", instruction, attempts: [] };
+  const pushTrace = () => {
+    if (!trace) return;
+    try {
+      trace.componentGen.push(traceEntry);
+    } catch (traceErr) {
+      logger.warn(`[ComponentsEdit] Trace capture failed for authorComponentsProgram (non-blocking): ${traceErr}`);
     }
-  }
-  const catalog = availableComponents.map((c) => {
-    const cfg = c.props?.config;
-    return `- ${c.name} (${c.type})${c.description ? ` \u2014 ${c.description}` : ""}` + (cfg ? `
+  };
+  try {
+    const queries = scriptResult.executedQueries || [];
+    if (!queries.length) return null;
+    const datasets = {};
+    for (const q of queries) {
+      if (q.virtual && q.sourceId?.startsWith("computed:")) {
+        datasets[q.sourceId.slice("computed:".length)] = q.data;
+      }
+    }
+    const catalog = availableComponents.map((c) => {
+      const cfg = c.props?.config;
+      return `- ${c.name} (${c.type})${c.description ? ` \u2014 ${c.description}` : ""}` + (cfg ? `
   config: ${JSON.stringify(cfg)}` : "");
-  }).join("\n");
-  const shapes = queries.map((q) => {
-    const cols = inferColumns(q.data);
-    const desc = [...cols.values()].map((c) => `${c.name}:${c.type}`).join(", ");
-    return `- ${q.sourceId} \u2014 ${q.count ?? q.data.length} rows [${desc}]`;
-  }).join("\n");
-  const current = stripToComponentsExport(recipe.scriptBody || "");
-  let feedback = "";
-  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    const sys = `You re-author ONE function: \`getComponents(data, params, fmt, datasets)\`, which RETURNS an array of component specs { componentType, sourceRef, title, description, config }.
+    }).join("\n");
+    traceEntry.componentCatalog = catalog;
+    const shapes = queries.map((q) => {
+      const cols = inferColumns(q.data);
+      const desc = [...cols.values()].map((c) => `${c.name}:${c.type}`).join(", ");
+      return `- ${q.sourceId} \u2014 ${q.count ?? q.data.length} rows [${desc}]`;
+    }).join("\n");
+    traceEntry.datasetShapes = shapes;
+    const current = stripToComponentsExport(recipe.scriptBody || "");
+    traceEntry.currentBody = current;
+    const callConfig = { model: model || void 0, maxTokens: 2e3, temperature: 0 };
+    traceEntry.callConfig = callConfig;
+    let feedback = "";
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      const sys = `You re-author ONE function: \`getComponents(data, params, fmt, datasets)\`, which RETURNS an array of component specs { componentType, sourceRef, title, description, config }.
 
 It re-runs on every replay, so build any figure in a title from \`datasets\`/\`fmt\` \u2014 never type one in. Bind each component to ONE \`sourceRef\` from the datasets below and select columns from it; never group, sum, or reshape, and never set an aggregation config.
 
@@ -14960,7 +15132,7 @@ ${shapes}
 
 ## Available components
 ${catalog}`;
-    const user = `Apply this rendering change: ${instruction}
+      const user = `Apply this rendering change: ${instruction}
 
 ` + (current ? `Current getComponents:
 \`\`\`js
@@ -14968,57 +15140,64 @@ ${current}
 \`\`\`
 
 Change ONLY what the instruction asks for; keep every other component and its text as-is.` : "There is no existing getComponents \u2014 author one that displays this result under the instruction above.") + feedback + "\n\nReply with the complete `export function getComponents(...) { ... }` and nothing else.";
-    let body;
-    try {
-      body = await LLM.stream({ sys, user }, { model, maxTokens: 2e3, temperature: 0, apiKey, signal });
-    } catch (err) {
-      logger.warn(`[ComponentsEdit] LLM call failed: ${err instanceof Error ? err.message : err}`);
-      return null;
-    }
-    body = body.replace(/^[\s\S]*?```(?:js|javascript|ts|typescript)?\n/, "").replace(/```[\s\S]*$/, "").trim();
-    if (!/export\s+(?:async\s+)?function\s+getComponents\b/.test(body)) {
-      feedback = `
+      const feedbackThisAttempt = feedback;
+      let body;
+      try {
+        body = await LLM.stream({ sys, user }, { ...callConfig, apiKey, signal });
+      } catch (err) {
+        logger.warn(`[ComponentsEdit] LLM call failed: ${err instanceof Error ? err.message : err}`);
+        traceEntry.attempts.push({ feedback: feedbackThisAttempt });
+        return null;
+      }
+      traceEntry.attempts.push({ feedback: feedbackThisAttempt, rawResponse: body });
+      traceEntry.rawResponse = body;
+      body = body.replace(/^[\s\S]*?```(?:js|javascript|ts|typescript)?\n/, "").replace(/```[\s\S]*$/, "").trim();
+      if (!/export\s+(?:async\s+)?function\s+getComponents\b/.test(body)) {
+        feedback = `
 
 Your previous reply did not contain \`export function getComponents\`.`;
-      continue;
-    }
-    if (!await scriptStore.attachComponents(recipe.id, body)) return null;
-    const { components, componentsError } = await runComponentsOnly(
-      recipe,
-      scriptStore.getScriptPath(recipe),
-      {},
-      scriptResult.data,
-      { externalTools, signal },
-      datasets
-    );
-    if (componentsError || !components?.length) {
-      feedback = `
+        continue;
+      }
+      if (!await scriptStore.attachComponents(recipe.id, body)) return null;
+      const { components, componentsError } = await runComponentsOnly(
+        recipe,
+        scriptStore.getScriptPath(recipe),
+        {},
+        scriptResult.data,
+        { externalTools, signal },
+        datasets
+      );
+      if (componentsError || !components?.length) {
+        feedback = `
 
 Your previous getComponents failed: ${componentsError || "it returned no components"}`;
-      continue;
-    }
-    const availableSourceRefs = queries.map((q) => q.sourceId);
-    const findings = [];
-    for (const spec of components) {
-      const q = queries.find((x) => x.sourceId === spec.sourceRef);
-      const rows = q?.data || [];
-      findings.push(...validateComponentSpec(
-        { ...spec, config: spec.config || {} },
-        { cols: inferColumns(rows), rowCount: rows.length, rows, availableSourceRefs }
-      ).filter((f) => f.severity === "error"));
-    }
-    if (findings.length) {
-      logger.warn(`[ComponentsEdit] attempt ${attempt} rejected: ${findings.length} finding(s)`);
-      feedback = `
+        continue;
+      }
+      const availableSourceRefs = queries.map((q) => q.sourceId);
+      const findings = [];
+      for (const spec of components) {
+        const q = queries.find((x) => x.sourceId === spec.sourceRef);
+        const rows = q?.data || [];
+        findings.push(...validateComponentSpec(
+          { ...spec, config: spec.config || {} },
+          { cols: inferColumns(rows), rowCount: rows.length, rows, availableSourceRefs }
+        ).filter((f) => f.severity === "error"));
+      }
+      if (findings.length) {
+        logger.warn(`[ComponentsEdit] attempt ${attempt} rejected: ${findings.length} finding(s)`);
+        feedback = `
 
 ${formatFindingsForAgent(findings)}`;
-      continue;
+        continue;
+      }
+      logger.info(`[ComponentsEdit] Re-authored getComponents for "${recipe.name}" (${components.length} component(s), attempt ${attempt})`);
+      return components;
     }
-    logger.info(`[ComponentsEdit] Re-authored getComponents for "${recipe.name}" (${components.length} component(s), attempt ${attempt})`);
-    return components;
+    logger.warn(`[ComponentsEdit] Gave up after ${maxAttempts} attempts \u2014 falling back to spec generation`);
+    return null;
+  } finally {
+    pushTrace();
   }
-  logger.warn(`[ComponentsEdit] Gave up after ${maxAttempts} attempts \u2014 falling back to spec generation`);
-  return null;
 }
 function stripToComponentsExport(body) {
   const m = body.search(/export\s+(?:async\s+)?function\s+getComponents\b/);
@@ -17485,7 +17664,8 @@ ${JSON.stringify(preview, null, 2)}
                   analysisText: scriptTextResponse,
                   analysisSummary: scriptResult?.analysis?.summary,
                   apiKey,
-                  model: sourceAgentModel
+                  model: sourceAgentModel,
+                  trace: runTrace
                 });
                 if (assembled && assembled.length > 0) {
                   matchedComponents2 = assembled;
@@ -17503,7 +17683,8 @@ ${JSON.stringify(preview, null, 2)}
                   externalTools: agentTools,
                   apiKey,
                   model: sourceAgentModel,
-                  signal
+                  signal,
+                  trace: runTrace
                 });
                 if (reauthored?.length) {
                   const assembled = await assembleComponentsFromSpecs({
@@ -17515,7 +17696,8 @@ ${JSON.stringify(preview, null, 2)}
                     analysisText: scriptTextResponse,
                     analysisSummary: scriptResult?.analysis?.summary,
                     apiKey,
-                    model: sourceAgentModel
+                    model: sourceAgentModel,
+                    trace: runTrace
                   });
                   if (assembled?.length) {
                     matchedComponents2 = assembled;
@@ -17556,7 +17738,8 @@ RENDERING REQUIREMENT (overrides the default choice of component): ${scriptMatch
                   collections,
                   analysisText: scriptTextResponse,
                   analysisSummary: scriptResult?.analysis?.summary,
-                  signal
+                  signal,
+                  trace: runTrace
                 });
                 if (compResult.components.length > 0) {
                   matchedComponents2 = compResult.components;
@@ -17696,6 +17879,18 @@ User question: ${prompt}
 ---
 
 BEGIN NOW. Your VERY FIRST action MUST be a \`write_script\` tool call containing the adapted getData() body, immediately followed by \`execute_script\`. Do NOT reply with prose, a plan, or "I'll adapt\u2026" first \u2014 that ends your turn with no script and produces a broken answer. Call \`write_script\` now.`;
+      if (runTrace) {
+        try {
+          runTrace.forkContext = {
+            ...runTrace.forkContext || {},
+            parentBody: forkContext.parentBody,
+            gaps: gapsBlock,
+            modificationHint: hintBlock
+          };
+        } catch (traceErr) {
+          logger.warn(`[AgentFlow] Trace capture failed for fork-mode preamble (non-blocking): ${traceErr}`);
+        }
+      }
     }
     let filteredTools = agentTools;
     const sqlToolCount = agentTools.filter((t) => t.toolType !== "direct").length;
@@ -17921,7 +18116,8 @@ BEGIN NOW. Your VERY FIRST action MUST be a \`write_script\` tool call containin
               analysisText: agentResponse.text,
               analysisSummary: agentResponse.analysis?.summary,
               apiKey,
-              model: sourceAgentModel
+              model: sourceAgentModel,
+              trace: runTrace
             });
             if (assembled && assembled.length > 0) {
               matchedComponents = assembled;
@@ -17948,7 +18144,8 @@ RENDERING REQUIREMENT (overrides the default choice of component): ${carriedRequ
             collections,
             analysisText: agentResponse.text,
             analysisSummary: agentResponse.analysis?.summary,
-            signal
+            signal,
+            trace: runTrace
           };
           const MAX_COMP_ATTEMPTS = 3;
           let compResult;
@@ -18104,6 +18301,18 @@ RENDERING REQUIREMENT (overrides the default choice of component): ${carriedRequ
           forkDepth: Math.min(FORK_DEPTH_CAP, forkContext.parentDepth + 1),
           forkReason: forkContext.modificationHint
         } : void 0;
+        if (runTrace && forkContext && lineage) {
+          try {
+            runTrace.forkContext = {
+              ...runTrace.forkContext || {},
+              parentRecipeId: lineage.parentId,
+              forkDepth: lineage.forkDepth,
+              forkReason: lineage.forkReason
+            };
+          } catch (traceErr) {
+            logger.warn(`[AgentFlow] Trace capture failed for fork lineage (non-blocking): ${traceErr}`);
+          }
+        }
         const promoted = await scriptStore.promoteToVerified(authored.recipeId, {
           sourceIds: authored.sourceIds,
           tables: authored.tables,
@@ -18296,7 +18505,7 @@ function transformUIBlockForDB(uiblock, userPrompt, uiBlockId) {
   };
 }
 function hasTraceContent(trace) {
-  return trace.kbNodes.global.length > 0 || trace.kbNodes.query.length > 0 || trace.schemaNodes.routing.length > 0 || trace.schemaNodes.preResolve.length > 0 || !!trace.schemaNodes.mainAgentCatalog || trace.schemaNodes.sourceAgentSchemas.length > 0 || trace.script != null || trace.scriptMatcher != null || !!trace.entityResolution.catalogText || trace.entityResolution.calls.length > 0 || !!trace.conversationHistory;
+  return trace.kbNodes.global.length > 0 || trace.kbNodes.query.length > 0 || trace.schemaNodes.routing.length > 0 || trace.schemaNodes.preResolve.length > 0 || !!trace.schemaNodes.mainAgentCatalog || trace.schemaNodes.sourceAgentSchemas.length > 0 || trace.script != null || trace.scriptMatcher != null || !!trace.entityResolution.catalogText || trace.entityResolution.calls.length > 0 || !!trace.conversationHistory || !!trace.userAccessContext || !!trace.userKbContext || !!trace.concepts?.catalogText || !!trace.concepts?.invariantsText || (trace.concepts?.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;
@@ -26384,8 +26593,7 @@ function buildResolveEntitiesTool(sdk, trace) {
         if (trace) {
           if (entityResult) trace.entityResolution.calls.push({ mentions, ...entityResult });
           if (conceptResult) {
-            trace.conceptResolution ?? (trace.conceptResolution = { calls: [] });
-            trace.conceptResolution.calls.push({ via: "dashboard-agent", asked: conceptNames, ...conceptResult });
+            trace.concepts.calls.push({ via: "dashboard-agent", asked: conceptNames, ...conceptResult });
           }
         }
       } catch (traceErr) {
@@ -26722,7 +26930,7 @@ ${fullPrompt}
           return { success: false, error: `No configured model found (tried ${tried}). Configure at least one of OPENROUTER_API_KEY, ANTHROPIC_API_KEY, or OPENAI_API_KEY.` };
         }
       }
-      model = { ...model, maxTokens: 8e3 };
+      model = { ...model, maxTokens: 2e4 };
       const toolsList = sdk.getTools().map((t) => `- ${t.id}: ${t.name}`).join("\n");
       if (signal?.aborted) {
         console.log(`[DashboardAgent] Aborted during setup \u2014 skipping schema pre-resolution for dashboard ${dashboardId}`);