@duckcodeailabs/dql-agent 1.11.9 → 1.12.0

package/dist/answer-loop.js

@@ -17,6 +17,8 @@
 import { createHash } from 'node:crypto';
 import { describeDialectForPrompt, normalizeMetricCapabilityContract, } from '@duckcodeailabs/dql-core';
 import { buildSkillBlockHints, buildSkillMetricHints, buildSkillsPrompt, expandQuestionWithSkillVocabulary, selectRelevantSkills } from './skills/loader.js';
+import { conversationTurnContextState, } from './conversation/snapshot.js';
+import { renderStructuredConversationSummary } from './conversation/rolling-summary.js';
 import { detectResultSetOperation, computeResultSetOperation } from './conversation/result-ops.js';
 import { classifyGovernedQueryShape } from './semantic-bridge/query-shape.js';
 import { domainContextSearchDomains } from './domain-context.js';
@@ -2900,6 +2902,7 @@ async function runAnswerLoop(input) {
     ];
     let result;
     let executionError;
+    let warehouseFailure;
     let repairAttempts = 0;
     // The repair turn returns error-recovery prose ("the column X was not recognized…"),
     // NOT a user-facing answer. Keep it for the trace only — never as the answer text.
@@ -2909,6 +2912,7 @@ async function runAnswerLoop(input) {
     }
     if (deepCandidateExecutionError) {
         executionError = deepCandidateExecutionError;
+        warehouseFailure = normalizeWarehouseSqlFailure(deepCandidateExecutionError, input.semanticDriver);
     }
     const executeCurrentSql = () => {
         const requestedLimit = questionPlan.requestedShape.topN?.scope === 'per_group'
@@ -2961,10 +2965,12 @@ async function runAnswerLoop(input) {
                 result = await executeCurrentSql();
         }
         catch (err) {
-            executionError = err instanceof Error ? err.message : String(err);
+            warehouseFailure = normalizeWarehouseSqlFailure(err, input.semanticDriver);
+            executionError = warehouseFailure.redactedMessage;
         }
         if (executionError && !fanoutContradiction && !authoritativeSemanticBinding) {
-            if (isRetryableGeneratedSqlError(executionError)) {
+            warehouseFailure ??= normalizeWarehouseSqlFailure(executionError, input.semanticDriver);
+            if (isRetryableGeneratedSqlError(warehouseFailure)) {
                 const localRepairSql = repairGeneratedSqlLocally(parsed.sql, executionError, schemaContext);
                 if (localRepairSql && canUseLaneRepair(repairBudgetState, 'execution')) {
                     recordLaneRepair(repairBudgetState, 'execution');
@@ -2989,23 +2995,28 @@ async function runAnswerLoop(input) {
                         try {
                             result = await executeCurrentSql();
                             executionError = undefined;
+                            warehouseFailure = undefined;
                         }
                         catch (retryErr) {
-                            executionError = retryErr instanceof Error ? retryErr.message : String(retryErr);
+                            warehouseFailure = normalizeWarehouseSqlFailure(retryErr, input.semanticDriver);
+                            executionError = warehouseFailure.redactedMessage;
                         }
                     }
                     else {
                         executionError = localRepairValidation.error;
+                        warehouseFailure = normalizeWarehouseSqlFailure(localRepairValidation.error, input.semanticDriver);
                     }
                 }
-                if (executionError && canUseLaneRepair(repairBudgetState, 'execution')) {
+                if (executionError
+                    && warehouseFailure?.retryDisposition === 'model_repair'
+                    && canUseLaneRepair(repairBudgetState, 'execution')) {
                     recordLaneRepair(repairBudgetState, 'execution');
                     const repairedRaw = await requestSqlRepair({
                         provider,
                         baseMessages: messages,
                         question,
                         parsed,
-                        executionError,
+                        failure: warehouseFailure,
                         schemaContext,
                         signal: input.signal,
                         reasoningEffort: input.reasoningEffort,
@@ -3037,13 +3048,16 @@ async function runAnswerLoop(input) {
                             try {
                                 result = await executeCurrentSql();
                                 executionError = undefined;
+                                warehouseFailure = undefined;
                             }
                             catch (retryErr) {
-                                executionError = retryErr instanceof Error ? retryErr.message : String(retryErr);
+                                warehouseFailure = normalizeWarehouseSqlFailure(retryErr, input.semanticDriver);
+                                executionError = warehouseFailure.redactedMessage;
                             }
                         }
                         else {
                             executionError = repairedValidation.error;
+                            warehouseFailure = normalizeWarehouseSqlFailure(repairedValidation.error, input.semanticDriver);
                         }
                     }
                 }
@@ -3204,6 +3218,7 @@ async function runAnswerLoop(input) {
         sql: parsed.sql,
         result,
         executionError,
+        ...(warehouseFailure ? { warehouseFailure } : {}),
         ...(finalSemanticExecutionTrace ? { semanticExecutionTrace: finalSemanticExecutionTrace } : {}),
         ...(governedMetricExecutionFailure ? { refusalCode: 'grounding_gap' } : {}),
         suggestedViz: parsed.viz ?? 'table',
@@ -4271,7 +4286,7 @@ function renderContextPrompt(blocks, businessContext, others, activeTier, memory
     const hintsSection = appliedHints.length > 0
         ? `\n\n## Applied governed hints (human-approved corrections)\n\nReviewed, scope-matched corrections from your team. Apply them when preparing a SQL preview to avoid known mistakes; they refine the DQL artifact's SQL preview but MUST NOT override a certified artifact that already answers the question.\n${appliedHints
             .slice(0, 6)
-            .map((h) => `- \`${h.title}\`: ${h.guidance}${h.correctedSql ? `\n  corrected SQL pattern: ${h.correctedSql.replace(/\s+/g, ' ').trim().slice(0, 240)}` : ''}`)
+            .map((h) => `- \`${h.title}\`: ${h.guidance}${h.graphReason ? `\n  matched graph context: ${h.graphReason}` : ''}${h.correctedSql ? `\n  corrected SQL pattern: ${h.correctedSql.replace(/\s+/g, ' ').trim().slice(0, 240)}` : ''}`)
             .join('\n')}`
         : '';
     const extraSection = extraContext?.trim()
@@ -4347,8 +4362,12 @@ function renderConversationSnapshot(snapshot) {
     else if (snapshot.topicRelation) {
         parts.push(`Working state: topic=${snapshot.topicRelation}`);
     }
-    if (snapshot.rollingSummary) {
-        parts.push(`Earlier in this conversation (compacted):\n${snapshot.rollingSummary.slice(0, 600)}`);
+    const structuredSummary = renderStructuredConversationSummary(snapshot.structuredSummary);
+    if (structuredSummary) {
+        parts.push(`Earlier in this conversation (source-attributed):\n${structuredSummary}`);
+    }
+    else if (snapshot.rollingSummary) {
+        parts.push(`Earlier in this conversation (legacy compacted view):\n${snapshot.rollingSummary.slice(0, 600)}`);
     }
     if (snapshot.recentTurns.length > 0) {
         const turns = snapshot.recentTurns.slice(-4).map((turn, index) => {
@@ -4356,16 +4375,20 @@ function renderConversationSnapshot(snapshot) {
         });
         parts.push(`Recent turns:\n${turns.join('\n')}`);
     }
-    if (snapshot.recalledTurns?.length) {
-        parts.push(`Recalled earlier turns (semantic match):\n${snapshot.recalledTurns.slice(0, 3)
+    const recalledTurns = snapshot.recalledTurns
+        ?.filter((turn) => conversationTurnContextState(turn) !== 'blocked')
+        .slice(0, 3);
+    if (recalledTurns?.length) {
+        parts.push(`Recalled earlier turns (semantic match):\n${recalledTurns
             .map((turn) => `- ${renderConversationSnapshotTurnLine(turn, 520)}`)
             .join('\n')}`);
     }
-    parts.push('Use this only where the question refers to it. On a new topic, answer fresh.');
+    parts.push('Use this only where the question refers to it. Provisional, unresolved, and blocked turns are not verified facts. On a new topic, answer fresh.');
     return parts.join('\n\n');
 }
 function renderConversationSnapshotTurnLine(turn, max) {
     const line = [
+        `state: ${conversationTurnContextState(turn)}`,
         `Q: ${turn.question}`,
         turn.answerSummary ? `A: ${turn.answerSummary}` : '',
         turn.resultColumns?.length ? `cols: ${turn.resultColumns.slice(0, 6).join(', ')}` : '',
@@ -6221,12 +6244,18 @@ async function requestSqlRepair(input) {
             content: [
                 'The SQL preview for the review-required DQL artifact failed during bounded preview execution.',
                 `Question: ${input.question}`,
-                `Execution error: ${input.executionError}`,
+                `Warehouse dialect: ${input.failure.driver ?? 'unknown'}`,
+                `Failure category: ${input.failure.category}`,
+                `Execution error: ${input.failure.redactedMessage}`,
+                input.failure.vendorCode ? `Vendor code: ${input.failure.vendorCode}` : '',
+                input.failure.sqlState ? `SQL state: ${input.failure.sqlState}` : '',
+                input.failure.line !== undefined ? `Failure line: ${input.failure.line}` : '',
+                input.failure.position !== undefined ? `Failure position: ${input.failure.position}` : '',
                 'Qualify every source column independently inside each SELECT/CTE scope. Do not repair an ambiguous column by choosing the first FROM relation; use the runtime schema to identify its unique owner, or leave the query unresolved when no unique owner is proven.',
                 'Preserve every requested output measure and dimension while repairing the failing reference.',
                 'Return one corrected read-only SQL query using only the runtime schema below, as a single ```json fenced object with summary, sql, viz, outputs, and optional dql metadata fields.',
                 schema,
-            ].join('\n\n'),
+            ].filter(Boolean).join('\n\n'),
         },
     ], {
         signal: input.signal,
@@ -6499,8 +6528,102 @@ function summarizeEvidencePayload(value, maxLength = 700) {
         return undefined;
     return compact.length <= maxLength ? compact : `${compact.slice(0, maxLength - 3)}...`;
 }
-function isRetryableGeneratedSqlError(error) {
-    return !/\b(read-only|readonly|select or with|unsafe|delete|insert|update|drop|alter|create|attach|copy|pragma)\b/i.test(error);
+export function normalizeWarehouseSqlFailure(error, fallbackDriver) {
+    const record = error && typeof error === 'object'
+        ? error
+        : undefined;
+    const rawMessage = error instanceof Error
+        ? error.message
+        : typeof error === 'string'
+            ? error
+            : typeof record?.message === 'string'
+                ? record.message
+                : String(error);
+    const message = redactWarehouseSqlFailureMessage(rawMessage);
+    const category = classifyWarehouseSqlFailure(message);
+    return {
+        version: 1,
+        category,
+        retryDisposition: warehouseSqlRetryDisposition(category),
+        redactedMessage: message,
+        ...(stringField(record, 'driver') ?? fallbackDriver
+            ? { driver: stringField(record, 'driver') ?? fallbackDriver }
+            : {}),
+        ...(stringField(record, 'vendorCode') ? { vendorCode: stringField(record, 'vendorCode') } : {}),
+        ...(stringField(record, 'sqlState') ? { sqlState: stringField(record, 'sqlState') } : {}),
+        ...(stringField(record, 'queryId') ? { queryId: stringField(record, 'queryId') } : {}),
+        ...(numberField(record, 'line') !== undefined ? { line: numberField(record, 'line') } : {}),
+        ...(numberField(record, 'position') !== undefined ? { position: numberField(record, 'position') } : {}),
+        ...(typeof record?.retryable === 'boolean' ? { retryable: record.retryable } : {}),
+    };
+}
+function redactWarehouseSqlFailureMessage(message) {
+    const compact = message.replace(/\s+/g, ' ').trim()
+        .replace(/\b(password|token|secret|private[_ -]?key)\s*[=:]\s*([^\s,;]+)/gi, '$1=[redacted]')
+        .replace(/\b(?:https?|snowflake|postgres(?:ql)?):\/\/[^\s]+/gi, '[redacted connection]');
+    return (compact || 'Warehouse query failed.').slice(0, 700);
+}
+function classifyWarehouseSqlFailure(message) {
+    if (/\b(read-only|readonly|select or with|unsafe statement|not permitted sql|delete|insert|update|drop|alter|create|attach|copy|pragma)\b/i.test(message)) {
+        return 'unsafe';
+    }
+    if (/\b(authentication|authenticate|invalid credentials?|incorrect username|login failed|oauth|expired token)\b/i.test(message)) {
+        return 'authentication';
+    }
+    if (/\b(permission denied|insufficient privileges?|not authorized|access denied|authorization failed|does not have privilege)\b/i.test(message)) {
+        return 'permission';
+    }
+    if (/\b(cancelled|canceled|aborted by user)\b/i.test(message))
+        return 'cancelled';
+    if (/\b(timeout|timed out|deadline exceeded|statement timeout)\b/i.test(message))
+        return 'timeout';
+    if (/\bambiguous\s+(?:reference|column(?:\s+name)?)\b/i.test(message))
+        return 'ambiguous_column';
+    if (/\b(column|identifier|field)\b.*\b(not found|does not exist|not recognized|invalid identifier|unknown)\b/i.test(message)
+        || /\bdoes not have a column named\b/i.test(message)
+        || /\binvalid identifier\b/i.test(message)) {
+        return 'unknown_column';
+    }
+    if (/\b(table|relation|view|object)\b.*\b(not found|does not exist|unknown|not exist|not authorized)\b/i.test(message)) {
+        return 'unknown_relation';
+    }
+    if (/\b(function|routine)\b.*\b(not found|does not exist|unknown|unsupported|no matching signature)\b/i.test(message)) {
+        return 'unsupported_function';
+    }
+    if (/\b(type mismatch|cannot cast|conversion error|invalid argument types?|operator does not exist)\b/i.test(message)) {
+        return 'type_mismatch';
+    }
+    if (/\b(parser error|parse error|syntax error|sql compilation error|unexpected token|unexpected keyword)\b/i.test(message)) {
+        return 'syntax';
+    }
+    return 'unknown';
+}
+function warehouseSqlRetryDisposition(category) {
+    if (category === 'syntax'
+        || category === 'unknown_column'
+        || category === 'ambiguous_column'
+        || category === 'unsupported_function'
+        || category === 'type_mismatch') {
+        return 'model_repair';
+    }
+    if (category === 'unknown_relation')
+        return 'refresh_metadata';
+    if (category === 'timeout')
+        return 'explicit_retry';
+    if (category === 'permission' || category === 'authentication')
+        return 'change_authorized_access';
+    return 'terminal';
+}
+function stringField(record, key) {
+    const value = record?.[key];
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function numberField(record, key) {
+    const value = record?.[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function isRetryableGeneratedSqlError(failure) {
+    return failure.retryDisposition === 'model_repair';
 }
 /**
  * Only SQL-shape/binding failures may leave the certified lane. Connectivity,