@duckcodeailabs/dql-agent 1.10.2 → 1.10.3

package/dist/answer-loop.js

@@ -50,6 +50,68 @@ import { buildAnalyticalResultFacts, renderDeterministicAnalyticalNarrative, val
 import { resolveAnalyticalPeriods, } from './analytical-period-resolution.js';
 import { classifyAnalyticalFailure, createAnalyticalFailure, } from './analytical-failure-repair.js';
 import { QUICK_PROMPT_CONTEXT_BUDGET, canUseLaneRepair, cascadeBudgetTrace, createCascadeBudgetState, deepAlternativeCountForQuestion, promptContextBudgetForQuestion, proposalToolBudgetForQuestion, recordLaneRepair, } from './cascade/budgets.js';
+function semanticCompilerFailure(error) {
+    const record = error && typeof error === 'object' ? error : undefined;
+    const message = error instanceof Error ? error.message : String(error);
+    const details = record?.details && typeof record.details === 'object'
+        ? record.details
+        : undefined;
+    const trace = record?.semanticTrace && typeof record.semanticTrace === 'object'
+        ? record.semanticTrace
+        : details?.semanticTrace && typeof details.semanticTrace === 'object'
+            ? details.semanticTrace
+            : undefined;
+    const rawCandidates = Array.isArray(details?.candidates)
+        ? details.candidates
+        : Array.isArray(trace?.failure?.candidates)
+            ? trace.failure.candidates
+            : [];
+    const candidates = rawCandidates.flatMap((candidate) => {
+        if (!candidate || typeof candidate !== 'object')
+            return [];
+        const value = candidate;
+        if (typeof value.id !== 'string' || typeof value.label !== 'string')
+            return [];
+        return [{
+                id: value.id,
+                label: value.label,
+                ...(typeof value.description === 'string' ? { description: value.description } : {}),
+                kind: 'semantic_entity_path',
+            }];
+    });
+    return {
+        message,
+        ...(typeof record?.code === 'string' ? { code: record.code } : {}),
+        ...(trace ? { trace } : {}),
+        ...(candidates.length > 0 ? { candidates } : {}),
+    };
+}
+function semanticTraceAfterExecution(trace, input) {
+    if (!trace)
+        return undefined;
+    const executionStatus = input.error ? 'failed' : input.executed ? 'completed' : 'not_started';
+    const executionDetail = input.error
+        ? `Warehouse execution failed: ${input.error}`
+        : input.executed
+            ? 'The authorized warehouse query executed and returned a result.'
+            : 'The compiler produced SQL, but execution was not requested.';
+    return {
+        ...trace,
+        status: input.error ? 'failed' : trace.status,
+        steps: trace.steps.map((step) => step.id === 'execute_query'
+            ? { ...step, status: executionStatus, detail: executionDetail }
+            : step),
+        ...(input.error
+            ? {
+                failure: {
+                    code: 'EXECUTION_FAILED',
+                    phase: 'execution',
+                    message: input.error,
+                },
+            }
+            : {}),
+    };
+}
 /**
  * Physical column names whose sampled runtime values include `value`. Used by the
  * semantic bridge to bind a filter literal to the dimension that actually carries
@@ -1623,6 +1685,7 @@ async function runAnswerLoop(input) {
     const semanticBridgeToolCalls = [];
     let semanticBridgeAnswer;
     let semanticRuntimeFailure;
+    let semanticExecutionTrace;
     let semanticRuntimeCompiledAnswer = false;
     if (authoritativeSemanticBinding && input.semanticLayer) {
         const selection = authoritativeSemanticBinding.selection;
@@ -1636,6 +1699,7 @@ async function runAnswerLoop(input) {
         if (!semanticBridgeAnswer && input.semanticQueryCompiler) {
             try {
                 const compiled = await input.semanticQueryCompiler(selection);
+                semanticExecutionTrace = compiled.trace;
                 semanticBridgeAnswer = composeSemanticQueryFromCompiledMembers({
                     semanticLayer: input.semanticLayer,
                     question,
@@ -1645,7 +1709,8 @@ async function runAnswerLoop(input) {
                 semanticRuntimeCompiledAnswer = Boolean(semanticBridgeAnswer && compiled.engine !== 'native');
             }
             catch (error) {
-                semanticRuntimeFailure = error instanceof Error ? error.message : String(error);
+                semanticRuntimeFailure = semanticCompilerFailure(error);
+                semanticExecutionTrace = semanticRuntimeFailure.trace;
             }
         }
         if (semanticBridgeAnswer) {
@@ -1658,7 +1723,9 @@ async function runAnswerLoop(input) {
             });
         }
         else if (!semanticRuntimeFailure) {
-            semanticRuntimeFailure = `The exact plan ${authoritativeSemanticBinding.planId} is not composable by the pinned semantic runtime.`;
+            semanticRuntimeFailure = {
+                message: `The exact plan ${authoritativeSemanticBinding.planId} is not composable by the pinned semantic runtime.`,
+            };
         }
     }
     if (!authoritativeSemanticBinding && input.semanticLayer && semanticMetricMatch) {
@@ -1688,6 +1755,7 @@ async function runAnswerLoop(input) {
                 const selection = { metrics: [matchedName], dimensions: [] };
                 try {
                     const compiled = await input.semanticQueryCompiler(selection);
+                    semanticExecutionTrace = compiled.trace;
                     semanticBridgeAnswer = composeSemanticQueryFromCompiledMembers({
                         semanticLayer: input.semanticLayer,
                         question,
@@ -1706,7 +1774,8 @@ async function runAnswerLoop(input) {
                     }
                 }
                 catch (error) {
-                    semanticRuntimeFailure = error instanceof Error ? error.message : String(error);
+                    semanticRuntimeFailure = semanticCompilerFailure(error);
+                    semanticExecutionTrace = semanticRuntimeFailure.trace;
                 }
             }
         }
@@ -1740,6 +1809,7 @@ async function runAnswerLoop(input) {
                 if (!composed && input.semanticQueryCompiler) {
                     try {
                         const compiled = await input.semanticQueryCompiler(selection);
+                        semanticExecutionTrace = compiled.trace;
                         composed = composeSemanticQueryFromCompiledMembers({
                             semanticLayer: bridgeLayer,
                             question,
@@ -1758,7 +1828,8 @@ async function runAnswerLoop(input) {
                         }
                     }
                     catch (error) {
-                        semanticRuntimeFailure = error instanceof Error ? error.message : String(error);
+                        semanticRuntimeFailure = semanticCompilerFailure(error);
+                        semanticExecutionTrace = semanticRuntimeFailure.trace;
                     }
                 }
                 return composed;
@@ -1812,7 +1883,11 @@ async function runAnswerLoop(input) {
         }
     }
     if (!semanticBridgeAnswer && semanticRuntimeFailure) {
-        const text = `The governed semantic metric was found, but its semantic runtime could not compile the request: ${compactSemanticRuntimeFailure(semanticRuntimeFailure)}`;
+        const isPathAmbiguity = semanticRuntimeFailure.code === 'SEMANTIC_PATH_AMBIGUOUS'
+            || semanticRuntimeFailure.trace?.failure?.code === 'SEMANTIC_PATH_AMBIGUOUS';
+        const text = isPathAmbiguity
+            ? semanticRuntimeFailure.message
+            : `The governed semantic metric was found, but its semantic runtime could not compile the request: ${compactSemanticRuntimeFailure(semanticRuntimeFailure.message)}`;
         return {
             kind: 'no_answer',
             sourceTier: 'no_answer',
@@ -1821,10 +1896,17 @@ async function runAnswerLoop(input) {
             confidence: 0,
             text,
             answer: text,
-            refusalCode: 'modeling_gap',
+            refusalCode: isPathAmbiguity ? 'ambiguous' : 'modeling_gap',
             // The answer shows the compact business-readable failure; the FULL compiler
             // output stays here for Inspect/debugging.
-            refusalDetails: { code: 'semantic_runtime_required', message: semanticRuntimeFailure },
+            refusalDetails: {
+                code: isPathAmbiguity ? 'semantic_path_ambiguous' : 'semantic_runtime_required',
+                message: semanticRuntimeFailure.message,
+            },
+            ...(semanticExecutionTrace ? { semanticExecutionTrace } : {}),
+            ...(semanticRuntimeFailure.candidates?.length
+                ? { clarificationOptions: semanticRuntimeFailure.candidates.map((candidate) => ({ ...candidate, question })) }
+                : {}),
             citations: [],
             memoryContext: input.memoryContext,
             evidence: buildNoAnswerEvidence({
@@ -2935,6 +3017,10 @@ async function runAnswerLoop(input) {
         : undefined;
     const certifiedMetricAnswer = semanticMetricCertification === 'certified' || semanticMetricCertification === 'reviewed';
     const governedMetricExecutionFailure = governedMetricAnswer && Boolean(executionError);
+    const finalSemanticExecutionTrace = semanticTraceAfterExecution(semanticExecutionTrace, {
+        executed: Boolean(result),
+        ...(executionError ? { error: executionError } : {}),
+    });
     return {
         kind: governedMetricExecutionFailure ? 'no_answer' : 'uncertified',
         sourceTier: governedMetricExecutionFailure ? 'no_answer' : governedMetricAnswer ? 'semantic_layer' : activeTier,
@@ -2948,6 +3034,7 @@ async function runAnswerLoop(input) {
         sql: parsed.sql,
         result,
         executionError,
+        ...(finalSemanticExecutionTrace ? { semanticExecutionTrace: finalSemanticExecutionTrace } : {}),
         ...(governedMetricExecutionFailure ? { refusalCode: 'grounding_gap' } : {}),
         suggestedViz: parsed.viz ?? 'table',
         dqlArtifact: answerDqlArtifact,
@@ -3138,6 +3225,7 @@ async function executeSemanticAnalyticalGraph(input) {
     const sourceResults = {};
     const compiledSql = [];
     const artifacts = [];
+    let semanticExecutionTrace;
     for (const invocation of input.binding.invocations) {
         let composed = composeSemanticQueryFromMembers({
             semanticLayer: layer,
@@ -3149,6 +3237,7 @@ async function executeSemanticAnalyticalGraph(input) {
         if (!composed && input.input.semanticQueryCompiler) {
             try {
                 const compiled = await input.input.semanticQueryCompiler(invocation.selection);
+                semanticExecutionTrace = compiled.trace;
                 composed = composeSemanticQueryFromCompiledMembers({
                     semanticLayer: layer,
                     question: input.input.question,
@@ -3157,9 +3246,34 @@ async function executeSemanticAnalyticalGraph(input) {
                 });
             }
             catch (error) {
+                const failure = semanticCompilerFailure(error);
+                if (failure.candidates?.length) {
+                    return {
+                        kind: 'no_answer',
+                        sourceTier: 'no_answer',
+                        certification: 'analyst_review_required',
+                        reviewStatus: 'none',
+                        confidence: 0,
+                        text: failure.message,
+                        answer: failure.message,
+                        refusalCode: 'ambiguous',
+                        refusalDetails: { code: 'semantic_path_ambiguous', message: failure.message },
+                        ...(failure.trace ? { semanticExecutionTrace: failure.trace } : {}),
+                        clarificationOptions: failure.candidates.map((candidate) => ({
+                            ...candidate,
+                            question: input.input.question,
+                        })),
+                        analyticalExecutionGraph: input.graph,
+                        citations: contextPackCitations(input.input.contextPack, 8),
+                        considered: input.considered,
+                        contextPack: input.input.contextPack,
+                        providerUsed: input.providerName,
+                    };
+                }
                 return analyticalGraphFailureAnswer(input, 'COMPILATION_FAILED', error instanceof Error ? error.message : String(error), {
                     phase: 'compilation',
                     ...(compiledSql.length ? { compiledSql: renderAnalyticalStatements(compiledSql) } : {}),
+                    ...(failure.trace ? { semanticExecutionTrace: failure.trace } : {}),
                 });
             }
         }
@@ -3184,7 +3298,13 @@ async function executeSemanticAnalyticalGraph(input) {
             result = await executor();
         }
         catch (error) {
-            return analyticalGraphFailureAnswer(input, 'EXECUTION_FAILED', error instanceof Error ? error.message : String(error), { phase: 'execution', dqlArtifact: composed.dqlArtifact, compiledSql: composed.sql });
+            const message = error instanceof Error ? error.message : String(error);
+            return analyticalGraphFailureAnswer(input, 'EXECUTION_FAILED', message, {
+                phase: 'execution',
+                dqlArtifact: composed.dqlArtifact,
+                compiledSql: composed.sql,
+                semanticExecutionTrace: semanticTraceAfterExecution(semanticExecutionTrace, { executed: false, error: message }),
+            });
         }
         const normalized = normalizeAnalyticalSourceResult({
             result,
@@ -3219,6 +3339,9 @@ async function executeSemanticAnalyticalGraph(input) {
             sql,
             ...(artifacts.length === 1 ? { dqlArtifact: artifacts[0] } : {}),
             analyticalExecutionGraph: input.graph,
+            ...(semanticExecutionTrace
+                ? { semanticExecutionTrace: semanticTraceAfterExecution(semanticExecutionTrace, { executed: false }) }
+                : {}),
             citations: contextPackCitations(input.input.contextPack, 8),
             considered: input.considered,
             contextPack: input.input.contextPack,
@@ -3263,6 +3386,9 @@ async function executeSemanticAnalyticalGraph(input) {
         analyticalExecutionReceipt: executed.receipt,
         analyticalFacts: story.factSet,
         analyticalNarrative: story.narrative,
+        ...(semanticExecutionTrace
+            ? { semanticExecutionTrace: semanticTraceAfterExecution(semanticExecutionTrace, { executed: true }) }
+            : {}),
         citations: contextPackCitations(input.input.contextPack, 8),
         considered: input.considered,
         contextPack: input.input.contextPack,
@@ -3472,6 +3598,7 @@ function analyticalGraphFailureAnswer(input, code, reason, artifacts = {}) {
         analyticalExecutionGraph: input.graph,
         ...(artifacts.compiledSql ? { proposedSql: artifacts.compiledSql, sql: artifacts.compiledSql } : {}),
         ...(artifacts.dqlArtifact ? { dqlArtifact: artifacts.dqlArtifact } : {}),
+        ...(artifacts.semanticExecutionTrace ? { semanticExecutionTrace: artifacts.semanticExecutionTrace } : {}),
         citations: contextPackCitations(input.input.contextPack, 8),
         considered: input.considered,
         contextPack: input.input.contextPack,