@duckcodeailabs/dql-cli 1.6.3 → 1.6.4

package/dist/local-runtime.js

@@ -4,7 +4,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, wat
 import { homedir } from 'node:os';
 import { dirname, extname, join, normalize, relative, resolve } from 'node:path';
 import { buildExecutionPlan, createWelcomeNotebook, deserializeNotebook, getConnectorFormSchemas, hasSemanticRefs, resolveSemanticRefs, } from '@duckcodeailabs/dql-notebook';
-import { loadSemanticLayerFromDir, resolveSemanticLayerAsync, Parser, buildLineageGraph, buildManifest, findAppDocuments, findDashboardsForApp, isBlockIdRef, loadAppDocument, loadDashboardDocument, analyzeImpact, buildTrustChain, detectDomainFlows, getDomainTrustOverview, queryLineage, queryCompleteLineagePaths, LineageGraph, canonicalize, canonicalizeNotebook, diffDQL, diffNotebook, } from '@duckcodeailabs/dql-core';
+import { loadSemanticLayerFromDir, resolveSemanticLayerAsync, getDialect, Parser, buildLineageGraph, buildManifest, findAppDocuments, findDashboardsForApp, isBlockIdRef, loadAppDocument, loadDashboardDocument, analyzeImpact, buildTrustChain, detectDomainFlows, getDomainTrustOverview, queryLineage, queryCompleteLineagePaths, LineageGraph, canonicalize, canonicalizeNotebook, diffDQL, diffNotebook, } from '@duckcodeailabs/dql-core';
 import { load as loadYaml } from 'js-yaml';
 import { listBlockTemplates } from './block-templates.js';
 import { getRunner as getLLMRunner } from './llm/index.js';
@@ -239,12 +239,67 @@ export async function startLocalServer(opts) {
          FROM information_schema.columns
          WHERE table_schema NOT IN ('information_schema', 'pg_catalog')
          ORDER BY table_schema, table_name, ordinal_position`, [], runtimeVariables({}), connection);
-            return buildAgentSchemaContext(question, result.rows);
+            const schemaContext = buildAgentSchemaContext(question, result.rows);
+            return enrichAgentSchemaContextWithValueMatches(question, schemaContext, executor, connection);
         }
         catch {
             return [];
         }
     };
+    const generateInvestigationSqlForApp = async (input) => {
+        const resolvedProvider = resolveDefaultLLMProvider(projectRoot);
+        const runner = resolvedProvider ? getLLMRunner(resolvedProvider) : null;
+        if (!resolvedProvider || !runner) {
+            throw new Error('No AI provider is configured. Configure OpenAI, Gemini, Ollama, or a custom OpenAI-compatible endpoint in Settings.');
+        }
+        let governedAnswer;
+        let providerError;
+        const contextEnvelope = {
+            mode: 'app_research',
+            intent: input.intent,
+            appId: input.appId,
+            dashboardId: input.dashboardId,
+            sourceTileId: input.sourceTileId,
+            sourceBlockId: input.sourceBlockId,
+            title: input.title,
+            instruction: 'Generate review-required read-only SQL when certified blocks do not exactly answer the requested research grain. Execute only through the bounded generated SQL preview path.',
+            context: input.context,
+        };
+        const controller = new AbortController();
+        await runner.run({
+            provider: resolvedProvider,
+            messages: [{ role: 'user', content: input.question }],
+            upstream: {
+                cellId: `app-research:${input.appId}:${input.dashboardId ?? 'app'}`,
+                sql: JSON.stringify(contextEnvelope, null, 2),
+            },
+            projectRoot,
+            executeCertifiedBlock: executeCertifiedBlockForAgent,
+            executeGeneratedSql: executeGeneratedSqlForAgent,
+            getSchemaContext: getSchemaContextForAgent,
+        }, (turn) => {
+            if (turn.kind === 'tool_result' && turn.id === 'governed_answer') {
+                governedAnswer = turn.output;
+            }
+            if (turn.kind === 'error') {
+                providerError = turn.message;
+            }
+        }, controller.signal);
+        if (!governedAnswer) {
+            throw new Error(providerError ?? 'The AI provider did not return a governed answer.');
+        }
+        return {
+            sql: governedAnswer.proposedSql ?? governedAnswer.sql,
+            answer: governedAnswer.answer ?? governedAnswer.text,
+            result: governedAnswer.result,
+            analysisPlan: governedAnswer.analysisPlan,
+            evidence: governedAnswer.evidence,
+            citations: governedAnswer.citations,
+            suggestedViz: governedAnswer.suggestedViz,
+            executionError: governedAnswer.executionError,
+            providerUsed: governedAnswer.providerUsed,
+        };
+    };
     // SSE clients for /api/watch hot-reload
     const sseClients = new Set();
     // Watch notebooks/, workbooks/, semantic-layer/, and data/ dirs for changes
@@ -303,6 +358,17 @@ export async function startLocalServer(opts) {
         ...candidate,
         validation: validateBlockStudioSource(candidate.dqlSource, semanticLayer),
     });
+    const validateImportCandidateForSave = (candidate) => {
+        const validated = validateImportCandidate(candidate);
+        const diagnostics = (validated.validation?.diagnostics ?? []);
+        const errors = diagnostics
+            .filter((diagnostic) => diagnostic.severity === 'error')
+            .map((diagnostic) => diagnostic.message || 'Candidate validation failed.');
+        if (validated.reviewStatus === 'rejected') {
+            errors.unshift('Candidate was rejected.');
+        }
+        return { candidate: validated, errors };
+    };
     const runBlockStudioPreviewSource = async (source, targetConnection = connection) => {
         let tableMapping;
         if (semanticLayer) {
@@ -777,6 +843,7 @@ export async function startLocalServer(opts) {
                     path,
                     projectRoot,
                     executeSql: executeLocalSqlForStoredResult,
+                    generateInvestigationSql: generateInvestigationSqlForApp,
                     runNotebook: (appId, notebookPath) => runNotebookForApp(appId, notebookPath),
                 });
                 if (handled)
@@ -1514,25 +1581,32 @@ export async function startLocalServer(opts) {
                 const nextCandidates = [...session.candidates];
                 for (let i = 0; i < nextCandidates.length; i += 1) {
                     const candidate = nextCandidates[i];
-                    if (candidate.reviewStatus === 'saved' || candidate.reviewStatus === 'rejected' || candidate.validation?.valid === false)
+                    if (candidate.reviewStatus === 'saved' || candidate.reviewStatus === 'rejected')
+                        continue;
+                    const readiness = validateImportCandidateForSave(candidate);
+                    nextCandidates[i] = readiness.candidate;
+                    writeBlockStudioImportCandidate(projectRoot, importId, readiness.candidate);
+                    if (readiness.errors.length > 0) {
+                        errors.push({ candidateId: candidate.id, error: readiness.errors.join(' ') });
                         continue;
+                    }
                     try {
                         const savedPath = saveBlockStudioArtifacts(projectRoot, {
-                            source: candidate.dqlSource,
-                            name: candidate.name,
-                            domain: candidate.domain,
-                            description: candidate.description,
-                            owner: candidate.owner,
-                            tags: candidate.tags,
-                            lineage: candidate.lineage.sourceTables,
+                            source: readiness.candidate.dqlSource,
+                            name: readiness.candidate.name,
+                            domain: readiness.candidate.domain,
+                            description: readiness.candidate.description,
+                            owner: readiness.candidate.owner,
+                            tags: readiness.candidate.tags,
+                            lineage: readiness.candidate.lineage.sourceTables,
                             importMeta: {
                                 importId,
-                                candidateId: candidate.id,
-                                sourceKind: candidate.sourceKind,
-                                sourcePath: candidate.sourcePath,
+                                candidateId: readiness.candidate.id,
+                                sourceKind: readiness.candidate.sourceKind,
+                                sourcePath: readiness.candidate.sourcePath,
                             },
                         });
-                        nextCandidates[i] = { ...candidate, reviewStatus: 'saved', savedPath };
+                        nextCandidates[i] = { ...readiness.candidate, reviewStatus: 'saved', savedPath };
                         writeBlockStudioImportCandidate(projectRoot, importId, nextCandidates[i]);
                         saved.push({ candidateId: candidate.id, path: savedPath });
                     }
@@ -1625,22 +1699,39 @@ export async function startLocalServer(opts) {
                 }
                 if (req.method === 'POST' && candidateId && action === 'save') {
                     const candidate = readBlockStudioImportCandidate(projectRoot, importId, candidateId);
+                    if (candidate.reviewStatus === 'saved' && candidate.savedPath) {
+                        const payload = openBlockStudioDocument(projectRoot, candidate.savedPath, semanticLayer);
+                        res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ candidate, block: payload }));
+                        return;
+                    }
+                    const readiness = validateImportCandidateForSave(candidate);
+                    if (readiness.errors.length > 0) {
+                        writeBlockStudioImportCandidate(projectRoot, importId, readiness.candidate);
+                        res.writeHead(422, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({
+                            error: readiness.errors.join(' '),
+                            candidate: readiness.candidate,
+                            diagnostics: readiness.candidate.validation?.diagnostics ?? [],
+                        }));
+                        return;
+                    }
                     const savedPath = saveBlockStudioArtifacts(projectRoot, {
-                        source: candidate.dqlSource,
-                        name: candidate.name,
-                        domain: candidate.domain,
-                        description: candidate.description,
-                        owner: candidate.owner,
-                        tags: candidate.tags,
-                        lineage: candidate.lineage.sourceTables,
+                        source: readiness.candidate.dqlSource,
+                        name: readiness.candidate.name,
+                        domain: readiness.candidate.domain,
+                        description: readiness.candidate.description,
+                        owner: readiness.candidate.owner,
+                        tags: readiness.candidate.tags,
+                        lineage: readiness.candidate.lineage.sourceTables,
                         importMeta: {
                             importId,
                             candidateId,
-                            sourceKind: candidate.sourceKind,
-                            sourcePath: candidate.sourcePath,
+                            sourceKind: readiness.candidate.sourceKind,
+                            sourcePath: readiness.candidate.sourcePath,
                         },
                     });
-                    const next = { ...candidate, reviewStatus: 'saved', savedPath };
+                    const next = { ...readiness.candidate, reviewStatus: 'saved', savedPath };
                     writeBlockStudioImportCandidate(projectRoot, importId, next);
                     const payload = openBlockStudioDocument(projectRoot, savedPath, semanticLayer);
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
@@ -1664,11 +1755,8 @@ export async function startLocalServer(opts) {
         if (req.method === 'GET' && path === '/api/block-studio/catalog') {
             try {
                 const cfg = loadProjectConfig(projectRoot);
-                const connections = cfg.connections ?? {};
-                if (Object.keys(connections).length === 0 && cfg.defaultConnection) {
-                    connections.default = cfg.defaultConnection;
-                }
-                const defaultKey = cfg.defaultConnection ? 'default' : Object.keys(connections)[0] ?? 'default';
+                const connections = getProjectConnectionsForApi(cfg);
+                const defaultKey = resolveDefaultConnectionKey(cfg, connections) ?? Object.keys(connections)[0] ?? 'default';
                 const userPrefs = readUserPrefs(userPrefsPath);
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({
@@ -1800,15 +1888,10 @@ export async function startLocalServer(opts) {
         }
         if (req.method === 'GET' && path === '/api/connections') {
             const cfg = loadProjectConfig(projectRoot);
-            const raw = cfg;
-            const connections = raw.connections ?? {};
-            // If no explicit connections map, surface the defaultConnection as "default"
-            if (Object.keys(connections).length === 0 && cfg.defaultConnection) {
-                connections['default'] = cfg.defaultConnection;
-            }
-            const defaultKey = raw.defaultConnection
-                ? 'default'
-                : Object.keys(connections)[0] ?? 'default';
+            const connections = getProjectConnectionsForApi(cfg);
+            const defaultKey = resolveDefaultConnectionKey(cfg, connections)
+                ?? Object.keys(connections)[0]
+                ?? 'default';
             const dbtProfiles = discoverDbtProfileConnections(projectRoot, cfg);
             res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
             res.end(serializeJSON({ default: defaultKey, connections, dbtProfiles }));
@@ -1826,6 +1909,22 @@ export async function startLocalServer(opts) {
                 if (body.connections && typeof body.connections === 'object') {
                     raw.connections = body.connections;
                 }
+                const connections = getStoredConnections(raw);
+                if (body.connections && typeof body.connections === 'object') {
+                    const requestedDefault = typeof body.defaultConnectionName === 'string'
+                        ? body.defaultConnectionName
+                        : typeof body.default === 'string'
+                            ? body.default
+                            : undefined;
+                    const defaultConnectionName = resolveDefaultConnectionKey(requestedDefault ? { ...raw, defaultConnectionName: requestedDefault } : raw, connections);
+                    delete raw.defaultConnection;
+                    if (defaultConnectionName) {
+                        raw.defaultConnectionName = defaultConnectionName;
+                    }
+                    else {
+                        delete raw.defaultConnectionName;
+                    }
+                }
                 writeFileSync(configPath, JSON.stringify(raw, null, 2) + '\n', 'utf-8');
                 // Hot-swap: re-read the config and re-initialize the active connection
                 projectConfig = loadProjectConfig(projectRoot);
@@ -3361,22 +3460,95 @@ export function loadProjectConfig(projectRoot) {
     }
     const raw = JSON.parse(readFileSync(configPath, 'utf-8'));
     const config = raw;
-    // Normalize modern `connections.default` format to `defaultConnection`
-    if (!config.defaultConnection && raw.connections) {
-        const connections = raw.connections;
-        const defaultConn = connections.default;
-        if (defaultConn?.driver) {
-            // Support both `filepath` (correct) and `path` (legacy/init compat)
-            const filepath = (defaultConn.filepath ?? defaultConn.path);
-            config.defaultConnection = {
-                ...defaultConn,
-                driver: defaultConn.driver,
-                ...(filepath ? { filepath } : {}),
-            };
+    const connections = getStoredConnections(raw);
+    const defaultConnectionName = resolveDefaultConnectionKey(raw, connections);
+    if (defaultConnectionName) {
+        const selected = normalizeStoredConnection(connections[defaultConnectionName]);
+        if (selected) {
+            config.defaultConnection = selected;
+            config.defaultConnectionName = defaultConnectionName;
+        }
+    }
+    else if (config.defaultConnection) {
+        const normalized = normalizeStoredConnection(config.defaultConnection);
+        if (normalized) {
+            config.defaultConnection = normalized;
         }
     }
     return config;
 }
+function getProjectConnectionsForApi(config) {
+    const connections = getStoredConnections(config);
+    if (Object.keys(connections).length === 0 && isConnectionLike(config.defaultConnection)) {
+        return { default: config.defaultConnection };
+    }
+    return connections;
+}
+function getStoredConnections(raw) {
+    const value = raw.connections;
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return {};
+    }
+    return { ...value };
+}
+function resolveDefaultConnectionKey(raw, connections) {
+    const keys = Object.keys(connections).filter((key) => isConnectionLike(connections[key]));
+    if (keys.length === 0)
+        return undefined;
+    const configured = readConfiguredDefaultConnectionName(raw);
+    if (configured && keys.includes(configured)) {
+        return configured;
+    }
+    if (keys.includes('default') && !isPlaceholderLocalConnection(connections.default)) {
+        return 'default';
+    }
+    const realConnections = keys.filter((key) => !isPlaceholderLocalConnection(connections[key]));
+    if (keys.includes('default') && isPlaceholderLocalConnection(connections.default) && realConnections.length === 1) {
+        return realConnections[0];
+    }
+    if (keys.length === 1) {
+        return keys[0];
+    }
+    return keys.includes('default') ? 'default' : keys[0];
+}
+function readConfiguredDefaultConnectionName(raw) {
+    for (const key of ['defaultConnectionName', 'defaultConnectionKey', 'currentConnection']) {
+        const value = raw[key];
+        if (typeof value === 'string' && value.trim())
+            return value.trim();
+    }
+    return typeof raw.default === 'string' && raw.default.trim() ? raw.default.trim() : undefined;
+}
+function normalizeStoredConnection(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const raw = value;
+    const driver = raw.driver ?? raw.type;
+    if (typeof driver !== 'string' || !driver.trim())
+        return null;
+    const { path: legacyPath, type: _type, ...rest } = raw;
+    const filepath = typeof raw.filepath === 'string'
+        ? raw.filepath
+        : typeof legacyPath === 'string'
+            ? legacyPath
+            : undefined;
+    return {
+        ...rest,
+        driver: driver.trim(),
+        ...(filepath ? { filepath } : {}),
+    };
+}
+function isConnectionLike(value) {
+    return normalizeStoredConnection(value) !== null;
+}
+function isPlaceholderLocalConnection(value) {
+    const connection = normalizeStoredConnection(value);
+    if (!connection)
+        return false;
+    if (connection.driver !== 'duckdb' && connection.driver !== 'file')
+        return false;
+    return !connection.filepath || connection.filepath === ':memory:';
+}
 export function prepareLocalExecution(sql, connection, projectRoot, projectConfig) {
     const normalizedConnection = normalizeProjectConnection(connection, projectRoot);
     return {
@@ -3416,19 +3588,25 @@ export function buildAgentPreviewSql(sql) {
     if (!trimmed)
         throw new Error('Generated SQL preview is empty.');
     const withoutTrailingSemicolon = trimmed.replace(/;\s*$/, '').trim();
-    const scanSql = stripSqlStringsAndComments(withoutTrailingSemicolon).trim();
+    const readOnlyError = readOnlySqlValidationError(withoutTrailingSemicolon, 'Generated SQL preview');
+    if (readOnlyError)
+        throw new Error(readOnlyError);
+    return `SELECT * FROM (\n${withoutTrailingSemicolon}\n) AS dql_agent_preview LIMIT 200`;
+}
+function readOnlySqlValidationError(sql, subject) {
+    const scanSql = stripSqlStringsAndComments(sql).trim();
     if (!/^(select|with)\b/i.test(scanSql)) {
-        throw new Error('Generated SQL preview only supports read-only SELECT or WITH queries.');
+        return `${subject} only supports read-only SELECT or WITH queries.`;
     }
     if (scanSql.includes(';')) {
-        throw new Error('Generated SQL preview only supports one statement.');
+        return `${subject} only supports one statement.`;
     }
     const forbiddenPattern = new RegExp(`\\b(${AGENT_PREVIEW_FORBIDDEN_SQL.join('|')})\\b`, 'i');
     const forbidden = scanSql.match(forbiddenPattern)?.[1];
     if (forbidden) {
-        throw new Error(`Generated SQL preview rejected unsupported statement keyword: ${forbidden.toUpperCase()}.`);
+        return `${subject} rejected unsupported statement keyword: ${forbidden.toUpperCase()}.`;
     }
-    return `SELECT * FROM (\n${withoutTrailingSemicolon}\n) AS dql_agent_preview LIMIT 200`;
+    return null;
 }
 function stripSqlStringsAndComments(sql) {
     let output = '';
@@ -4211,6 +4389,16 @@ export function validateBlockStudioSource(source, semanticLayer) {
         diagnostics.push(...resolvedCustomSql.diagnostics);
         executableSql = resolvedCustomSql.sql;
     }
+    if (executableSql && semanticConfig.blockType !== 'semantic') {
+        const readOnlyError = readOnlySqlValidationError(executableSql.trim().replace(/;\s*$/, '').trim(), 'Block SQL');
+        if (readOnlyError) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'sql_read_only',
+                message: readOnlyError,
+            });
+        }
+    }
     const chartConfig = extractBlockStudioChartConfig(source);
     if (!chartConfig) {
         diagnostics.push({
@@ -4240,7 +4428,7 @@ export function validateBlockStudioSource(source, semanticLayer) {
         executableSql,
     };
 }
-function saveBlockStudioArtifacts(projectRoot, options) {
+export function saveBlockStudioArtifacts(projectRoot, options) {
     const slug = options.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'block';
     const safeDomain = (options.domain ?? '')
         .trim()
@@ -6113,7 +6301,7 @@ function isAiPinRefreshDue(lastRefreshedAt) {
         return true;
     return Date.now() - last >= 24 * 60 * 60 * 1000;
 }
-function buildAgentSchemaContext(question, rows) {
+export function buildAgentSchemaContext(question, rows) {
     const byRelation = new Map();
     for (const row of rows) {
         if (!row || typeof row !== 'object')
@@ -6141,13 +6329,54 @@ function buildAgentSchemaContext(question, rows) {
         byRelation.set(relation, current);
     }
     const tokens = agentSchemaTokens(question);
+    const shouldProbeValues = extractAgentValueSearchTerms(question).length > 0;
     return Array.from(byRelation.values())
-        .map((table) => ({ table, score: scoreAgentSchemaTable(table, tokens) }))
+        .map((table) => ({
+        table,
+        score: scoreAgentSchemaTable(table, tokens) + (shouldProbeValues ? scoreAgentValueProbeTable(table) : 0),
+    }))
         .filter((entry) => entry.score > 0)
         .sort((a, b) => b.score - a.score || a.table.relation.localeCompare(b.table.relation))
         .slice(0, 12)
         .map((entry) => entry.table);
 }
+async function enrichAgentSchemaContextWithValueMatches(question, schemaContext, executor, connection) {
+    const searchTerms = extractAgentValueSearchTerms(question);
+    if (schemaContext.length === 0 || searchTerms.length === 0)
+        return schemaContext;
+    const matches = new Map();
+    for (const candidate of rankAgentValueProbeColumns(schemaContext).slice(0, 12)) {
+        try {
+            const result = await executor.executeQuery(buildAgentValueProbeSql(candidate.table, candidate.column.name, searchTerms, connection), [], runtimeVariables({}), connection);
+            const values = uniqueStrings(result.rows.flatMap(valueProbeRowValues)).slice(0, 5);
+            if (values.length === 0)
+                continue;
+            const tableMatches = matches.get(candidate.table.relation) ?? new Map();
+            tableMatches.set(candidate.column.name, values);
+            matches.set(candidate.table.relation, tableMatches);
+        }
+        catch {
+            // Value probes are advisory. Unsupported casts, privileges, and large-table
+            // failures should not block the metadata-backed answer path.
+        }
+    }
+    if (matches.size === 0)
+        return schemaContext;
+    return schemaContext.map((table) => {
+        const tableMatches = matches.get(table.relation);
+        if (!tableMatches)
+            return table;
+        return {
+            ...table,
+            columns: table.columns.map((column) => {
+                const sampleValues = tableMatches.get(column.name);
+                return sampleValues?.length
+                    ? { ...column, sampleValues: uniqueStrings([...(column.sampleValues ?? []), ...sampleValues]).slice(0, 5) }
+                    : column;
+            }),
+        };
+    });
+}
 function scoreAgentSchemaTable(table, tokens) {
     let score = 0;
     const relationTokens = agentSchemaTokens(`${table.schema ?? ''} ${table.name} ${table.relation}`);
@@ -6166,6 +6395,146 @@ function scoreAgentSchemaTable(table, tokens) {
         score += 1;
     return score;
 }
+function scoreAgentValueProbeTable(table) {
+    let score = 0;
+    if (hasAgentSchemaToken(table.name, ['account', 'customer', 'member', 'order', 'product', 'sku', 'subscriber', 'user']))
+        score += 5;
+    for (const column of table.columns) {
+        if (!isAgentValueProbeColumn(column))
+            continue;
+        score += 2;
+        if (hasAgentSchemaToken(column.name, ['account', 'customer', 'email', 'full', 'member', 'name', 'product', 'sku', 'user']))
+            score += 2;
+    }
+    return Math.min(score, 18);
+}
+function rankAgentValueProbeColumns(schemaContext) {
+    const ranked = [];
+    for (const table of schemaContext) {
+        for (const column of table.columns) {
+            if (!isAgentValueProbeColumn(column))
+                continue;
+            ranked.push({
+                table,
+                column,
+                score: scoreAgentValueProbeColumn(table, column),
+            });
+        }
+    }
+    return ranked.sort((a, b) => b.score - a.score || a.table.relation.localeCompare(b.table.relation) || a.column.name.localeCompare(b.column.name));
+}
+function scoreAgentValueProbeColumn(table, column) {
+    let score = 0;
+    if (hasAgentSchemaToken(table.name, ['account', 'customer', 'member', 'product', 'sku', 'subscriber', 'user']))
+        score += 4;
+    if (hasAgentSchemaToken(column.name, ['full', 'name', 'email', 'account', 'customer', 'member', 'product', 'sku', 'subscriber', 'user']))
+        score += 8;
+    if (hasAgentSchemaToken(column.name, ['id', 'key', 'code', 'number', 'status', 'segment', 'region', 'category', 'type']))
+        score += 3;
+    return score;
+}
+function isAgentValueProbeColumn(column) {
+    const name = column.name.toLowerCase();
+    if (/\b(password|secret|token|credential|hash|salt)\b/.test(name))
+        return false;
+    if (!hasAgentSchemaToken(name, [
+        'account',
+        'category',
+        'channel',
+        'city',
+        'code',
+        'country',
+        'customer',
+        'email',
+        'full',
+        'id',
+        'key',
+        'member',
+        'name',
+        'number',
+        'product',
+        'region',
+        'segment',
+        'sku',
+        'state',
+        'status',
+        'subscriber',
+        'type',
+        'user',
+    ])) {
+        return false;
+    }
+    const type = column.type?.toLowerCase() ?? '';
+    if (!type)
+        return true;
+    return /\b(char|character|clob|email|string|text|uuid|varchar)\b/.test(type);
+}
+function buildAgentValueProbeSql(table, column, searchTerms, connection) {
+    const relation = quoteAgentRelation(table.relation, connection);
+    const identifier = quoteAgentIdentifier(column, connection);
+    const castValue = `LOWER(CAST(${identifier} AS ${agentTextCastType(connection.driver)}))`;
+    const predicates = searchTerms
+        .slice(0, 5)
+        .map((term) => `${castValue} LIKE ${sqlStringLiteral(`%${escapeSqlLike(term.toLowerCase())}%`)} ESCAPE '\\\\'`)
+        .join(' OR ');
+    return [
+        `SELECT DISTINCT CAST(${identifier} AS ${agentTextCastType(connection.driver)}) AS value`,
+        `FROM ${relation}`,
+        `WHERE ${identifier} IS NOT NULL AND (${predicates})`,
+        'LIMIT 5',
+    ].join('\n');
+}
+function agentTextCastType(driver) {
+    switch (driver) {
+        case 'bigquery':
+            return 'STRING';
+        case 'clickhouse':
+            return 'String';
+        case 'fabric':
+        case 'mssql':
+            return 'NVARCHAR(MAX)';
+        case 'mysql':
+            return 'CHAR';
+        case 'sqlite':
+            return 'TEXT';
+        default:
+            return 'VARCHAR';
+    }
+}
+function quoteAgentRelation(relation, connection) {
+    return relation.split('.').map((part) => quoteAgentIdentifier(part, connection)).join('.');
+}
+function quoteAgentIdentifier(identifier, connection) {
+    return getDialect(connection.driver).quoteIdentifier(identifier);
+}
+function sqlStringLiteral(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+function escapeSqlLike(value) {
+    return value.replace(/[\\%_]/g, (match) => `\\${match}`);
+}
+function valueProbeRowValues(row) {
+    if (!row || typeof row !== 'object')
+        return [];
+    const record = row;
+    return Object.values(record)
+        .filter((value) => (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'))
+        .map(String)
+        .map((value) => value.trim())
+        .filter(Boolean);
+}
+function uniqueStrings(values) {
+    const seen = new Set();
+    const output = [];
+    for (const value of values) {
+        const normalized = value.toLowerCase();
+        if (seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        output.push(value);
+    }
+    return output;
+}
 function agentSchemaTokens(value) {
     const tokens = new Set();
     for (const raw of value.toLowerCase().match(/[a-z0-9_]+/g) ?? []) {
@@ -6178,10 +6547,60 @@ function agentSchemaTokens(value) {
     }
     return tokens;
 }
+function hasAgentSchemaToken(value, expected) {
+    const tokens = agentSchemaTokens(value);
+    return expected.some((token) => tokens.has(token));
+}
+export function extractAgentValueSearchTerms(question) {
+    const terms = [];
+    for (const match of question.matchAll(/["']([^"']{3,120})["']/g)) {
+        terms.push(match[1]);
+    }
+    for (const match of question.matchAll(/\b[\w.%+-]+@[\w.-]+\.[A-Za-z]{2,}\b/g)) {
+        terms.push(match[0]);
+    }
+    for (const match of question.matchAll(/\b[A-Z][a-z0-9]+(?:\s+[A-Z][a-z0-9]+){1,3}\b/g)) {
+        terms.push(match[0]);
+    }
+    for (const match of question.matchAll(/\b(?:for|named|called|only|where|customer|user|account|product)\s+([A-Za-z0-9@._-]+(?:\s+[A-Za-z0-9@._-]+){0,3})/gi)) {
+        terms.push(match[1]);
+    }
+    return uniqueStrings(terms
+        .map(cleanAgentValueSearchTerm)
+        .filter((term) => term.length >= 3 && !AGENT_VALUE_SEARCH_STOP_PHRASES.has(term.toLowerCase()))).slice(0, 6);
+}
+function cleanAgentValueSearchTerm(term) {
+    return term
+        .replace(/[?.,;:]+$/g, '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .replace(/^(?:account|customer|member|named|called|product|sku|subscriber|user)\s+/i, '')
+        .replace(/\s+\b(?:last|next|this)\b.*$/i, '')
+        .replace(/\s+\b(?:last|this)\s+(?:day|week|month|quarter|year)\b.*$/i, '')
+        .replace(/\s+\b(?:daily|weekly|monthly|quarterly|yearly)\b.*$/i, '')
+        .trim();
+}
 const AGENT_SCHEMA_STOPWORDS = new Set([
     'all', 'and', 'are', 'can', 'data', 'for', 'from', 'have', 'how', 'many', 'me',
     'show', 'the', 'this', 'who', 'with', 'value',
 ]);
+const AGENT_VALUE_SEARCH_STOP_PHRASES = new Set([
+    'account',
+    'customer',
+    'last week',
+    'this week',
+    'last month',
+    'this month',
+    'last quarter',
+    'this quarter',
+    'last year',
+    'this year',
+    'member',
+    'product',
+    'sku',
+    'subscriber',
+    'user',
+]);
 function normalizeAgentSchemaToken(token) {
     if (token === 'orders')
         return 'order';