@duckcodeailabs/dql-cli 1.12.1 → 1.12.2

package/dist/local-runtime.js

@@ -40,7 +40,7 @@ import { observeWarehouseTargetIdentity } from './semantic-execution/connection-
 import { configuredWarehouseTargetIdentity } from './semantic-execution/connection-identity.js';
 import { executeTargetBoundSemanticQuery, semanticExecutionFailureCode, semanticExecutionFailureDetails, } from './semantic-execution/execution-gateway.js';
 import { buildSemanticTargetBinding } from './semantic-execution/target-binding.js';
-import { normalizeConnectionMetadataScope, syncWarehouseMetadata, warehouseMetadataStatus, } from './warehouse-metadata.js';
+import { discoverWarehouseMetadataScopes, normalizeConnectionMetadataScope, syncWarehouseMetadata, warehouseMetadataStatus, } from './warehouse-metadata.js';
 import { NotebookDatasetWorkspace, } from "./notebook-datasets.js";
 import { prepareBlockInvocation } from './block-invocation.js';
 const NOTEBOOK_EXECUTE_PREVIEW_ROW_LIMIT = 500;
@@ -204,6 +204,18 @@ export function parseAgentRunRequestBody(body) {
     if (!question)
         return { error: 'question is required.' };
     const selectedObject = parseAgentRunSelectedObject(record.selectedObject);
+    const rawExecutionTarget = agentRunRecord(record.executionTarget)
+        ?? agentRunRecord(agentRunRecord(record.workspaceContext)?.executionTarget);
+    const executionTarget = rawExecutionTarget?.target === 'local'
+        ? { target: 'local' }
+        : rawExecutionTarget?.target === 'connection'
+            ? {
+                target: 'connection',
+                ...(agentRunString(rawExecutionTarget.connectionName)
+                    ? { connectionName: agentRunString(rawExecutionTarget.connectionName) }
+                    : {}),
+            }
+            : undefined;
     const workspaceContext = agentRunRecord(record.workspaceContext) ?? agentRunRecord(record.context);
     const signals = agentRunRecord(record.signals);
     const requestedMode = parseAgentRunRequestedMode(record.requestedMode) ?? parseAgentRunRequestedMode(record.mode);
@@ -219,6 +231,7 @@ export function parseAgentRunRequestBody(body) {
             intent: agentRunString(record.intent),
             signals: signals,
             selectedObject,
+            executionTarget,
             workspaceContext,
             conversationContext: agentRunRecord(record.conversationContext),
             history: parseAgentRunHistory(record.history),
@@ -887,6 +900,7 @@ export async function startLocalServer(opts) {
         }
         return requireActiveConnection(isConnectionConfig(body.connection) ? body.connection : connection);
     };
+    const resolveAgentRunExecutionConnection = (request) => resolveExecutionConnection(request.executionTarget ? { executionTarget: request.executionTarget } : {});
     const executionTargetDescriptor = (body) => {
         const target = body.executionTarget && typeof body.executionTarget === 'object'
             ? body.executionTarget
@@ -1312,15 +1326,18 @@ export async function startLocalServer(opts) {
         // Best-effort active warehouse dialect so Lane-2 semantic compiles emit
         // dialect-correct SQL (e.g. DATE_TRUNC / identifier quoting). Absent when no
         // connection is configured — the compiler then uses its default dialect.
-        let semanticDriver;
         let semanticConnection;
         try {
-            semanticConnection = requireActiveConnection();
-            semanticDriver = semanticConnection.driver;
+            semanticConnection = await resolveAgentRunExecutionConnection(request);
         }
-        catch {
-            semanticDriver = undefined;
+        catch (error) {
+            // An explicit target is a contract and must fail closed. Without one,
+            // conversational/non-data runs retain the existing no-connection path;
+            // any later analytical execution will surface the normal setup action.
+            if (request.executionTarget)
+                throw error;
         }
+        const semanticDriver = semanticConnection?.driver;
         const semanticTableMapping = semanticLayer && semanticConnection
             ? await resolveSemanticTableMapping(executor, semanticConnection, semanticLayer, projectRoot)
             : undefined;
@@ -1510,10 +1527,12 @@ export async function startLocalServer(opts) {
                 ? { resolvedAnalyticalPlan: routeDecision.resolvedAnalyticalPlan }
                 : {}),
             analyticalReferenceInstant: new Date().toISOString(),
-            executeCertifiedBlock: executeCertifiedBlockForAgent,
-            executeGeneratedSql: (sql, artifact) => executeGeneratedArtifactForAgent(request.question, sql, artifact),
-            executeDqlArtifact: (artifact) => executeArtifactReferenceForAgent(artifact, request.question),
-            getSchemaContext: getSchemaContextForAgent,
+            executeCertifiedBlock: (node, invocation) => executeCertifiedBlockForAgent(node, invocation, semanticConnection),
+            executeGeneratedSql: (sql, artifact) => executeGeneratedArtifactForAgent(request.question, sql, artifact, semanticConnection),
+            executeDqlArtifact: (artifact) => executeArtifactReferenceForAgent(artifact, request.question, semanticConnection),
+            getSchemaContext: (question, preparedContextPack) => getSchemaContextForAgent(question, preparedContextPack, semanticConnection, request.executionTarget?.target === 'connection'
+                ? request.executionTarget.connectionName
+                : undefined),
         }, (turn) => {
             if (turn.kind === 'thinking')
                 onProgress?.(turn.text);
@@ -1762,7 +1781,7 @@ export async function startLocalServer(opts) {
                     }));
                 const exploration = await executeExploratoryCandidate(governedAnswer.exploratoryCandidate, explorationSchema, request.question, governedAnswer.contextPack?.questionPlan.requestedShape.topN?.scope === 'overall'
                     ? governedAnswer.contextPack.questionPlan.requestedShape.topN.n
-                    : undefined);
+                    : undefined, await resolveAgentRunExecutionConnection(request));
                 const probeSummary = exploration.proofs.length > 0
                     ? `${exploration.proofs.length} bounded join probe${exploration.proofs.length === 1 ? '' : 's'} completed.`
                     : 'No join probe was required for this query.';
@@ -2976,7 +2995,7 @@ export async function startLocalServer(opts) {
             cells: snapshotCells,
         });
     };
-    const executeDqlArtifactSourceForAgent = async (source, metadata = {}, invocationInput) => {
+    const executeDqlArtifactSourceForAgent = async (source, metadata = {}, invocationInput, executionConnection) => {
         const invocation = prepareBlockInvocation({
             source,
             parameters: invocationInput?.parameters,
@@ -2989,7 +3008,7 @@ export async function startLocalServer(opts) {
         if (invocation.unresolvedParameters.length > 0) {
             throw new Error(`I need values for: ${invocation.unresolvedParameters.join(', ')}.`);
         }
-        const activeConnection = requireActiveConnection();
+        const activeConnection = requireActiveConnection(executionConnection);
         const precompiledSemanticQuery = Boolean(extractBlockStudioSql(source));
         const tableMapping = !precompiledSemanticQuery
             ? await resolveSemanticTableMapping(executor, activeConnection, semanticLayer, projectRoot)
@@ -3061,7 +3080,7 @@ export async function startLocalServer(opts) {
             } : {}),
         };
     };
-    const executeCertifiedBlockByNameForAgent = async (blockName, invocationInput, requireCertified = false) => {
+    const executeCertifiedBlockByNameForAgent = async (blockName, invocationInput, requireCertified = false, executionConnection) => {
         const manifest = buildManifest({ projectRoot });
         const block = manifest.blocks[blockName];
         if (!block) {
@@ -3076,7 +3095,7 @@ export async function startLocalServer(opts) {
             path: block.filePath,
             domain: block.domain,
             chartType: block.chartType,
-        }, invocationInput);
+        }, invocationInput, executionConnection);
         return {
             ...result,
             dqlArtifact: {
@@ -3095,17 +3114,17 @@ export async function startLocalServer(opts) {
             },
         };
     };
-    const executeCertifiedBlockForAgent = async (node, invocationInput) => {
+    const executeCertifiedBlockForAgent = async (node, invocationInput, executionConnection) => {
         if (node.kind !== 'block') {
             throw new Error(`Certified ${node.kind} "${node.name}" is a navigation artifact and cannot be executed as a block.`);
         }
-        return executeCertifiedBlockByNameForAgent(node.name || node.nodeId.replace(/^block:/, ''), invocationInput);
+        return executeCertifiedBlockByNameForAgent(node.name || node.nodeId.replace(/^block:/, ''), invocationInput, false, executionConnection);
     };
     // Secondary agent surfaces use this compatibility callback. Delegate to the
     // same artifact-first path as Ask so research/app/notebook execution cannot
     // silently reintroduce a raw-SQL result followed by a different DQL artifact.
     const executeGeneratedSqlForAgent = async (sql, artifact) => executeGeneratedArtifactForAgent(artifact?.name ?? 'AI-generated query', sql, artifact);
-    const executeArtifactReferenceForAgent = async (artifact, question) => {
+    const executeArtifactReferenceForAgent = async (artifact, question, executionConnection) => {
         const invocation = prepareBlockInvocation({
             source: artifact.source,
             parameters: artifact.parameterValues,
@@ -3120,7 +3139,7 @@ export async function startLocalServer(opts) {
             question,
             parameters: invocation.values,
             rowLimit: artifact.limit ?? 200,
-        });
+        }, executionConnection);
         return {
             ...result,
             dqlArtifact: {
@@ -3132,9 +3151,9 @@ export async function startLocalServer(opts) {
             },
         };
     };
-    const executeGeneratedArtifactForAgent = async (question, sql, seed) => {
+    const executeGeneratedArtifactForAgent = async (question, sql, seed, executionConnection) => {
         const artifact = generatedSqlArtifactContract(question, sql, seed);
-        return executeArtifactReferenceForAgent({ ...artifact, limit: seed?.limit ?? artifact.limit ?? 200 }, question);
+        return executeArtifactReferenceForAgent({ ...artifact, limit: seed?.limit ?? artifact.limit ?? 200 }, question, executionConnection);
     };
     /**
      * EXP-001: execution host for the deliberately narrow non-governed lane.
@@ -3144,8 +3163,8 @@ export async function startLocalServer(opts) {
      * existing read-only 200-row preview. Any malformed, broad, or unsupported
      * candidate remains review-required and is not executed automatically.
      */
-    const executeExploratoryCandidate = async (candidate, schemaContext = [], question = '', requestedTopN) => {
-        const activeConnection = requireActiveConnection();
+    const executeExploratoryCandidate = async (candidate, schemaContext = [], question = '', requestedTopN, executionConnection) => {
+        const activeConnection = requireActiveConnection(executionConnection);
         const preflight = repairExploratorySqlBeforeExecution(candidate.sql, schemaContext, question, activeConnection.driver);
         const boundedSql = applyRequestedTopNToExploratorySql(preflight.sql, requestedTopN);
         const repairs = boundedSql === preflight.sql
@@ -3236,26 +3255,27 @@ export async function startLocalServer(opts) {
                     return { proofs, sql: boundedSql, repairs, error: contradiction };
                 }
             }
-            const result = await executeGeneratedArtifactForAgent(question, boundedSql);
+            const result = await executeGeneratedArtifactForAgent(question, boundedSql, undefined, activeConnection);
             return { result, proofs, sql: boundedSql, repairs };
         }
         catch (error) {
             return { proofs, sql: boundedSql, repairs, error: error instanceof Error ? error.message : String(error) };
         }
     };
-    const getSchemaContextForAgent = async (question, preparedContextPack) => {
+    const getSchemaContextForAgent = async (question, preparedContextPack, executionConnection, executionConnectionName) => {
+        const schemaConnection = executionConnection ?? connection;
         const scanRuntimeSchema = async () => {
-            if (!connection)
+            if (!schemaConnection)
                 return { ranked: [], snapshot: [] };
-            const result = await executor.executePositional(buildRuntimeSchemaSearchSql(question), [], connection, { maxRows: 600, maxBytes: 2 * 1024 * 1024, batchSize: 200, deadlineMs: 30_000 });
+            const result = await executor.executePositional(buildRuntimeSchemaSearchSql(question), [], schemaConnection, { maxRows: 600, maxBytes: 2 * 1024 * 1024, batchSize: 200, deadlineMs: 30_000 });
             return {
                 ranked: buildAgentSchemaContext(question, result.rows),
                 snapshot: buildAgentSchemaContext(question, result.rows, { includeUnscored: true, limit: 100 }),
             };
         };
         const catalogContext = await buildAgentSchemaContextFromCatalog(projectRoot, question, preparedContextPack).catch(() => []);
-        const activeScope = connection
-            ? optionalActiveConnectionMetadataScope(projectRoot, projectConfig, connection, projectConfig.defaultConnectionName ?? 'default')
+        const activeScope = schemaConnection
+            ? optionalActiveConnectionMetadataScope(projectRoot, projectConfig, schemaConnection, executionConnectionName ?? projectConfig.defaultConnectionName ?? 'default')
             : null;
         const activeRuntimeSnapshot = latestRuntimeSchemaSnapshotForProject(projectRoot);
         const hasActivatedMetadataGeneration = Boolean(activeScope
@@ -3263,12 +3283,12 @@ export async function startLocalServer(opts) {
             && activeRuntimeSnapshot.status !== 'stale');
         const valueGrounding = resolveAgentRuntimeValueGrounding(projectConfig);
         if (catalogContext.length > 0) {
-            if (!connection || valueGrounding.mode !== 'safe_automatic')
+            if (!schemaConnection || valueGrounding.mode !== 'safe_automatic')
                 return catalogContext;
             // The immutable dbt/DQL snapshot already owns schema discovery. A named
             // row value must not turn a warm Ask into an information_schema scan over
             // thousands of enterprise tables; only field-scoped value probes are live.
-            const enriched = await enrichAgentSchemaContextWithValueMatches(question, catalogContext, executor, connection, valueGrounding.searchSafeColumns);
+            const enriched = await enrichAgentSchemaContextWithValueMatches(question, catalogContext, executor, schemaConnection, valueGrounding.searchSafeColumns);
             if (!hasActivatedMetadataGeneration) {
                 recordAgentRuntimeSchemaSnapshot(projectRoot, catalogContext, 'catalog runtime schema');
             }
@@ -3280,12 +3300,12 @@ export async function startLocalServer(opts) {
         // user may explicitly refresh the selected scope.
         if (hasActivatedMetadataGeneration)
             return [];
-        if (!connection)
+        if (!schemaConnection)
             return [];
         try {
             const schemaContext = await scanRuntimeSchema();
             const enriched = valueGrounding.mode === 'safe_automatic'
-                ? await enrichAgentSchemaContextWithValueMatches(question, schemaContext.ranked, executor, connection, valueGrounding.searchSafeColumns)
+                ? await enrichAgentSchemaContextWithValueMatches(question, schemaContext.ranked, executor, schemaConnection, valueGrounding.searchSafeColumns)
                 : schemaContext.ranked;
             recordAgentRuntimeSchemaSnapshot(projectRoot, schemaContext.snapshot, 'question-scoped information_schema search');
             return enriched;
@@ -6732,6 +6752,7 @@ export async function startLocalServer(opts) {
                         hintId,
                         title: typeof body.title === 'string' ? body.title : undefined,
                         guidance: typeof body.guidance === 'string' ? body.guidance : undefined,
+                        lesson: parseHintLessonInput(body.lesson),
                         correctedSql: typeof body.correctedSql === 'string' ? body.correctedSql : undefined,
                         scope: rawScope ? {
                             metric: scopeValue('metric'),
@@ -6911,6 +6932,7 @@ export async function startLocalServer(opts) {
                         requiredEvaluation: correctionEvaluation,
                         hintTitle: typeof body.title === 'string' && body.title.trim() ? body.title.trim() : undefined,
                         hintGuidance: typeof body.guidance === 'string' && body.guidance.trim() ? body.guidance.trim() : undefined,
+                        lesson: parseHintLessonInput(body.lesson),
                         tags: Array.isArray(body.tags) ? body.tags.map(String) : undefined,
                     });
                     // `approve` is intentionally ignored: capture never promotes a hint.
@@ -9824,8 +9846,32 @@ export async function startLocalServer(opts) {
                 return;
             }
             const metadataScopePreviewMatch = path.match(/^\/api\/connections\/([^/]+)\/metadata-scope\/preview$/);
+            const metadataDiscoveryMatch = path.match(/^\/api\/connections\/([^/]+)\/metadata-scope\/discovery$/);
             const metadataScopeMatch = path.match(/^\/api\/connections\/([^/]+)\/metadata-scope$/);
             const metadataSyncMatch = path.match(/^\/api\/connections\/([^/]+)\/metadata-sync$/);
+            if (metadataDiscoveryMatch && req.method === 'POST') {
+                try {
+                    const connectionId = decodeURIComponent(metadataDiscoveryMatch[1]);
+                    const cfg = loadProjectConfig(projectRoot);
+                    const selectedConnection = projectConnectionById(projectRoot, cfg, connectionId);
+                    if (!selectedConnection)
+                        throw new Error(`Unknown connection "${connectionId}".`);
+                    const defaults = metadataScopeDbtDefaults(projectRoot, cfg);
+                    const discovery = await discoverWarehouseMetadataScopes({
+                        connectionId,
+                        executor,
+                        connection: selectedConnection,
+                        dbtRelations: defaults.relations,
+                    });
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(discovery));
+                }
+                catch (error) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+                }
+                return;
+            }
             if (metadataScopePreviewMatch && req.method === 'POST') {
                 try {
                     const connectionId = decodeURIComponent(metadataScopePreviewMatch[1]);
@@ -15438,6 +15484,24 @@ function internalDqlRelationIdValidationError(sql, subject) {
         return null;
     return `${subject} contains internal DQL graph relation identifier${internalIds.length === 1 ? '' : 's'} ${internalIds.join(', ')}. Use the physical database.schema.table relation instead, or choose Ask AI to fix from the notebook error.`;
 }
+function parseHintLessonInput(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const raw = value;
+    const stringList = (field) => Array.isArray(raw[field])
+        ? raw[field].filter((item) => typeof item === 'string')
+        : undefined;
+    return {
+        version: 1,
+        category: typeof raw.category === 'string'
+            ? raw.category
+            : undefined,
+        rule: typeof raw.rule === 'string' ? raw.rule : undefined,
+        intentExamples: stringList('intentExamples'),
+        avoid: stringList('avoid'),
+        expectedOutcome: typeof raw.expectedOutcome === 'string' ? raw.expectedOutcome : undefined,
+    };
+}
 class DqlInternalRelationIdError extends Error {
     name = 'DqlInternalRelationIdError';
 }