@duckcodeailabs/dql-cli 1.6.0 → 1.6.2

package/dist/local-runtime.js

@@ -1,6 +1,7 @@
 import { execSync } from 'node:child_process';
 import { createServer } from 'node:http';
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, watch, writeFileSync } from 'node:fs';
+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';
@@ -120,7 +121,8 @@ export async function startLocalServer(opts) {
                         config: (sourceCell.chartConfig ?? sourceCell.config),
                     };
                     const resolved = resolveNotebookBlockReferenceCell(cell, projectRoot);
-                    const plan = buildExecutionPlan(resolved.cell, { semanticLayer, driver: connection.driver });
+                    const tableMapping = await resolveSemanticTableMapping(executor, connection, semanticLayer);
+                    const plan = buildExecutionPlan(resolved.cell, { semanticLayer, driver: connection.driver, tableMapping });
                     if (!plan) {
                         snapshotCells.push({ cellId, status: 'idle', executionCount: 0, executedAt });
                         continue;
@@ -181,15 +183,17 @@ export async function startLocalServer(opts) {
         }
         const absBlockPath = join(projectRoot, block.filePath);
         const source = readFileSync(absBlockPath, 'utf-8');
+        const tableMapping = await resolveSemanticTableMapping(executor, connection, semanticLayer);
         const semanticCompose = semanticLayer
             ? composeSemanticBlockSql(source, semanticLayer, {
                 driver: connection.driver,
+                tableMapping,
                 projectRoot,
                 projectConfig,
                 detectedProvider: semanticDetectedProvider,
             })
             : null;
-        const plan = buildExecutionPlan({ id: `agent-${block.name}`, type: 'dql', source, title: block.name }, { semanticLayer, driver: connection.driver });
+        const plan = buildExecutionPlan({ id: `agent-${block.name}`, type: 'dql', source, title: block.name }, { semanticLayer, driver: connection.driver, tableMapping });
         if (!plan && !semanticCompose?.sql) {
             const semanticError = semanticCompose?.diagnostics.find((diagnostic) => diagnostic.severity === 'error')?.message;
             throw new Error(semanticError ?? `Block "${block.name}" produced no executable SQL.`);
@@ -210,6 +214,37 @@ export async function startLocalServer(opts) {
             blockPath: block.filePath,
         };
     };
+    const executeGeneratedSqlForAgent = async (sql) => {
+        const boundedSql = buildAgentPreviewSql(sql);
+        const semantic = prepareSemanticSql(boundedSql, semanticLayer);
+        if (semantic.unresolvedRefs.length > 0) {
+            throw new Error(`Unknown semantic reference${semantic.unresolvedRefs.length > 1 ? 's' : ''}: ${semantic.unresolvedRefs.join(', ')}`);
+        }
+        const prepared = prepareLocalExecution(semantic.sql, connection, projectRoot, projectConfig);
+        const app = loadRuntimeApp(projectRoot, activePersonaAppId());
+        assertAppAccess({ app, domain: app?.domain, level: 'execute' });
+        const rawResult = await executor.executeQuery(prepared.sql, [], runtimeVariables({}), prepared.connection);
+        const normalized = normalizeQueryResult(rawResult, semantic.semanticRefs);
+        return {
+            columns: normalized.columns,
+            rows: normalized.rows,
+            rowCount: normalized.rowCount,
+            executionTime: normalized.executionTime,
+            sql: prepared.sql,
+        };
+    };
+    const getSchemaContextForAgent = async (question) => {
+        try {
+            const result = await executor.executeQuery(`SELECT table_schema, table_name, column_name, data_type
+         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);
+        }
+        catch {
+            return [];
+        }
+    };
     // SSE clients for /api/watch hot-reload
     const sseClients = new Set();
     // Watch notebooks/, workbooks/, semantic-layer/, and data/ dirs for changes
@@ -298,7 +333,7 @@ export async function startLocalServer(opts) {
                 ?? 'No executable SQL found in block source.';
             throw new Error(message);
         }
-        const plan = buildExecutionPlan({ id: 'block-studio', type: 'dql', source, title: 'Block Studio' }, { semanticLayer, driver: targetConnection.driver });
+        const plan = buildExecutionPlan({ id: 'block-studio', type: 'dql', source, title: 'Block Studio' }, { semanticLayer, driver: targetConnection.driver, tableMapping });
         const sql = resolveProjectRelativeSqlPaths(semanticCompose?.sql ?? plan?.sql ?? executableSql, projectRoot, projectConfig.dataDir);
         const result = await executor.executeQuery(sql, plan?.sqlParams ?? [], runtimeVariables(plan?.variables ?? {}), targetConnection);
         return {
@@ -309,7 +344,8 @@ export async function startLocalServer(opts) {
     };
     const runBlockStudioTestSummary = async (source, targetConnection = connection) => {
         const start = Date.now();
-        const plan = buildExecutionPlan({ id: 'block-studio-tests', type: 'dql', source, title: 'Block Studio' }, { semanticLayer, driver: targetConnection.driver });
+        const tableMapping = await resolveSemanticTableMapping(executor, targetConnection, semanticLayer);
+        const plan = buildExecutionPlan({ id: 'block-studio-tests', type: 'dql', source, title: 'Block Studio' }, { semanticLayer, driver: targetConnection.driver, tableMapping });
         const tests = plan?.tests ?? [];
         if (!plan || !plan.sql) {
             return {
@@ -578,7 +614,7 @@ export async function startLocalServer(opts) {
                     ? body.variables
                     : {};
                 const tiles = [];
-                const localApps = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+                let localApps = null;
                 for (const item of loaded.dashboard.layout.items) {
                     if (item.text) {
                         tiles.push({
@@ -592,6 +628,18 @@ export async function startLocalServer(opts) {
                         continue;
                     }
                     if (item.aiPin) {
+                        try {
+                            localApps ??= new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+                        }
+                        catch (err) {
+                            tiles.push({
+                                tileId: item.i,
+                                status: 'error',
+                                tileType: 'aiPin',
+                                error: err instanceof Error ? err.message : String(err),
+                            });
+                            continue;
+                        }
                         let pin = localApps.getAiPin(item.aiPin.id);
                         if (!pin) {
                             tiles.push({
@@ -645,15 +693,18 @@ export async function startLocalServer(opts) {
                         });
                         const absBlockPath = join(projectRoot, block.filePath);
                         const source = readFileSync(absBlockPath, 'utf-8');
+                        const targetConnection = isConnectionConfig(body.connection) ? body.connection : connection;
+                        const tableMapping = await resolveSemanticTableMapping(executor, targetConnection, semanticLayer);
                         const semanticCompose = semanticLayer
                             ? composeSemanticBlockSql(source, semanticLayer, {
-                                driver: connection.driver,
+                                driver: targetConnection.driver,
+                                tableMapping,
                                 projectRoot,
                                 projectConfig,
                                 detectedProvider: semanticDetectedProvider,
                             })
                             : null;
-                        const plan = buildExecutionPlan({ id: item.i, type: 'dql', source, title: item.title ?? block.name }, { semanticLayer, driver: connection.driver });
+                        const plan = buildExecutionPlan({ id: item.i, type: 'dql', source, title: item.title ?? block.name }, { semanticLayer, driver: targetConnection.driver, tableMapping });
                         if (!plan && !semanticCompose?.sql) {
                             tiles.push({
                                 tileId: item.i,
@@ -663,7 +714,7 @@ export async function startLocalServer(opts) {
                             });
                             continue;
                         }
-                        const prepared = prepareLocalExecution(semanticCompose?.sql ?? plan.sql, isConnectionConfig(body.connection) ? body.connection : connection, projectRoot, projectConfig);
+                        const prepared = prepareLocalExecution(semanticCompose?.sql ?? plan.sql, targetConnection, projectRoot, projectConfig);
                         const result = await executor.executeQuery(prepared.sql, plan?.sqlParams ?? [], runtimeVariables({ ...(plan?.variables ?? {}), ...variables }), prepared.connection);
                         tiles.push({
                             tileId: item.i,
@@ -701,7 +752,7 @@ export async function startLocalServer(opts) {
                         }
                     }
                 }
-                localApps.close();
+                localApps?.close();
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({
                     appId,
@@ -1758,8 +1809,9 @@ export async function startLocalServer(opts) {
             const defaultKey = raw.defaultConnection
                 ? 'default'
                 : 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 }));
+            res.end(serializeJSON({ default: defaultKey, connections, dbtProfiles }));
             return;
         }
         // Save/update connections
@@ -2476,7 +2528,15 @@ export async function startLocalServer(opts) {
             req.on('close', () => controller.abort());
             const emit = (turn) => { res.write(`data: ${JSON.stringify(turn)}\n\n`); };
             try {
-                await runner.run({ provider: resolvedProvider, messages, upstream, projectRoot, executeCertifiedBlock: executeCertifiedBlockForAgent }, emit, controller.signal);
+                await runner.run({
+                    provider: resolvedProvider,
+                    messages,
+                    upstream,
+                    projectRoot,
+                    executeCertifiedBlock: executeCertifiedBlockForAgent,
+                    executeGeneratedSql: executeGeneratedSqlForAgent,
+                    getSchemaContext: getSchemaContextForAgent,
+                }, emit, controller.signal);
             }
             catch (err) {
                 emit({ kind: 'error', message: err instanceof Error ? err.message : String(err) });
@@ -3048,7 +3108,8 @@ export async function startLocalServer(opts) {
                 const resolved = resolveNotebookBlockReferenceCell(cell, projectRoot);
                 const executableCell = resolved.cell;
                 const cellConnection = isConnectionConfig(body.connection) ? body.connection : connection;
-                const plan = buildExecutionPlan(executableCell, { semanticLayer, driver: cellConnection.driver });
+                const tableMapping = await resolveSemanticTableMapping(executor, cellConnection, semanticLayer);
+                const plan = buildExecutionPlan(executableCell, { semanticLayer, driver: cellConnection.driver, tableMapping });
                 if (!plan) {
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({ cellType: cell.type, result: null }));
@@ -3308,6 +3369,7 @@ export function loadProjectConfig(projectRoot) {
             // Support both `filepath` (correct) and `path` (legacy/init compat)
             const filepath = (defaultConn.filepath ?? defaultConn.path);
             config.defaultConnection = {
+                ...defaultConn,
                 driver: defaultConn.driver,
                 ...(filepath ? { filepath } : {}),
             };
@@ -3324,6 +3386,100 @@ export function prepareLocalExecution(sql, connection, projectRoot, projectConfi
         connection: normalizedConnection,
     };
 }
+const AGENT_PREVIEW_FORBIDDEN_SQL = [
+    'alter',
+    'analyze',
+    'attach',
+    'call',
+    'copy',
+    'create',
+    'delete',
+    'detach',
+    'drop',
+    'export',
+    'grant',
+    'import',
+    'insert',
+    'install',
+    'load',
+    'merge',
+    'pragma',
+    'reset',
+    'revoke',
+    'set',
+    'truncate',
+    'update',
+    'vacuum',
+];
+export function buildAgentPreviewSql(sql) {
+    const trimmed = sql.trim();
+    if (!trimmed)
+        throw new Error('Generated SQL preview is empty.');
+    const withoutTrailingSemicolon = trimmed.replace(/;\s*$/, '').trim();
+    const scanSql = stripSqlStringsAndComments(withoutTrailingSemicolon).trim();
+    if (!/^(select|with)\b/i.test(scanSql)) {
+        throw new Error('Generated SQL preview only supports read-only SELECT or WITH queries.');
+    }
+    if (scanSql.includes(';')) {
+        throw new Error('Generated SQL preview 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 `SELECT * FROM (\n${withoutTrailingSemicolon}\n) AS dql_agent_preview LIMIT 200`;
+}
+function stripSqlStringsAndComments(sql) {
+    let output = '';
+    for (let index = 0; index < sql.length; index += 1) {
+        const current = sql[index];
+        const next = sql[index + 1];
+        if (current === '-' && next === '-') {
+            output += '  ';
+            index += 2;
+            while (index < sql.length && sql[index] !== '\n') {
+                output += ' ';
+                index += 1;
+            }
+            if (index < sql.length)
+                output += '\n';
+            continue;
+        }
+        if (current === '/' && next === '*') {
+            output += '  ';
+            index += 2;
+            while (index < sql.length && !(sql[index] === '*' && sql[index + 1] === '/')) {
+                output += sql[index] === '\n' ? '\n' : ' ';
+                index += 1;
+            }
+            if (index < sql.length) {
+                output += '  ';
+                index += 1;
+            }
+            continue;
+        }
+        if (current === "'" || current === '"') {
+            const quote = current;
+            output += ' ';
+            while (index + 1 < sql.length) {
+                index += 1;
+                output += sql[index] === '\n' ? '\n' : ' ';
+                if (sql[index] === quote) {
+                    if (sql[index + 1] === quote) {
+                        index += 1;
+                        output += ' ';
+                        continue;
+                    }
+                    break;
+                }
+            }
+            continue;
+        }
+        output += current;
+    }
+    return output;
+}
 /**
  * Shared resolver for `@metric(name)` / `@dim(name)` refs in raw SQL.
  * Used by notebook SQL execution and Block Studio validation so both paths
@@ -3344,7 +3500,7 @@ export function prepareSemanticSql(sql, semanticLayer) {
     };
 }
 export function normalizeProjectConnection(connection, projectRoot) {
-    const normalized = { ...connection };
+    const normalized = expandConnectionEnvPlaceholders({ ...connection });
     if ((normalized.driver === 'file' || normalized.driver === 'duckdb') && normalized.filepath && normalized.filepath !== ':memory:' && !isAbsoluteLikePath(normalized.filepath)) {
         normalized.filepath = resolve(projectRoot, normalized.filepath);
     }
@@ -3353,6 +3509,15 @@ export function normalizeProjectConnection(connection, projectRoot) {
     }
     return normalized;
 }
+function expandConnectionEnvPlaceholders(connection) {
+    const expanded = {};
+    for (const [key, value] of Object.entries(connection)) {
+        expanded[key] = typeof value === 'string'
+            ? value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (match, envKey) => process.env[envKey] ?? match)
+            : value;
+    }
+    return expanded;
+}
 export function resolveProjectRelativeSqlPaths(sql, projectRoot, dataDir) {
     const resolvedRoot = resolve(projectRoot);
     const normalizedDataDir = typeof dataDir === 'string' && dataDir.trim().length > 0
@@ -3495,6 +3660,8 @@ function scanNotebookFiles(projectRoot) {
         workbooks: 'workbook',
         blocks: 'block',
         dashboards: 'dashboard',
+        terms: 'term',
+        'business-views': 'business_view',
     };
     for (const [folder, type] of Object.entries(folderMap)) {
         const dir = join(projectRoot, folder);
@@ -3516,8 +3683,9 @@ function scanNotebookFiles(projectRoot) {
                     continue;
                 if (!entry.name.endsWith('.dql') && !entry.name.endsWith('.dqlnb'))
                     continue;
+                const fallbackName = entry.name.replace(/\.(dql|dqlnb)$/, '');
                 result.push({
-                    name: entry.name.replace(/\.(dql|dqlnb)$/, ''),
+                    name: inferDqlArtifactName(fullPath, type, fallbackName),
                     path: relativePath,
                     type,
                     folder: relativeDir.split('/')[0] ?? relativeDir,
@@ -3527,6 +3695,27 @@ function scanNotebookFiles(projectRoot) {
         catch { /* skip unreadable dirs */ }
     }
 }
+function inferDqlArtifactName(fullPath, type, fallbackName) {
+    if (!fullPath.endsWith('.dql'))
+        return fallbackName;
+    const expectedKind = {
+        block: 'BlockDecl',
+        dashboard: 'Dashboard',
+        term: 'TermDecl',
+        business_view: 'BusinessViewDecl',
+    };
+    const kind = expectedKind[type];
+    if (!kind)
+        return fallbackName;
+    try {
+        const ast = new Parser(readFileSync(fullPath, 'utf-8')).parse();
+        const statement = ast.statements.find((item) => item.kind === kind && typeof item.name === 'string');
+        return statement?.name ?? fallbackName;
+    }
+    catch {
+        return fallbackName;
+    }
+}
 function scanDataFiles(projectRoot) {
     const dataDir = join(projectRoot, 'data');
     if (!existsSync(dataDir))
@@ -3756,7 +3945,20 @@ function parseSemanticBlockConfig(source) {
         limit: limitMatch ? Number.parseInt(limitMatch[1], 10) : undefined,
     };
 }
-function buildSemanticTableMapping(semanticLayer, rows) {
+export async function resolveSemanticTableMapping(executor, connection, semanticLayer) {
+    if (!semanticLayer)
+        return undefined;
+    try {
+        const tablesResult = await executor.executeQuery(`SELECT table_schema, table_name
+       FROM information_schema.tables
+       WHERE table_schema NOT IN ('information_schema', 'pg_catalog')`, [], {}, connection);
+        return buildSemanticTableMapping(semanticLayer, tablesResult.rows);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function buildSemanticTableMapping(semanticLayer, rows) {
     const dbTableNames = new Set();
     const schemaQualified = new Map();
     for (const row of rows) {
@@ -4569,7 +4771,10 @@ function buildSemanticBlockContent(options) {
     if (options.tags && options.tags.length > 0) {
         lines.push(`    tags = [${options.tags.map((tag) => `"${escapeDqlString(tag)}"`).join(', ')}]`);
     }
-    if (options.metrics.length === 1) {
+    if (options.metrics.length === 0) {
+        lines.push('    metric = ""');
+    }
+    else if (options.metrics.length === 1) {
         lines.push(`    metric = "${escapeDqlString(options.metrics[0])}"`);
     }
     else {
@@ -4578,6 +4783,9 @@ function buildSemanticBlockContent(options) {
     if (options.dimensions.length > 0) {
         lines.push(`    dimensions = [${options.dimensions.map((dimension) => `"${escapeDqlString(dimension)}"`).join(', ')}]`);
     }
+    else {
+        lines.push('    dimensions = []');
+    }
     if (options.timeDimension) {
         lines.push(`    time_dimension = "${escapeDqlString(options.timeDimension.name)}"`);
         lines.push(`    granularity = "${escapeDqlString(options.timeDimension.granularity)}"`);
@@ -4945,7 +5153,51 @@ function resolveDbtManifestPath(projectRoot) {
     const candidate = join(projectRoot, 'target', 'manifest.json');
     return existsSync(candidate) ? candidate : undefined;
 }
-export function buildDbtStatus(projectRoot, projectConfig, lastSyncTime) {
+export function discoverDbtProfileConnections(projectRoot, projectConfig) {
+    const dbtProjectPath = findDbtProjectPath(projectRoot, projectConfig);
+    const projectProfileName = readDbtProjectProfileName(dbtProjectPath);
+    const profilePaths = findDbtProfilePaths(projectRoot, dbtProjectPath);
+    const candidates = [];
+    for (const profilePath of profilePaths) {
+        const profiles = readYamlFile(profilePath);
+        if (!profiles)
+            continue;
+        for (const [profileName, rawProfile] of Object.entries(profiles)) {
+            if (!rawProfile || typeof rawProfile !== 'object')
+                continue;
+            if (projectProfileName && profileName !== projectProfileName)
+                continue;
+            const profile = rawProfile;
+            const outputs = profile.outputs && typeof profile.outputs === 'object'
+                ? profile.outputs
+                : {};
+            const defaultTarget = typeof profile.target === 'string' ? profile.target : 'default';
+            for (const [targetName, output] of Object.entries(outputs)) {
+                if (!output || typeof output !== 'object')
+                    continue;
+                const mapped = mapDbtProfileOutput(output);
+                if (!mapped)
+                    continue;
+                const warnings = [...mapped.warnings];
+                if (targetName !== defaultTarget) {
+                    warnings.push(`Not the default dbt target "${defaultTarget}".`);
+                }
+                candidates.push({
+                    id: `${profilePath}:${profileName}:${targetName}`,
+                    profileName,
+                    targetName,
+                    adapter: mapped.adapter,
+                    path: profilePath,
+                    connection: mapped.connection,
+                    missingFields: requiredConnectionFields(mapped.connection, mapped.envRefs),
+                    warnings,
+                });
+            }
+        }
+    }
+    return candidates.slice(0, 20);
+}
+function findDbtProjectPath(projectRoot, projectConfig) {
     const configuredDbtDir = projectConfig.dbt?.projectDir
         ? resolve(projectRoot, projectConfig.dbt.projectDir)
         : undefined;
@@ -4960,7 +5212,259 @@ export function buildDbtStatus(projectRoot, projectConfig, lastSyncTime) {
         resolve(projectRoot, '../dbt'),
         resolve(projectRoot, '../../dbt'),
     ].filter((value) => Boolean(value));
-    const dbtProjectPath = candidateDirs.find((dir, index, list) => list.indexOf(dir) === index && existsSync(join(dir, 'dbt_project.yml'))) ?? configuredDbtDir ?? semanticDbtDir ?? projectRoot;
+    return candidateDirs.find((dir, index, list) => list.indexOf(dir) === index && existsSync(join(dir, 'dbt_project.yml')))
+        ?? configuredDbtDir
+        ?? semanticDbtDir
+        ?? projectRoot;
+}
+function findDbtProfilePaths(projectRoot, dbtProjectPath) {
+    const dirs = [
+        process.env.DBT_PROFILES_DIR,
+        dbtProjectPath,
+        projectRoot,
+        join(homedir(), '.dbt'),
+    ].filter((value) => Boolean(value));
+    const paths = [];
+    for (const dir of dirs) {
+        for (const filename of ['profiles.yml', 'profiles.yaml']) {
+            const profilePath = resolve(dir, filename);
+            if (existsSync(profilePath) && !paths.includes(profilePath)) {
+                paths.push(profilePath);
+            }
+        }
+    }
+    return paths;
+}
+function readDbtProjectProfileName(dbtProjectPath) {
+    const projectFile = join(dbtProjectPath, 'dbt_project.yml');
+    const projectYaml = readYamlFile(projectFile);
+    return typeof projectYaml?.profile === 'string' ? projectYaml.profile : null;
+}
+function readYamlFile(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = loadYaml(readFileSync(path, 'utf-8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function mapDbtProfileOutput(output) {
+    const adapter = text(output, 'type').value?.toLowerCase();
+    const envRefs = new Set();
+    const warnings = [];
+    const read = (...keys) => {
+        const result = text(output, ...keys);
+        result.envRefs.forEach((ref) => envRefs.add(ref));
+        return result.value;
+    };
+    const port = numberValue(output, 'port');
+    const sslRaw = read('ssl', 'sslmode');
+    const ssl = sslRaw === undefined
+        ? undefined
+        : !['false', '0', 'disable', 'disabled', 'off'].includes(sslRaw.toLowerCase());
+    switch (adapter) {
+        case 'postgres':
+        case 'postgresql':
+            return {
+                adapter,
+                connection: compactConnection({
+                    driver: 'postgresql',
+                    host: read('host'),
+                    port,
+                    database: read('dbname', 'database'),
+                    schema: read('schema'),
+                    username: read('user', 'username'),
+                    password: read('password', 'pass'),
+                    ssl,
+                }),
+                envRefs: [...envRefs],
+                warnings,
+            };
+        case 'redshift':
+            return {
+                adapter,
+                connection: compactConnection({
+                    driver: 'redshift',
+                    host: read('host'),
+                    port: port ?? 5439,
+                    database: read('dbname', 'database'),
+                    schema: read('schema'),
+                    username: read('user', 'username'),
+                    password: read('password', 'pass'),
+                    ssl,
+                }),
+                envRefs: [...envRefs],
+                warnings,
+            };
+        case 'snowflake': {
+            const privateKeyPath = read('private_key_path', 'privateKeyPath');
+            const authenticator = read('authenticator');
+            const authMethod = privateKeyPath
+                ? 'key_pair'
+                : authenticator?.toLowerCase() === 'externalbrowser'
+                    ? 'external_browser'
+                    : 'password';
+            return {
+                adapter,
+                connection: compactConnection({
+                    driver: 'snowflake',
+                    account: read('account'),
+                    warehouse: read('warehouse'),
+                    database: read('database'),
+                    schema: read('schema'),
+                    username: read('user', 'username'),
+                    password: read('password'),
+                    role: read('role'),
+                    privateKeyPath,
+                    privateKeyPassphrase: read('private_key_passphrase', 'privateKeyPassphrase'),
+                    authenticator,
+                    authMethod,
+                }),
+                envRefs: [...envRefs],
+                warnings,
+            };
+        }
+        case 'bigquery': {
+            const keyFilename = read('keyfile', 'keyFilename');
+            return {
+                adapter,
+                connection: compactConnection({
+                    driver: 'bigquery',
+                    projectId: read('project', 'projectId'),
+                    schema: read('dataset', 'schema'),
+                    location: read('location'),
+                    keyFilename,
+                    authMethod: keyFilename ? 'service_account_key_file' : 'application_default',
+                }),
+                envRefs: [...envRefs],
+                warnings,
+            };
+        }
+        case 'duckdb':
+            return {
+                adapter,
+                connection: compactConnection({
+                    driver: 'duckdb',
+                    filepath: read('path', 'database') ?? ':memory:',
+                }),
+                envRefs: [...envRefs],
+                warnings,
+            };
+        case 'databricks':
+            return {
+                adapter,
+                connection: compactConnection({
+                    driver: 'databricks',
+                    host: read('host', 'server_hostname'),
+                    httpPath: read('http_path', 'httpPath'),
+                    warehouse: read('warehouse', 'warehouse_id'),
+                    catalog: read('catalog'),
+                    database: read('catalog', 'database'),
+                    schema: read('schema'),
+                    token: read('token'),
+                    authMethod: 'token',
+                }),
+                envRefs: [...envRefs],
+                warnings,
+            };
+        default:
+            return null;
+    }
+}
+function text(source, ...keys) {
+    for (const key of keys) {
+        const raw = source[key];
+        if (raw === undefined || raw === null)
+            continue;
+        const value = String(raw).trim();
+        if (!value)
+            continue;
+        return resolveDbtEnvVars(value);
+    }
+    return { envRefs: [] };
+}
+function resolveDbtEnvVars(value) {
+    const envRefs = [];
+    const replaced = value.replace(/\{\{\s*env_var\(\s*['"]([^'"]+)['"]\s*(?:,\s*(['"])(.*?)\2)?\s*\)\s*\}\}/g, (_match, envKey, _quote, fallback) => {
+        const envValue = process.env[envKey];
+        if (envValue !== undefined)
+            return envValue;
+        if (fallback !== undefined)
+            return fallback;
+        envRefs.push(envKey);
+        return `\${${envKey}}`;
+    });
+    return { value: replaced, envRefs };
+}
+function numberValue(source, key) {
+    const raw = source[key];
+    if (raw === undefined || raw === null || raw === '')
+        return undefined;
+    const value = Number(raw);
+    return Number.isFinite(value) ? value : undefined;
+}
+function compactConnection(connection) {
+    const compact = {};
+    for (const [key, value] of Object.entries(connection)) {
+        if (value === undefined || value === null || value === '')
+            continue;
+        compact[key] = value;
+    }
+    return compact;
+}
+function requiredConnectionFields(connection, envRefs) {
+    const missing = new Set();
+    const needs = (field) => {
+        const value = connection[field];
+        if (value === undefined || value === null || value === '')
+            missing.add(String(field));
+    };
+    switch (connection.driver) {
+        case 'postgresql':
+        case 'redshift':
+            needs('host');
+            needs('database');
+            needs('username');
+            break;
+        case 'snowflake':
+            needs('account');
+            needs('warehouse');
+            needs('database');
+            needs('schema');
+            needs('username');
+            if (connection.authMethod === 'key_pair') {
+                needs('privateKeyPath');
+            }
+            else if (connection.authMethod !== 'external_browser') {
+                needs('password');
+            }
+            break;
+        case 'bigquery':
+            needs('projectId');
+            break;
+        case 'duckdb':
+            needs('filepath');
+            break;
+        case 'databricks':
+            needs('host');
+            if (!connection.httpPath && !connection.warehouse)
+                missing.add('httpPath');
+            needs('token');
+            break;
+    }
+    for (const envKey of envRefs) {
+        if (!process.env[envKey])
+            missing.add(`env:${envKey}`);
+    }
+    return [...missing];
+}
+export function buildDbtStatus(projectRoot, projectConfig, lastSyncTime) {
+    const dbtProjectPath = findDbtProjectPath(projectRoot, projectConfig);
     const configuredManifest = projectConfig.dbt?.manifestPath ?? 'target/manifest.json';
     const manifestPath = resolve(dbtProjectPath, configuredManifest);
     const catalogPath = resolve(dbtProjectPath, 'target/catalog.json');
@@ -4990,7 +5494,9 @@ export function buildDbtStatus(projectRoot, projectConfig, lastSyncTime) {
     const savedQueryCount = Array.isArray(semanticManifest?.saved_queries)
         ? semanticManifest.saved_queries.length
         : 0;
-    const configured = existsSync(join(dbtProjectPath, 'dbt_project.yml')) || Boolean(configuredDbtDir || semanticDbtDir);
+    const configured = existsSync(join(dbtProjectPath, 'dbt_project.yml'))
+        || Boolean(projectConfig.dbt?.projectDir)
+        || Boolean(projectConfig.semanticLayer?.provider === 'dbt' && projectConfig.semanticLayer.projectPath);
     const manifestExists = existsSync(manifestPath);
     const semanticExists = existsSync(semanticManifestPath);
     const setupHint = !configured
@@ -5107,14 +5613,21 @@ async function execGit(cwd, args) {
         });
     });
 }
-async function readGitStatus(cwd) {
+async function resolveGitRoot(cwd) {
     const isRepo = await execGit(cwd, ['rev-parse', '--is-inside-work-tree']);
-    if (isRepo.code !== 0 || isRepo.stdout.trim() !== 'true') {
+    if (isRepo.code !== 0 || isRepo.stdout.trim() !== 'true')
+        return null;
+    const root = await execGit(cwd, ['rev-parse', '--show-toplevel']);
+    return root.code === 0 && root.stdout.trim() ? root.stdout.trim() : cwd;
+}
+async function readGitStatus(cwd) {
+    const gitRoot = await resolveGitRoot(cwd);
+    if (!gitRoot) {
         return { inRepo: false, branch: null, ahead: 0, behind: 0, changes: [] };
     }
-    const branchRes = await execGit(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
+    const branchRes = await execGit(gitRoot, ['rev-parse', '--abbrev-ref', 'HEAD']);
     const branch = branchRes.code === 0 ? branchRes.stdout.trim() : null;
-    const trackRes = await execGit(cwd, ['rev-list', '--left-right', '--count', '@{u}...HEAD']);
+    const trackRes = await execGit(gitRoot, ['rev-list', '--left-right', '--count', '@{u}...HEAD']);
     let ahead = 0;
     let behind = 0;
     if (trackRes.code === 0) {
@@ -5122,7 +5635,7 @@ async function readGitStatus(cwd) {
         behind = Number(match[0] ?? 0);
         ahead = Number(match[1] ?? 0);
     }
-    const statusRes = await execGit(cwd, ['status', '--porcelain=v1', '--untracked-files=normal']);
+    const statusRes = await execGit(gitRoot, ['status', '--porcelain=v1', '--untracked-files=normal']);
     const changes = [];
     if (statusRes.code === 0) {
         for (const line of statusRes.stdout.split('\n')) {
@@ -5136,13 +5649,13 @@ async function readGitStatus(cwd) {
     return { inRepo: true, branch, ahead, behind, changes };
 }
 async function readGitLog(cwd, limit) {
-    const isRepo = await execGit(cwd, ['rev-parse', '--is-inside-work-tree']);
-    if (isRepo.code !== 0)
+    const gitRoot = await resolveGitRoot(cwd);
+    if (!gitRoot)
         return { inRepo: false, commits: [] };
     const sep = '\x1f';
     const end = '\x1e';
     const fmt = ['%H', '%an', '%ad', '%s'].join(sep) + end;
-    const res = await execGit(cwd, ['log', `-${limit}`, `--pretty=format:${fmt}`, '--date=short']);
+    const res = await execGit(gitRoot, ['log', `-${limit}`, `--pretty=format:${fmt}`, '--date=short']);
     if (res.code !== 0)
         return { inRepo: true, commits: [] };
     const commits = [];
@@ -5205,23 +5718,97 @@ function ensureGitignoreEntry(projectRoot, pattern) {
     }
 }
 async function readGitDiff(cwd, filePath, staged = false) {
-    const isRepo = await execGit(cwd, ['rev-parse', '--is-inside-work-tree']);
-    if (isRepo.code !== 0) {
+    const gitRoot = await resolveGitRoot(cwd);
+    if (!gitRoot) {
         return { inRepo: false, diff: '', before: null, after: null, diffReport: null };
     }
     const baseArgs = staged ? ['diff', '--cached', '--no-color'] : ['diff', '--no-color'];
     if (!filePath) {
-        const res = await execGit(cwd, baseArgs);
+        const res = await execGit(gitRoot, baseArgs);
         return { inRepo: true, diff: res.stdout, before: null, after: null, diffReport: null };
     }
     const isSemantic = filePath.endsWith('.dql') || filePath.endsWith('.dqlnb');
     const [diffRes, before, after] = await Promise.all([
-        execGit(cwd, [...baseArgs, '--', filePath]),
-        isSemantic ? readHeadBlob(cwd, filePath) : Promise.resolve(null),
-        isSemantic ? readWorkingCopy(join(cwd, filePath)) : Promise.resolve(null),
+        execGit(gitRoot, [...baseArgs, '--', filePath]),
+        isSemantic ? readHeadBlob(gitRoot, filePath) : Promise.resolve(null),
+        isSemantic ? readWorkingCopy(join(gitRoot, filePath)) : Promise.resolve(null),
     ]);
+    const diffText = !staged && !diffRes.stdout.trim()
+        ? (await readUntrackedTextDiff(gitRoot, filePath)) || diffRes.stdout
+        : diffRes.stdout;
     const diffReport = isSemantic ? computeSemanticDiff(filePath, before, after) : null;
-    return { inRepo: true, diff: diffRes.stdout, before, after, diffReport };
+    return { inRepo: true, diff: diffText, before, after, diffReport };
+}
+const MAX_UNTRACKED_DIFF_FILES = 20;
+const MAX_UNTRACKED_DIFF_BYTES = 512 * 1024;
+async function readUntrackedTextDiff(cwd, filePath) {
+    const status = await execGit(cwd, ['status', '--porcelain=v1', '--untracked-files=normal', '--', filePath]);
+    if (status.code !== 0 || !status.stdout.split('\n').some((line) => line.startsWith('?? '))) {
+        return '';
+    }
+    const listed = await execGit(cwd, ['ls-files', '--others', '--exclude-standard', '--', filePath]);
+    if (listed.code !== 0)
+        return '';
+    const chunks = [];
+    let totalBytes = 0;
+    for (const rawPath of listed.stdout.split('\n').map((p) => p.trim()).filter(Boolean)) {
+        if (chunks.length >= MAX_UNTRACKED_DIFF_FILES || totalBytes >= MAX_UNTRACKED_DIFF_BYTES)
+            break;
+        const absPath = safeJoin(cwd, rawPath);
+        if (!absPath || !existsSync(absPath))
+            continue;
+        const st = statSync(absPath);
+        if (!st.isFile())
+            continue;
+        if (st.size > MAX_UNTRACKED_DIFF_BYTES) {
+            chunks.push(formatBinaryAddedDiff(rawPath));
+            continue;
+        }
+        const buf = readFileSync(absPath);
+        if (buf.includes(0)) {
+            chunks.push(formatBinaryAddedDiff(rawPath));
+            continue;
+        }
+        totalBytes += buf.length;
+        chunks.push(formatAddedFileDiff(rawPath, buf.toString('utf-8')));
+    }
+    if (chunks.length === 0)
+        return '';
+    const omitted = listed.stdout.split('\n').filter(Boolean).length - chunks.length;
+    if (omitted > 0) {
+        chunks.push(`diff --git a/${filePath} b/${filePath}\n# ${omitted} additional untracked file${omitted === 1 ? '' : 's'} omitted from preview`);
+    }
+    return chunks.join('\n');
+}
+function formatAddedFileDiff(filePath, content) {
+    const normalized = content.replace(/\r\n/g, '\n');
+    const hasFinalNewline = normalized.endsWith('\n');
+    const lines = normalized.length === 0
+        ? []
+        : normalized.split('\n').slice(0, hasFinalNewline ? -1 : undefined);
+    const hunk = lines.length > 0
+        ? [`@@ -0,0 +1,${lines.length} @@`, ...lines.map((line) => `+${line}`)]
+        : [];
+    if (!hasFinalNewline && normalized.length > 0)
+        hunk.push('\');
+    return [
+        `diff --git a/${filePath} b/${filePath}`,
+        'new file mode 100644',
+        'index 0000000..0000000',
+        '--- /dev/null',
+        `+++ b/${filePath}`,
+        ...hunk,
+    ].join('\n');
+}
+function formatBinaryAddedDiff(filePath) {
+    return [
+        `diff --git a/${filePath} b/${filePath}`,
+        'new file mode 100644',
+        'index 0000000..0000000',
+        '--- /dev/null',
+        `+++ b/${filePath}`,
+        `Binary file ${filePath} added`,
+    ].join('\n');
 }
 // ── git write operations ──────────────────────────────────────────────────
 // Each helper validates inputs, shells out via execFile (no shell expansion),
@@ -5251,89 +5838,118 @@ function gitErrorOutput(res) {
     return (res.stderr || res.stdout || '').trim();
 }
 async function gitStage(cwd, paths) {
-    const v = validatePaths(cwd, paths);
+    const gitRoot = await resolveGitRoot(cwd);
+    if (!gitRoot)
+        return { ok: false, error: 'Not a git repository' };
+    const v = validatePaths(gitRoot, paths);
     if (!v.ok)
         return { ok: false, error: v.error };
-    const res = await execGit(cwd, ['add', '--', ...v.paths]);
+    const res = await execGit(gitRoot, ['add', '--', ...v.paths]);
     return res.code === 0 ? { ok: true } : { ok: false, error: gitErrorOutput(res) };
 }
 async function gitUnstage(cwd, paths) {
-    const v = validatePaths(cwd, paths);
+    const gitRoot = await resolveGitRoot(cwd);
+    if (!gitRoot)
+        return { ok: false, error: 'Not a git repository' };
+    const v = validatePaths(gitRoot, paths);
     if (!v.ok)
         return { ok: false, error: v.error };
     // `restore --staged` works with or without HEAD; for an initial commit (no
     // HEAD yet) git's `rm --cached` is the fallback. Try restore first.
-    const res = await execGit(cwd, ['restore', '--staged', '--', ...v.paths]);
+    const res = await execGit(gitRoot, ['restore', '--staged', '--', ...v.paths]);
     if (res.code === 0)
         return { ok: true };
-    const fallback = await execGit(cwd, ['rm', '--cached', '-r', '--', ...v.paths]);
+    const fallback = await execGit(gitRoot, ['rm', '--cached', '-r', '--', ...v.paths]);
     return fallback.code === 0 ? { ok: true } : { ok: false, error: gitErrorOutput(fallback) };
 }
 async function gitDiscard(cwd, paths) {
-    const v = validatePaths(cwd, paths);
+    const gitRoot = await resolveGitRoot(cwd);
+    if (!gitRoot)
+        return { ok: false, error: 'Not a git repository' };
+    const v = validatePaths(gitRoot, paths);
     if (!v.ok)
         return { ok: false, error: v.error };
     // For tracked files: `restore --worktree` reverts to HEAD. For untracked
     // files: that's a no-op and we delete them via `clean -f`. Run both so
     // the caller doesn't have to know which list each path is in.
-    const restore = await execGit(cwd, ['restore', '--worktree', '--', ...v.paths]);
-    const clean = await execGit(cwd, ['clean', '-f', '--', ...v.paths]);
+    const restore = await execGit(gitRoot, ['restore', '--worktree', '--', ...v.paths]);
+    const clean = await execGit(gitRoot, ['clean', '-f', '--', ...v.paths]);
     if (restore.code !== 0 && clean.code !== 0) {
         return { ok: false, error: gitErrorOutput(restore) || gitErrorOutput(clean) };
     }
     return { ok: true };
 }
 async function gitCommit(cwd, message, stageAll) {
+    const gitRoot = await resolveGitRoot(cwd);
+    if (!gitRoot)
+        return { ok: false, error: 'Not a git repository' };
     const trimmed = message.trim();
     if (!trimmed)
         return { ok: false, error: 'Commit message required' };
     if (stageAll) {
-        const add = await execGit(cwd, ['add', '-A']);
+        const add = await execGit(gitRoot, ['add', '-A']);
         if (add.code !== 0)
             return { ok: false, error: gitErrorOutput(add) };
     }
-    const res = await execGit(cwd, ['commit', '-m', trimmed]);
+    const res = await execGit(gitRoot, ['commit', '-m', trimmed]);
     if (res.code !== 0)
         return { ok: false, error: gitErrorOutput(res) };
-    const hashRes = await execGit(cwd, ['rev-parse', 'HEAD']);
+    const hashRes = await execGit(gitRoot, ['rev-parse', 'HEAD']);
     return { ok: true, hash: hashRes.code === 0 ? hashRes.stdout.trim() : undefined };
 }
 async function gitPush(cwd) {
-    const res = await execGit(cwd, ['push']);
+    const gitRoot = await resolveGitRoot(cwd);
+    if (!gitRoot)
+        return { ok: false, error: 'Not a git repository' };
+    const branch = await execGit(gitRoot, ['rev-parse', '--abbrev-ref', 'HEAD']);
+    const upstream = await execGit(gitRoot, ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}']);
+    const remotes = await execGit(gitRoot, ['remote']);
+    const remote = remotes.stdout.split('\n').map((s) => s.trim()).find(Boolean) ?? 'origin';
+    const branchName = branch.code === 0 ? branch.stdout.trim() : '';
+    const args = upstream.code === 0 || !branchName || branchName === 'HEAD'
+        ? ['push']
+        : ['push', '-u', remote, branchName];
+    const res = await execGit(gitRoot, args);
     return res.code === 0
         ? { ok: true, output: gitErrorOutput(res) }
         : { ok: false, error: gitErrorOutput(res) };
 }
 async function gitPull(cwd) {
+    const gitRoot = await resolveGitRoot(cwd);
+    if (!gitRoot)
+        return { ok: false, error: 'Not a git repository' };
     // `--ff-only` keeps the operation non-destructive: if the local branch has
     // diverged from upstream, we surface the error rather than auto-merging.
     // The user can resolve via the terminal or a future merge UI.
-    const res = await execGit(cwd, ['pull', '--ff-only']);
+    const res = await execGit(gitRoot, ['pull', '--ff-only']);
     return res.code === 0
         ? { ok: true, output: gitErrorOutput(res) }
         : { ok: false, error: gitErrorOutput(res) };
 }
 async function readGitBranches(cwd) {
-    const isRepo = await execGit(cwd, ['rev-parse', '--is-inside-work-tree']);
-    if (isRepo.code !== 0)
+    const gitRoot = await resolveGitRoot(cwd);
+    if (!gitRoot)
         return { inRepo: false, current: null, branches: [] };
-    const cur = await execGit(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
-    const list = await execGit(cwd, ['branch', '--list', '--format=%(refname:short)']);
+    const cur = await execGit(gitRoot, ['rev-parse', '--abbrev-ref', 'HEAD']);
+    const list = await execGit(gitRoot, ['branch', '--list', '--format=%(refname:short)']);
     const branches = list.code === 0
         ? list.stdout.split('\n').map((s) => s.trim()).filter(Boolean)
         : [];
     return { inRepo: true, current: cur.code === 0 ? cur.stdout.trim() : null, branches };
 }
 async function readGitRemote(cwd) {
-    const isRepo = await execGit(cwd, ['rev-parse', '--is-inside-work-tree']);
-    if (isRepo.code !== 0)
+    const gitRoot = await resolveGitRoot(cwd);
+    if (!gitRoot)
         return { inRepo: false, url: null, name: null };
-    const remoteName = await execGit(cwd, ['config', '--get', 'remote.pushDefault']);
+    const remoteName = await execGit(gitRoot, ['config', '--get', 'remote.pushDefault']);
     const name = remoteName.code === 0 && remoteName.stdout.trim() ? remoteName.stdout.trim() : 'origin';
-    const url = await execGit(cwd, ['remote', 'get-url', name]);
+    const url = await execGit(gitRoot, ['remote', 'get-url', name]);
     return { inRepo: true, url: url.code === 0 ? url.stdout.trim() : null, name };
 }
 async function gitCreateBranch(cwd, name, checkout) {
+    const gitRoot = await resolveGitRoot(cwd);
+    if (!gitRoot)
+        return { ok: false, error: 'Not a git repository' };
     const trimmed = name.trim();
     // Branch names can't start with `-` (would be parsed as a flag) and must be
     // non-empty. git itself enforces the rest of the ref-name rules.
@@ -5342,17 +5958,20 @@ async function gitCreateBranch(cwd, name, checkout) {
     if (trimmed.startsWith('-'))
         return { ok: false, error: 'Invalid branch name' };
     const res = checkout
-        ? await execGit(cwd, ['checkout', '-b', trimmed])
-        : await execGit(cwd, ['branch', trimmed]);
+        ? await execGit(gitRoot, ['checkout', '-b', trimmed])
+        : await execGit(gitRoot, ['branch', trimmed]);
     return res.code === 0 ? { ok: true } : { ok: false, error: gitErrorOutput(res) };
 }
 async function gitCheckout(cwd, name) {
+    const gitRoot = await resolveGitRoot(cwd);
+    if (!gitRoot)
+        return { ok: false, error: 'Not a git repository' };
     const trimmed = name.trim();
     if (!trimmed)
         return { ok: false, error: 'Branch name required' };
     if (trimmed.startsWith('-'))
         return { ok: false, error: 'Invalid branch name' };
-    const res = await execGit(cwd, ['checkout', trimmed]);
+    const res = await execGit(gitRoot, ['checkout', trimmed]);
     return res.code === 0 ? { ok: true } : { ok: false, error: gitErrorOutput(res) };
 }
 async function readHeadBlob(cwd, filePath) {
@@ -5482,6 +6101,92 @@ function isAiPinRefreshDue(lastRefreshedAt) {
         return true;
     return Date.now() - last >= 24 * 60 * 60 * 1000;
 }
+function buildAgentSchemaContext(question, rows) {
+    const byRelation = new Map();
+    for (const row of rows) {
+        if (!row || typeof row !== 'object')
+            continue;
+        const record = row;
+        const schema = stringFromRecord(record, 'table_schema');
+        const table = stringFromRecord(record, 'table_name');
+        const column = stringFromRecord(record, 'column_name');
+        if (!schema || !table || !column)
+            continue;
+        const relation = `${schema}.${table}`;
+        const current = byRelation.get(relation) ?? {
+            relation,
+            schema,
+            name: table,
+            source: 'runtime information_schema',
+            columns: [],
+        };
+        if (current.columns.length < 80) {
+            current.columns.push({
+                name: column,
+                type: stringFromRecord(record, 'data_type'),
+            });
+        }
+        byRelation.set(relation, current);
+    }
+    const tokens = agentSchemaTokens(question);
+    return Array.from(byRelation.values())
+        .map((table) => ({ table, score: scoreAgentSchemaTable(table, tokens) }))
+        .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);
+}
+function scoreAgentSchemaTable(table, tokens) {
+    let score = 0;
+    const relationTokens = agentSchemaTokens(`${table.schema ?? ''} ${table.name} ${table.relation}`);
+    for (const token of tokens) {
+        if (relationTokens.has(token))
+            score += 8;
+    }
+    for (const column of table.columns) {
+        const columnTokens = agentSchemaTokens(column.name);
+        for (const token of tokens) {
+            if (columnTokens.has(token))
+                score += 3;
+        }
+    }
+    if (/(customer|order|revenue|product|location|date|month)/i.test(table.name))
+        score += 1;
+    return score;
+}
+function agentSchemaTokens(value) {
+    const tokens = new Set();
+    for (const raw of value.toLowerCase().match(/[a-z0-9_]+/g) ?? []) {
+        for (const part of raw.split('_')) {
+            const normalized = normalizeAgentSchemaToken(part);
+            if (!normalized || normalized.length < 3 || AGENT_SCHEMA_STOPWORDS.has(normalized))
+                continue;
+            tokens.add(normalized);
+        }
+    }
+    return tokens;
+}
+const AGENT_SCHEMA_STOPWORDS = new Set([
+    'all', 'and', 'are', 'can', 'data', 'for', 'from', 'have', 'how', 'many', 'me',
+    'show', 'the', 'this', 'who', 'with', 'value',
+]);
+function normalizeAgentSchemaToken(token) {
+    if (token === 'orders')
+        return 'order';
+    if (token === 'customers')
+        return 'customer';
+    if (token === 'products')
+        return 'product';
+    if (token.endsWith('ies') && token.length > 4)
+        return `${token.slice(0, -3)}y`;
+    if (token.endsWith('s') && token.length > 4)
+        return token.slice(0, -1);
+    return token;
+}
+function stringFromRecord(record, key) {
+    const value = record[key];
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
 function isMemoryScope(value) {
     return value === 'thread'
         || value === 'notebook'