@duckcodeailabs/dql-cli 1.14.1 → 1.14.2

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

@@ -1,9 +1,10 @@
-import { deadlineScale, planAnalystTurn, rerankCandidates } from '@duckcodeailabs/dql-agent';
+import { classifyProviderFailure, deadlineScale, planAnalystTurn, rerankCandidates, } from '@duckcodeailabs/dql-agent';
 import { buildAnalystLoopTools } from '../analyst-loop-tools.js';
-import { ClaudeProvider, KGStore, MemoryStore, defaultKgPath, defaultMemoryPath, GeminiProvider, loadAgentSemanticLayer, OllamaProvider, OpenAIProvider, answer, buildAnalysisQuestionPlan, buildLocalContextPack, contextRetrievalBudgetForQuestion, ensureAgentProjectReady, isLikelyClarificationReply, isTrustedConversationTurn, createProviderDispatchEgressReceipt, createProviderEgressReceipt, assertProviderPayloadAllowed, prepareProviderContextForDispatch, prepareProviderWireEnvelopeForDispatch, prepareServerOwnedProviderSchemaContext, projectEmbeddingProvider, answerAgentic, qualifyAuthorizationReferences, createAnalystLaneHandler, parseProposal, renderContextValidationRefusalForUser, validateSqlAgainstLocalContext, resolveOrchestratorPolicy, } from '@duckcodeailabs/dql-agent';
-import { CassetteStore, resolveCassetteModeFromEnv, withCassette } from '../../commands/agent-eval-cassette.js';
+import { ClaudeProvider, KGStore, MemoryStore, defaultKgPath, defaultMemoryPath, GeminiProvider, loadAgentSemanticLayer, OllamaProvider, OpenAIProvider, answer, buildAnalysisQuestionPlan, buildLocalContextPack, contextRetrievalBudgetForQuestion, ensureAgentProjectReady, isLikelyClarificationReply, isTrustedConversationTurn, createProviderDispatchEgressReceipt, createProviderEgressReceipt, assertProviderPayloadAllowed, prepareProviderContextForDispatch, prepareProviderWireEnvelopeForDispatch, prepareServerOwnedProviderSchemaContext, projectEmbeddingProvider, answerAgentic, qualifyAuthorizationReferences, scopeContextPackToExploratoryCandidateClosure, createAnalystLaneHandler, parseProposal, renderContextValidationRefusalForUser, validateSqlAgainstLocalContext, resolveOrchestratorPolicy, } from '@duckcodeailabs/dql-agent';
+import { CassetteStore, evalCassetteCanonicalizationV2, resolveCassetteModeFromEnv, withCassette, } from '../../commands/agent-eval-cassette.js';
 import { buildManifest, normalizeDqlArtifactReference, resolveDbtManifestPath } from '@duckcodeailabs/dql-core';
-import { existsSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { buildAnswerLoopTools, createGroundingContextExpander } from '../answer-loop-tools.js';
 import { getSemanticRuntimeStatus } from '../../semantic-runtime.js';
@@ -75,6 +76,39 @@ const SPECS = {
         },
     },
 };
+/**
+ * Capture a content-free provider failure at the closest boundary. Local
+ * runtime may later choose a user-facing headline, but must not need raw
+ * provider errors or URLs to reconstruct the cause.
+ */
+function providerBoundaryDiagnostic(input) {
+    const config = getEffectiveProviderConfig(input.projectRoot, input.providerId);
+    const message = input.error instanceof Error ? input.error.message : String(input.error ?? 'provider readiness failed');
+    const code = input.code
+        ?? (input.error && typeof input.error === 'object' ? String(input.error.code ?? '') : '');
+    const fingerprint = (value) => value?.trim()
+        ? `sha256:${createHash('sha256').update(value.trim()).digest('hex')}`
+        : undefined;
+    let origin;
+    if (config.baseUrl) {
+        try {
+            origin = new URL(config.baseUrl).origin;
+        }
+        catch {
+            // The full malformed URL never leaves this function; its fingerprint is
+            // still a useful support correlation key without disclosing content.
+            origin = config.baseUrl;
+        }
+    }
+    return classifyProviderFailure({
+        code,
+        message,
+        phase: input.phase,
+        providerFingerprint: fingerprint(input.providerId),
+        modelFingerprint: fingerprint(config.model),
+        baseOriginFingerprint: fingerprint(origin),
+    });
+}
 function createCertifiedFitConfirmation(provider, signal) {
     return async ({ question, questionPlan, block, fit }) => {
         const response = await provider.generate([
@@ -228,6 +262,40 @@ function stringArray(value) {
 function stringValue(value) {
     return typeof value === 'string' && value.trim().length > 0 ? value : undefined;
 }
+/**
+ * A precomputed exploratory pack is an optimization/witness only. The runner
+ * independently derives the pack from the immutable router-selected IDs and
+ * accepts the witness only when its snapshot, source fingerprint, physical
+ * relations, and metadata object set are exactly the same. This prevents a
+ * caller from replacing a safe same-snapshot closure with a broader one.
+ */
+function exploratoryClosureMatches(derived, witness) {
+    if (!derived)
+        return false;
+    if (derived.knowledgeLens.snapshotId !== witness.knowledgeLens.snapshotId)
+        return false;
+    if (derived.freshness.fingerprint !== witness.freshness.fingerprint)
+        return false;
+    const normalize = (value) => value
+        .trim()
+        .split('.')
+        .map((part) => part.trim().replace(/^["`\[]|["`\]]$/g, '').toLowerCase())
+        .filter(Boolean)
+        .join('.');
+    const sameSet = (left, right) => {
+        if (left.length !== right.length)
+            return false;
+        const rightSet = new Set(right);
+        return left.every((value) => rightSet.has(value));
+    };
+    const derivedRelations = [...new Set(derived.allowedSqlContext.relations.map((relation) => normalize(relation.relation)))].sort();
+    const witnessRelations = [...new Set(witness.allowedSqlContext.relations.map((relation) => normalize(relation.relation)))].sort();
+    if (!sameSet(derivedRelations, witnessRelations))
+        return false;
+    const derivedObjects = [...new Set(derived.objects.map((object) => object.objectKey))].sort();
+    const witnessObjects = [...new Set(witness.objects.map((object) => object.objectKey))].sort();
+    return sameSet(derivedObjects, witnessObjects);
+}
 function truncateForFitPrompt(value, max) {
     if (!value)
         return undefined;
@@ -279,16 +347,27 @@ function emitProposalFromText(text, emit) {
  * this one (local-runtime.ts:164), so reaching back would close an import cycle
  * through a 34k-line file. A few lines of JSON reading is the cheaper trade.
  *
- * Cached per project root because this runs on every turn and the answer is a
- * migration setting, not live state. A malformed file resolves to `null`, which
- * `resolveOrchestratorPolicy` turns into `legacy` — a broken config must not
- * route real questions onto an unproven path.
+ * Cached by a lightweight file fingerprint, not forever. Settings writes must
+ * take effect for the next Ask without requiring a notebook-server restart.
+ * A malformed file resolves to `null`, which `resolveOrchestratorPolicy` turns
+ * into `legacy` — a broken config must not route real questions onto an
+ * unproven path.
  */
 const agentConfigCache = new Map();
+function agentConfigFingerprint(projectRoot) {
+    try {
+        const stats = statSync(join(projectRoot, 'dql.config.json'));
+        return `${stats.dev}:${stats.ino}:${stats.size}:${stats.mtimeMs}`;
+    }
+    catch {
+        return 'missing';
+    }
+}
 function readAgentConfig(projectRoot) {
+    const fingerprint = agentConfigFingerprint(projectRoot);
     const cached = agentConfigCache.get(projectRoot);
-    if (cached !== undefined)
-        return cached;
+    if (cached && cached.fingerprint === fingerprint)
+        return cached.value;
     let resolved = null;
     try {
         const raw = readFileSync(join(projectRoot, 'dql.config.json'), 'utf-8');
@@ -300,7 +379,7 @@ function readAgentConfig(projectRoot) {
     catch {
         resolved = null;
     }
-    agentConfigCache.set(projectRoot, resolved);
+    agentConfigCache.set(projectRoot, { fingerprint, value: resolved });
     return resolved;
 }
 function readOrchestratorConfig(projectRoot) {
@@ -355,11 +434,43 @@ function valueLookupEnabled(projectRoot) {
 function agenticLaneForRequest(req) {
     return req.orchestrationMode === 'research' ? 'research' : 'generated';
 }
-export function applyEvalCassette(provider) {
+export function applyEvalCassette(provider, projectRoot) {
     const dir = process.env.DQL_EVAL_CASSETTE_DIR;
     if (!dir)
         return provider;
-    return withCassette(provider, new CassetteStore(dir), resolveCassetteModeFromEnv(process.env));
+    return withCassette(provider, new CassetteStore(dir), resolveCassetteModeFromEnv(process.env), evalCassetteCanonicalizationV2(projectRoot));
+}
+/**
+ * Create a replay-only provider when the runtime is launched for an offline
+ * evaluation. This is intentionally unavailable outside explicit cassette
+ * replay: recording and live modes still require a configured real provider.
+ *
+ * The cassette's recorded provider identity is part of its key. Recover it
+ * from a single-provider cassette directory instead of borrowing a user's
+ * active provider or guessing from an API setting. The base provider cannot
+ * make a network call; replay misses remain CassetteMissError failures.
+ */
+export function createEvalCassetteReplayProvider(projectRoot) {
+    const dir = process.env.DQL_EVAL_CASSETTE_DIR;
+    if (!dir || resolveCassetteModeFromEnv(process.env) !== 'replay')
+        return undefined;
+    const store = new CassetteStore(dir);
+    const providerNames = store.providerNames();
+    const providerName = providerNames.length === 1 ? asAgentProviderName(providerNames[0]) : undefined;
+    if (!providerName)
+        return undefined;
+    return withCassette({
+        name: providerName,
+        available: async () => true,
+        generate: async () => {
+            throw new Error('Eval cassette replay miss: no live provider is available.');
+        },
+    }, store, 'replay', evalCassetteCanonicalizationV2(projectRoot));
+}
+function asAgentProviderName(value) {
+    return value === 'claude' || value === 'openai' || value === 'gemini' || value === 'ollama'
+        ? value
+        : undefined;
 }
 /**
  * A raw text provider for planning calls that are not the answer itself.
@@ -373,7 +484,7 @@ export function createGovernedTextProvider(id, projectRoot) {
     if (!spec)
         return undefined;
     try {
-        return applyEvalCassette(spec.create(projectRoot));
+        return applyEvalCassette(spec.create(projectRoot), projectRoot);
     }
     catch {
         return undefined;
@@ -383,7 +494,7 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
     return {
         async run(req, emit, signal) {
             const spec = SPECS[id];
-            const rawProvider = applyEvalCassette(providerOverride ?? spec.create(req.projectRoot));
+            const rawProvider = applyEvalCassette(providerOverride ?? spec.create(req.projectRoot), req.projectRoot);
             const isResearch = req.orchestrationMode === 'research';
             const maxProviderDispatches = isResearch ? 8 : 4;
             const researchRowsOptIn = isResearch && req.researchResultRowsOptIn === true;
@@ -483,15 +594,41 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
                     return envelope;
                 },
             });
+            // One retry only, on the SAME configured provider and only for failures
+            // that are normally transient. The physical-dispatch observer remains in
+            // the path for both attempts, so a retry cannot exceed the run-wide
+            // dispatch budget or silently fail over to another provider.
+            let transientRetryUsed = false;
+            const mayRetrySameProvider = (error) => {
+                if (signal.aborted || transientRetryUsed)
+                    return false;
+                const code = error && typeof error === 'object' ? String(error.code ?? '') : '';
+                const message = error instanceof Error ? error.message : String(error ?? '');
+                const diagnostic = `${code} ${message}`;
+                return !/PROVIDER_DISPATCH_BUDGET|RUN_SOFT_TARGET|RUN_DEADLINE|PROJECT_SNAPSHOT|abort|cancel/i.test(diagnostic)
+                    && /(?:429|rate limit|too many requests|502|503|504|gateway|econn|network|fetch failed|connection refused|timeout|timed out)/i.test(diagnostic);
+            };
+            const retrySameProviderOnce = async (operation) => {
+                try {
+                    return await operation();
+                }
+                catch (error) {
+                    if (!mayRetrySameProvider(error))
+                        throw error;
+                    transientRetryUsed = true;
+                    emit({ kind: 'thinking', text: 'The configured AI provider had a transient error; retrying it once within this run budget.' });
+                    return operation();
+                }
+            };
             const provider = {
                 name: rawProvider.name,
                 available: () => rawProvider.available(),
                 generate: (...args) => {
-                    return rawProvider.generate(args[0], withPhysicalDispatchObserver(args[1]));
+                    return retrySameProviderOnce(() => rawProvider.generate(args[0], withPhysicalDispatchObserver(args[1])));
                 },
                 ...(rawProvider.generateWithTools ? {
                     generateWithTools: (...args) => {
-                        return rawProvider.generateWithTools(args[0], args[1], withPhysicalDispatchObserver(args[2]));
+                        return retrySameProviderOnce(() => rawProvider.generateWithTools(args[0], args[1], withPhysicalDispatchObserver(args[2])));
                     },
                 } : {}),
                 ...(rawProvider.generateStream ? {
@@ -502,7 +639,20 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
             };
             const available = await provider.available().catch(() => false);
             if (!available) {
-                emit({ kind: 'error', message: `${spec.label} is not configured or reachable. ${spec.setup}` });
+                const message = `${spec.label} is not configured or reachable. ${spec.setup}`;
+                emit({
+                    kind: 'error',
+                    message,
+                    providerDiagnostic: providerBoundaryDiagnostic({
+                        providerId: id,
+                        projectRoot: req.projectRoot,
+                        phase: 'preflight',
+                        error: message,
+                        // Local Ollama readiness is a reachability concern; configured
+                        // remote providers missing credentials are authentication issues.
+                        code: id === 'ollama' ? 'NETWORK_FAILURE' : 'AUTHENTICATION_FAILED',
+                    }),
+                });
                 return;
             }
             try {
@@ -633,6 +783,63 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
                     const schemaContext = req.getSchemaContext && shouldLoadSchemaContext(contextPack, Boolean(semanticLayer))
                         ? await req.getSchemaContext(question, contextPack).catch(() => [])
                         : [];
+                    // The router's exploratory candidate IDs are server-owned execution
+                    // authority. Once that tier is selected, provider prompt/schema
+                    // context must be the candidate closure rather than the broad
+                    // retrieval pack. The latter remains available to the host for
+                    // receipts only and cannot be used to introduce another relation.
+                    const forcedExploratoryTier = req.selectedCascadeTier === 'exploratory_sql';
+                    // Re-derive the closure from the broad immutable pack and the
+                    // router-selected IDs. `preparedExploratoryContextPack` is only a
+                    // server-side consistency witness; it cannot override or widen the
+                    // derivation even if a future caller constructs an AgentRunner
+                    // request directly.
+                    const derivedExploratoryContextPack = forcedExploratoryTier
+                        ? scopeContextPackToExploratoryCandidateClosure(contextPack, req.exploratoryCandidateIds)
+                        : undefined;
+                    const closureWitnessMatches = !req.preparedExploratoryContextPack
+                        || exploratoryClosureMatches(derivedExploratoryContextPack, req.preparedExploratoryContextPack);
+                    const exploratoryContextPack = closureWitnessMatches
+                        ? derivedExploratoryContextPack
+                        : undefined;
+                    if (forcedExploratoryTier && (!exploratoryContextPack || !req.exploratoryCandidateIds?.length)) {
+                        const text = 'The router-selected exploratory path no longer has a complete same-snapshot physical closure, so DQL did not send SQL generation or execute a query.';
+                        emit({
+                            kind: 'tool_result',
+                            id: 'governed_answer',
+                            output: {
+                                kind: 'no_answer',
+                                sourceTier: 'no_answer',
+                                certification: 'analyst_review_required',
+                                reviewStatus: 'none',
+                                confidence: 0,
+                                text,
+                                answer: text,
+                                refusalCode: 'grounding_gap',
+                                refusalDetails: {
+                                    code: closureWitnessMatches ? 'EXPLORATORY_CLOSURE_UNAVAILABLE' : 'EXPLORATORY_CLOSURE_MISMATCH',
+                                    message: text,
+                                },
+                                contextPack,
+                                providerUsed: provider.name,
+                            },
+                        });
+                        return;
+                    }
+                    const answerContextPack = forcedExploratoryTier
+                        ? exploratoryContextPack ?? contextPack
+                        : contextPack;
+                    const normalizeQualifiedRelation = (value) => value
+                        .trim()
+                        .split('.')
+                        .map((part) => part.trim().replace(/^["`\[]|["`\]]$/g, '').toLowerCase())
+                        .filter(Boolean)
+                        .join('.');
+                    const closureRelations = new Set((exploratoryContextPack?.allowedSqlContext.relations ?? [])
+                        .map((relation) => normalizeQualifiedRelation(relation.relation)));
+                    const answerSchemaContext = forcedExploratoryTier && closureRelations.size > 0
+                        ? schemaContext.filter((table) => closureRelations.has(normalizeQualifiedRelation(table.relation)))
+                        : schemaContext;
                     const schemaDurationMs = Date.now() - schemaStartedAt;
                     const selectedBlockHints = shouldUseSelectedBlockHint(req, question, followUp)
                         ? extractSelectedBlockHints(req)
@@ -655,8 +862,8 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
                         question,
                         ...(conversationSnapshot ? { conversationSnapshot } : {}),
                         ...(memoryContext ? { memoryContext } : {}),
-                        schemaContext: prepareServerOwnedProviderSchemaContext(schemaContext),
-                        ...(contextPack ? { contextPack } : {}),
+                        schemaContext: prepareServerOwnedProviderSchemaContext(answerSchemaContext),
+                        ...(answerContextPack ? { contextPack: answerContextPack } : {}),
                         skills,
                         ...(followUp ? { followUp } : {}),
                     }), {
@@ -672,6 +879,12 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
                         ...(req.resolvedAnalyticalPlan
                             ? { resolvedAnalyticalPlan: req.resolvedAnalyticalPlan }
                             : {}),
+                        ...(req.selectedCascadeTier
+                            ? { selectedCascadeTier: req.selectedCascadeTier }
+                            : {}),
+                        ...(req.exploratoryCandidateIds?.length
+                            ? { exploratoryCandidateIds: [...req.exploratoryCandidateIds] }
+                            : {}),
                         ...(req.generatedProposalTargetFingerprint
                             ? { generatedProposalTargetFingerprint: req.generatedProposalTargetFingerprint }
                             : {}),
@@ -692,7 +905,7 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
                         followUp,
                         conversationSnapshot,
                         memoryContext,
-                        schemaContext,
+                        schemaContext: answerSchemaContext,
                         semanticLayer,
                         // Runtime-aware executability for metric SELECTION: with a full
                         // semantic runtime active (dbt Cloud / MetricFlow CLI) every
@@ -704,7 +917,7 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
                                 canExecuteSemanticMetric: (metricName) => semanticRuntimeActive !== 'native' || semanticLayer.canComposeMetric(metricName),
                             }
                             : {}),
-                        contextPack,
+                        contextPack: answerContextPack,
                         // The project's configured embedder (dql.config.json ai.embeddings).
                         // Without it, matchSemanticMetric falls back to the offline hashed
                         // provider, whose vectors can never ground a match on similarity
@@ -726,6 +939,28 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
                         executeGeneratedSql: req.executeGeneratedSql
                             ? async (...args) => { guardSnapshot(); sqlExecutions += 1; return req.executeGeneratedSql(...args); }
                             : undefined,
+                        prepareExploratorySqlExecution: req.prepareExploratorySqlExecution
+                            ? async (sql, ...args) => {
+                                guardSnapshot();
+                                // The execution host repeats this validation immediately
+                                // before capability minting. Keep the same exact-qualified
+                                // closure check here as well, before the provider runner can
+                                // even invoke that host boundary. A provider response cannot
+                                // use another same-snapshot relation merely because it was
+                                // present in broad retrieval diagnostics.
+                                if (forcedExploratoryTier && exploratoryContextPack) {
+                                    const proposalValidation = validateSqlAgainstLocalContext(sql, exploratoryContextPack, {
+                                        runtimeSchema: answerSchemaContext,
+                                    });
+                                    const outsideClosure = !proposalValidation.ok
+                                        || proposalValidation.referencedRelations.some((relation) => !closureRelations.has(normalizeQualifiedRelation(relation)));
+                                    if (outsideClosure) {
+                                        throw Object.assign(new Error('The generated SQL references a relation outside the router-selected physical closure, so it was not executed.'), { code: 'UNAUTHORIZED_SQL' });
+                                    }
+                                }
+                                return req.prepareExploratorySqlExecution(sql, ...args);
+                            }
+                            : undefined,
                         executeAgenticGeneratedSql: req.executeAgenticGeneratedSql
                             ? async (capability, sql, artifact) => {
                                 guardSnapshot();
@@ -985,6 +1220,19 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
                     dispatchEvidence: dispatchEvidence(orchestrationBudgetExhausted ? 'orchestration_budget_exhausted'
                         : snapshotDrift ? 'project_snapshot_mismatch'
                             : 'provider_error'),
+                    providerDiagnostic: providerBoundaryDiagnostic({
+                        providerId: id,
+                        projectRoot: req.projectRoot,
+                        phase: orchestrationBudgetExhausted
+                            ? 'planning'
+                            : 'generation',
+                        error: err,
+                        code: orchestrationBudgetExhausted
+                            ? 'PROVIDER_DISPATCH_BUDGET'
+                            : snapshotDrift
+                                ? 'ADMISSION_DENIED'
+                                : budgetCode,
+                    }),
                 });
             }
         },
@@ -2088,6 +2336,8 @@ export const __test__ = {
     shouldSearchProjectFiles,
     renderProjectSourceSearch,
     researchDispatchPurposeForTool,
+    readAgentConfig,
+    providerBoundaryDiagnostic,
 };
 function researchDispatchPurposeForTool(toolName) {
     return toolName === 'execute_local_analysis' ? 'research_tool' : 'research_narration';