@duckcodeailabs/dql-cli 1.13.3 → 1.13.5

package/dist/llm/providers/dql-agent-provider.js

@@ -1,8 +1,7 @@
-import { ClaudeProvider, KGStore, MemoryStore, defaultKgPath, defaultMemoryPath, GeminiProvider, loadAgentSemanticLayer, OllamaProvider, OpenAIProvider, answer, buildAnalysisQuestionPlan, buildLocalContextPack, contextRetrievalBudgetForQuestion, ensureAgentProjectReady, isLikelyClarificationReply, isTrustedConversationTurn, } from '@duckcodeailabs/dql-agent';
+import { ClaudeProvider, KGStore, MemoryStore, defaultKgPath, defaultMemoryPath, GeminiProvider, loadAgentSemanticLayer, OllamaProvider, OpenAIProvider, answer, buildAnalysisQuestionPlan, buildLocalContextPack, contextRetrievalBudgetForQuestion, ensureAgentProjectReady, isLikelyClarificationReply, isTrustedConversationTurn, createProviderDispatchEgressReceipt, createProviderEgressReceipt, assertProviderPayloadAllowed, prepareProviderContextForDispatch, prepareProviderWireEnvelopeForDispatch, prepareServerOwnedProviderSchemaContext, } from '@duckcodeailabs/dql-agent';
 import { buildManifest, normalizeDqlArtifactReference, resolveDbtManifestPath } from '@duckcodeailabs/dql-core';
 import { existsSync } from 'node:fs';
 import { buildAnswerLoopTools, createGroundingContextExpander } from '../answer-loop-tools.js';
-import { rethrowIfCancelled } from '../cancellation.js';
 import { getSemanticRuntimeStatus } from '../../semantic-runtime.js';
 import { blockProposalDqlMetadata } from '../proposal-metadata.js';
 import { getEffectiveProviderConfig } from '../../settings/provider-settings.js';
@@ -258,11 +257,126 @@ function emitProposalFromText(text, emit) {
         // Ignore malformed proposal text. The visible assistant response still streams as text.
     }
 }
-export function createDqlAgentProviderRunner(id) {
+export function createDqlAgentProviderRunner(id, providerOverride) {
     return {
         async run(req, emit, signal) {
             const spec = SPECS[id];
-            const provider = spec.create(req.projectRoot);
+            const rawProvider = providerOverride ?? spec.create(req.projectRoot);
+            const isResearch = req.analysisDepth === 'deep';
+            const researchRowsOptIn = isResearch && req.researchResultRowsOptIn === true;
+            const sharedDispatchEvidence = req.providerDispatchEvidenceSink;
+            let providerRoundTrips = 0;
+            let sqlExecutions = 0;
+            let pendingResultRowCount = 0;
+            let pendingColumnCount = 0;
+            let pendingCumulativeResultRowCount = 0;
+            let pendingResearchPurpose = 'research_narration';
+            const providerEgressReceipts = [];
+            const dispatchEvidence = (fallbackReason) => {
+                const shared = sharedDispatchEvidence?.snapshot(fallbackReason);
+                return shared
+                    ? { ...shared, sqlExecutions, fallbackReason }
+                    : {
+                        providerEgressReceipts: [...providerEgressReceipts],
+                        providerRoundTrips,
+                        toolCalls: 0,
+                        sqlExecutions,
+                        repairs: 0,
+                        fallbackReason,
+                    };
+            };
+            signal.addEventListener('abort', () => {
+                const reason = signal.reason;
+                if (reason && typeof reason === 'object') {
+                    Object.assign(reason, { providerDispatchEvidence: dispatchEvidence('cancelled') });
+                }
+            }, { once: true });
+            const withPhysicalDispatchObserver = (options) => ({
+                ...(options ?? {}),
+                // A tool-calling loop capped at two physical sends can make exactly one
+                // tool call before it must answer, which is not enough to look something
+                // up and then use it. The run-scoped ledger is the real guardrail.
+                maxProviderDispatches: isResearch ? 8 : 4,
+                ...(sharedDispatchEvidence?.mayStartToolCall
+                    ? { mayStartToolCall: () => sharedDispatchEvidence.mayStartToolCall() }
+                    : {}),
+                onProviderDispatch: (event) => {
+                    const purpose = isResearch ? pendingResearchPurpose : 'answer_generation';
+                    if (sharedDispatchEvidence) {
+                        const envelope = sharedDispatchEvidence.observe(event, {
+                            purpose,
+                            dispatchPhase: 'generation',
+                            optIn: pendingResultRowCount > 0 && researchRowsOptIn,
+                            serializedResultShape: {
+                                resultRowCount: pendingResultRowCount,
+                                columnCount: pendingColumnCount,
+                            },
+                            ...(pendingCumulativeResultRowCount > 0
+                                ? { cumulativeResultRowCount: pendingCumulativeResultRowCount }
+                                : {}),
+                        });
+                        pendingResultRowCount = 0;
+                        pendingColumnCount = 0;
+                        pendingCumulativeResultRowCount = 0;
+                        pendingResearchPurpose = 'research_narration';
+                        return envelope;
+                    }
+                    // Fallback path only (CLI/MCP-direct runs carry no shared ledger).
+                    // Kept in step with `maxProviderDispatches` above so the same question
+                    // does not get a different budget depending on which surface asked it.
+                    if (!isResearch && providerRoundTrips >= 4) {
+                        throw Object.assign(new Error('Provider dispatch budget exhausted after four ordinary generation attempts.'), {
+                            code: 'PROVIDER_DISPATCH_BUDGET_EXHAUSTED',
+                        });
+                    }
+                    const envelope = prepareProviderWireEnvelopeForDispatch(rawProvider.name, event.envelope);
+                    assertProviderPayloadAllowed(envelope, {
+                        allowResultRows: false,
+                        maxResultRows: 0,
+                        purpose,
+                    });
+                    providerRoundTrips += 1;
+                    providerEgressReceipts.push(createProviderDispatchEgressReceipt({
+                        purpose,
+                        dispatchPhase: 'generation',
+                        provider: rawProvider.name,
+                        permittedCategories: pendingResultRowCount > 0
+                            ? ['instructions', 'question', 'schema_metadata', 'governed_context', 'result_rows']
+                            : ['instructions', 'question', 'schema_metadata', 'governed_context'],
+                        optIn: pendingResultRowCount > 0 && researchRowsOptIn,
+                        envelope,
+                        serializedResultShape: {
+                            resultRowCount: pendingResultRowCount,
+                            columnCount: pendingColumnCount,
+                        },
+                        ...(pendingCumulativeResultRowCount > 0
+                            ? { cumulativeResultRowCount: pendingCumulativeResultRowCount }
+                            : {}),
+                    }));
+                    pendingResultRowCount = 0;
+                    pendingColumnCount = 0;
+                    pendingCumulativeResultRowCount = 0;
+                    pendingResearchPurpose = 'research_narration';
+                    return envelope;
+                },
+            });
+            const provider = {
+                name: rawProvider.name,
+                available: () => rawProvider.available(),
+                generate: (...args) => {
+                    return rawProvider.generate(args[0], withPhysicalDispatchObserver(args[1]));
+                },
+                ...(rawProvider.generateWithTools ? {
+                    generateWithTools: (...args) => {
+                        return rawProvider.generateWithTools(args[0], args[1], withPhysicalDispatchObserver(args[2]));
+                    },
+                } : {}),
+                ...(rawProvider.generateStream ? {
+                    generateStream: (...args) => {
+                        return rawProvider.generateStream(args[0], withPhysicalDispatchObserver(args[1]), args[2]);
+                    },
+                } : {}),
+            };
             const available = await provider.available().catch(() => false);
             if (!available) {
                 emit({ kind: 'error', message: `${spec.label} is not configured or reachable. ${spec.setup}` });
@@ -362,7 +476,9 @@ export function createDqlAgentProviderRunner(id) {
                         sourcePath: skill.sourcePath ?? '',
                     }));
                     const contextDurationMs = Date.now() - contextStartedAt;
-                    const answerLoopTools = buildAnswerLoopTools(req.projectRoot);
+                    const answerLoopTools = buildAnswerLoopTools(req.projectRoot, {
+                        researchResultRowsOptIn: researchRowsOptIn,
+                    });
                     const sourceSearchTool = answerLoopTools.find((tool) => tool.name === 'search_project_files');
                     const sourceSearchStartedAt = Date.now();
                     const earlySourceSearch = sourceSearchTool && shouldSearchProjectFiles(contextPack)
@@ -404,6 +520,19 @@ export function createDqlAgentProviderRunner(id) {
                         if (req.projectSnapshot)
                             req.assertProjectSnapshot?.(req.projectSnapshot.snapshotId);
                     };
+                    assertProviderPayloadAllowed(prepareProviderContextForDispatch({
+                        question,
+                        ...(conversationSnapshot ? { conversationSnapshot } : {}),
+                        ...(memoryContext ? { memoryContext } : {}),
+                        schemaContext: prepareServerOwnedProviderSchemaContext(schemaContext),
+                        ...(contextPack ? { contextPack } : {}),
+                        skills,
+                        ...(followUp ? { followUp } : {}),
+                    }), {
+                        allowResultRows: false,
+                        maxResultRows: 0,
+                        purpose: 'answer_generation',
+                    });
                     const result = await answer({
                         question,
                         ...(req.resolvedAnalyticalPlan
@@ -442,22 +571,55 @@ export function createDqlAgentProviderRunner(id) {
                         signal,
                         reasoningEffort: req.reasoningEffort,
                         analysisDepth: contextBudget.analysisDepth,
+                        allowProviderSemanticMemberSelection: req.allowProviderSemanticMemberSelection === true,
                         ...(req.semanticDriver ? { semanticDriver: req.semanticDriver } : {}),
                         ...(req.semanticTableMapping ? { semanticTableMapping: req.semanticTableMapping } : {}),
                         ...(req.semanticQueryCompiler ? { semanticQueryCompiler: req.semanticQueryCompiler } : {}),
                         ...(req.preferredEvidenceIds?.length ? { preferredEvidenceIds: req.preferredEvidenceIds } : {}),
                         ...(req.preferredExecutionId ? { preferredExecutionId: req.preferredExecutionId } : {}),
                         executeCertifiedBlock: req.executeCertifiedBlock
-                            ? async (...args) => { guardSnapshot(); return req.executeCertifiedBlock(...args); }
+                            ? async (...args) => { guardSnapshot(); sqlExecutions += 1; return req.executeCertifiedBlock(...args); }
                             : undefined,
                         executeGeneratedSql: req.executeGeneratedSql
-                            ? async (...args) => { guardSnapshot(); return req.executeGeneratedSql(...args); }
+                            ? async (...args) => { guardSnapshot(); sqlExecutions += 1; return req.executeGeneratedSql(...args); }
                             : undefined,
                         executeDqlArtifact: req.executeDqlArtifact
-                            ? async (...args) => { guardSnapshot(); return req.executeDqlArtifact(...args); }
+                            ? async (...args) => { guardSnapshot(); sqlExecutions += 1; return req.executeDqlArtifact(...args); }
                             : undefined,
                         expandGroundingContext: createGroundingContextExpander(req.projectRoot, req.probeNamedRelations),
                         answerLoopTools,
+                        providerPayloadGuard: {
+                            purpose: 'research_tool',
+                            allowedResultRowTools: researchRowsOptIn
+                                ? { sample_notebook_dataset: 20, execute_local_analysis: 200 }
+                                : {},
+                            resultRowBudgetGroupByTool: {
+                                sample_notebook_dataset: 'research_sample',
+                                execute_local_analysis: 'research_local_analysis',
+                            },
+                            cumulativeResultRowBudgets: {
+                                research_sample: 20,
+                                research_local_analysis: 200,
+                            },
+                            onPayload: ({ toolName, output, resultRowCount, columnCount, cumulativeResultRowCount }) => {
+                                pendingResearchPurpose = researchDispatchPurposeForTool(toolName);
+                                pendingResultRowCount += resultRowCount;
+                                pendingColumnCount = Math.max(pendingColumnCount, columnCount);
+                                pendingCumulativeResultRowCount = Math.max(pendingCumulativeResultRowCount, cumulativeResultRowCount);
+                                if (resultRowCount === 0)
+                                    return;
+                                providerEgressReceipts.push(createProviderEgressReceipt({
+                                    purpose: researchDispatchPurposeForTool(toolName),
+                                    provider: provider.name,
+                                    permittedCategories: ['question', 'schema_metadata', 'result_rows'],
+                                    optIn: researchRowsOptIn,
+                                    payload: { toolName, output },
+                                    resultRowCount,
+                                    columnCount,
+                                    cumulativeResultRowCount,
+                                }));
+                            },
+                        },
                         // NOTE: no captureGeneratedDraft here — a plain answer/research question must NOT
                         // auto-write a draft into the blocks space. A draft is created only when the user
                         // explicitly acts (the "Create DQL draft" action → the dql_block_draft route).
@@ -483,6 +645,27 @@ export function createDqlAgentProviderRunner(id) {
                         { phase: 'answer_resolution', durationMs: answerDurationMs, detail: result.route?.tier ?? result.kind },
                         { phase: 'total', durationMs: Date.now() - requestStartedAt },
                     ];
+                    const terminalDispatchEvidence = dispatchEvidence('none');
+                    result.evidence.runtimeCounters = {
+                        providerRoundTrips: terminalDispatchEvidence.providerRoundTrips,
+                        toolCalls: result.evidence.toolCalls?.length ?? 0,
+                        sqlExecutions,
+                        repairs: result.analysisPlan?.repairAttempts ?? 0,
+                    };
+                    if (req.analysisDepth === 'deep' && !providerEgressReceipts.some((receipt) => receipt.purpose === 'research_tool')) {
+                        providerEgressReceipts.push(createProviderEgressReceipt({
+                            purpose: 'research_tool',
+                            provider: provider.name,
+                            permittedCategories: ['instructions', 'question', 'schema_metadata', 'governed_context'],
+                            optIn: researchRowsOptIn,
+                            payload: { resultRows: 0, enabled: researchRowsOptIn },
+                            resultRowCount: 0,
+                            columnCount: 0,
+                        }));
+                    }
+                    result.providerEgressReceipts = sharedDispatchEvidence
+                        ? terminalDispatchEvidence.providerEgressReceipts
+                        : providerEgressReceipts;
                     emit({ kind: 'tool_result', id: 'governed_answer', output: result });
                     emit({ kind: 'text', text: formatAgentAnswer(result) });
                     if (result.proposedSql) {
@@ -507,10 +690,41 @@ export function createDqlAgentProviderRunner(id) {
                 // A deadline/cancellation is NOT a provider failure. Rethrow it intact so
                 // the engine renders its graceful bounded-deadline message instead of a
                 // raw "<provider> failed: The operation was aborted due to timeout".
-                rethrowIfCancelled(err, signal);
+                if (signal.aborted) {
+                    const reason = signal.reason ?? err;
+                    if (reason && typeof reason === 'object') {
+                        Object.assign(reason, { providerDispatchEvidence: dispatchEvidence('cancelled') });
+                    }
+                    throw reason;
+                }
                 const message = err instanceof Error ? err.message : String(err);
+                // Both codes are DQL's OWN budget refusing to start another dispatch.
+                // Only the count-based one was recognized, so a time-based refusal was
+                // reported as "<provider> failed: The 30-second soft target elapsed" —
+                // blaming the user's AI subscription for DQL's timer and sending them
+                // to debug the wrong system entirely.
+                const budgetCode = err && typeof err === 'object'
+                    ? String(err.code)
+                    : '';
+                const orchestrationBudgetExhausted = budgetCode === 'PROVIDER_DISPATCH_BUDGET_EXHAUSTED'
+                    || budgetCode === 'RUN_SOFT_TARGET_EXCEEDED'
+                    || budgetCode === 'RUN_DEADLINE_INSUFFICIENT';
+                // The project catalog was rebuilt underneath a run in flight. That is
+                // DQL's own concurrency, and telling the user their AI subscription
+                // failed sends them to re-authenticate a provider that worked fine.
+                const snapshotDrift = budgetCode === 'PROJECT_SNAPSHOT_MISMATCH';
                 const setupHint = shouldShowProviderSetupHint(message) ? ` ${spec.setup}` : '';
-                emit({ kind: 'error', message: `${spec.label} failed: ${message}.${setupHint}` });
+                emit({
+                    kind: 'error',
+                    message: orchestrationBudgetExhausted
+                        ? `Ask stopped at its own bounded orchestration budget before a final answer was available — the AI provider did not fail. (${message})`
+                        : snapshotDrift
+                            ? 'The project snapshot was rebuilt while this run was in flight, so DQL discarded the in-progress plan rather than answer from a stale catalog. The AI provider did not fail — retry the question.'
+                            : `${spec.label} failed: ${message}.${setupHint}`,
+                    dispatchEvidence: dispatchEvidence(orchestrationBudgetExhausted ? 'orchestration_budget_exhausted'
+                        : snapshotDrift ? 'project_snapshot_mismatch'
+                            : 'provider_error'),
+                });
             }
         },
     };
@@ -663,13 +877,20 @@ export function renderExtraContext(req, followUp) {
         // questions. Render it as prose with its trust instruction, and strip it
         // from the JSON below rather than shipping the same content twice.
         try {
-            const envelope = JSON.parse(upstream);
-            const appContext = envelope.workspaceContext?.appContext;
+            const rawEnvelope = JSON.parse(upstream);
+            const appContext = rawEnvelope.workspaceContext?.appContext;
             const rendered = renderAppContextForPrompt(appContext);
             if (rendered) {
                 parts.push(rendered);
-                const { appContext: _dropped, ...restWorkspace } = envelope.workspaceContext ?? {};
-                upstream = JSON.stringify({ ...envelope, workspaceContext: restWorkspace }, null, 2);
+                const { appContext: _dropped, ...restWorkspace } = rawEnvelope.workspaceContext ?? {};
+                const envelope = prepareProviderContextForDispatch({
+                    ...rawEnvelope,
+                    workspaceContext: restWorkspace,
+                });
+                upstream = JSON.stringify(envelope, null, 2);
+            }
+            else {
+                upstream = JSON.stringify(prepareProviderContextForDispatch(rawEnvelope), null, 2);
             }
         }
         catch {
@@ -943,6 +1164,7 @@ function resolveAgentFollowUpContextRaw(rawContext, question) {
         })),
         resolvedReferences: resolvedReferences.labels,
         unresolvedReferences: resolvedReferences.unresolved,
+        deicticChoices: resolvedReferences.deicticChoices,
         // The prior turn's actual rows, so a follow-up can compute across the shown
         // results ("of these, the average") without a fresh query. A relative
         // comparison deliberately drops the prior contract, so skip it there too.
@@ -1161,7 +1383,18 @@ function resolveConversationReferences(question, turns, activeValues) {
     ];
     let filters = resolveDeicticFilters(question, activeValues) ?? [];
     const labels = [];
-    if (!namedValues && dimensions.length > 0 && filters.length === 0) {
+    // An ambiguous singular reference is the single most common follow-up shape
+    // ("what region does this customer belong to?" after a ranked list). Keep the
+    // candidates so the run can offer them instead of dead-ending.
+    const ambiguousSingular = !namedValues
+        ? resolveSingularDeicticCandidates(question, activeValues)
+        : undefined;
+    const deicticChoices = ambiguousSingular && ambiguousSingular.values.length > 1
+        ? ambiguousSingular
+        : undefined;
+    // Do NOT backfill an ambiguous singular from history: filtering on all of the
+    // candidates answers a different question than the one that was asked.
+    if (!namedValues && !deicticChoices && dimensions.length > 0 && filters.length === 0) {
         for (const turn of [...turns].reverse()) {
             const values = cleanStringRecordArray(cleanRecord(turn.result)?.dimensionValues);
             if (!values)
@@ -1200,7 +1433,9 @@ function resolveConversationReferences(question, turns, activeValues) {
                 }]
             : [];
     const unresolved = referencesNeedValues(question) && filters.length === 0
-        ? ['Could not resolve the referenced prior result values from conversation state.']
+        ? [deicticChoices
+                ? `"${deicticChoices.dimension}" was referenced in the singular, but the previous result had ${deicticChoices.values.length} of them.`
+                : 'Could not resolve the referenced prior result values from conversation state.']
         : undefined;
     return {
         filters: filters.length > 0 ? Array.from(new Set(filters)).slice(0, 24) : undefined,
@@ -1209,6 +1444,7 @@ function resolveConversationReferences(question, turns, activeValues) {
         unresolved,
         valuesByDimension: namedValues,
         memberBindings: memberBindings.length > 0 ? memberBindings : undefined,
+        deicticChoices,
     };
 }
 /**
@@ -1353,15 +1589,34 @@ function cleanStringRecordArray(value) {
     }
     return Object.keys(out).length > 0 ? out : undefined;
 }
+/**
+ * Values a singular deictic reference ("this customer") could be pointing at.
+ *
+ * This used to `.slice(0, 1)` — silently picking the FIRST row of the previous
+ * answer and binding it as a required filter. After a ten-row ranking, "this
+ * customer" would quietly become "Melissa Lopez" because she happened to sort
+ * first, and the user was never told. An ambiguous reference must stay
+ * ambiguous so the caller can ask which one was meant.
+ */
+function resolveSingularDeicticCandidates(question, priorValues) {
+    if (!priorValues)
+        return undefined;
+    const singular = resolveSingularDeicticDimension(question, priorValues);
+    if (!singular)
+        return undefined;
+    const values = Array.from(new Set(valuesForPriorDimension(priorValues, singular))).slice(0, 24);
+    return values.length > 0 ? { dimension: singular, values } : undefined;
+}
 function resolveDeicticFilters(question, priorValues) {
     if (!priorValues)
         return undefined;
     const hasExplicitPluralReference = /\b(?:these|those|same)\s+(?:customers?|products?|cat(?:egor|agor|ogor)(?:y|ies)|segments?|regions?)\b/i.test(question);
     if (!hasExplicitPluralReference) {
-        const singular = resolveSingularDeicticDimension(question, priorValues);
+        const singular = resolveSingularDeicticCandidates(question, priorValues);
         if (singular) {
-            const values = valuesForPriorDimension(priorValues, singular).slice(0, 1);
-            return values.length > 0 ? values : undefined;
+            // Exactly one candidate is unambiguous and can be bound as a filter.
+            // Several candidates are a question for the user, not a coin flip.
+            return singular.values.length === 1 ? singular.values : undefined;
         }
     }
     const dims = resolveDeicticDimensions(question, priorValues) ?? [];
@@ -1499,7 +1754,11 @@ export const __test__ = {
     shouldLoadSchemaContext,
     shouldSearchProjectFiles,
     renderProjectSourceSearch,
+    researchDispatchPurposeForTool,
 };
+function researchDispatchPurposeForTool(toolName) {
+    return toolName === 'execute_local_analysis' ? 'research_tool' : 'research_narration';
+}
 const GENERIC_FOLLOW_UP_WORDS = new Set([
     'a', 'about', 'again', 'all', 'also', 'and', 'are', 'as', 'be', 'block', 'can', 'could', 'data', 'did', 'do', 'does',
     'execute', 'for', 'from', 'get', 'give', 'import', 'it', 'its', 'let', 'lets', 'me', 'metrics',