@duckcodeailabs/dql-cli 1.4.4 → 1.5.0

package/{local-runtime.js → dist/local-runtime.js}

@@ -7,9 +7,13 @@ import { loadSemanticLayerFromDir, resolveSemanticLayerAsync, Parser, buildLinea
 import { load as loadYaml } from 'js-yaml';
 import { listBlockTemplates } from './block-templates.js';
 import { getRunner as getLLMRunner } from './llm/index.js';
+import { ClaudeProvider, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, defaultMemoryPath, ensureDefaultMemoryFiles, } from '@duckcodeailabs/dql-agent';
 import { handleAppsApi } from './apps-api.js';
+import { getEffectiveProviderConfig, listProviderSettings, saveProviderSettings, } from './settings/provider-settings.js';
 import { DQLAccessDeniedError, activePersonaAppId, assertAppAccess, loadRuntimeApp, runtimeVariables, } from './governance-runtime.js';
+import { LocalAppStorage, defaultLocalAppsDbPath } from '@duckcodeailabs/dql-project';
 import { buildSemanticObjectDetail, buildSemanticTree, computeSyncDiff, loadSemanticImportManifest, performSemanticImport, previewSemanticImport, syncSemanticImport, } from './semantic-import.js';
+import { createBlockStudioImportSession, loadBlockStudioImportSession, readBlockStudioImportCandidate, updateBlockStudioImportCandidate, writeBlockStudioImportCandidate, } from './block-studio-import.js';
 import { MetricFlowUnavailableError, compileMetricFlowQuery, hasDbtSemanticManifest, } from './metricflow.js';
 export async function startLocalServer(opts) {
     const { rootDir, executor, connection: rawConnection, preferredPort, projectRoot = process.cwd() } = opts;
@@ -68,6 +72,55 @@ export async function startLocalServer(opts) {
             catch { /* non-fatal */ }
         }
     }
+    const executeLocalSqlForStoredResult = async (sql) => {
+        const semantic = prepareSemanticSql(sql, 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 result = await executor.executeQuery(prepared.sql, [], runtimeVariables({}), prepared.connection);
+        return normalizeQueryResult(result, semantic.semanticRefs);
+    };
+    const executeCertifiedBlockForAgent = async (node) => {
+        if (node.kind !== 'block') {
+            throw new Error(`Certified ${node.kind} "${node.name}" is a navigation artifact and cannot be executed as a block.`);
+        }
+        const manifest = buildManifest({ projectRoot });
+        const block = manifest.blocks[node.name] ?? manifest.blocks[node.nodeId.replace(/^block:/, '')];
+        if (!block) {
+            throw new Error(`Matched block "${node.name}" is not present in the project manifest.`);
+        }
+        const absBlockPath = join(projectRoot, block.filePath);
+        const source = readFileSync(absBlockPath, 'utf-8');
+        const semanticCompose = semanticLayer
+            ? composeSemanticBlockSql(source, semanticLayer, {
+                driver: connection.driver,
+                projectRoot,
+                projectConfig,
+                detectedProvider: semanticDetectedProvider,
+            })
+            : null;
+        const plan = buildExecutionPlan({ id: `agent-${block.name}`, type: 'dql', source, title: block.name }, { semanticLayer, driver: connection.driver });
+        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.`);
+        }
+        const prepared = prepareLocalExecution(semanticCompose?.sql ?? plan.sql, connection, projectRoot, projectConfig);
+        const app = loadRuntimeApp(projectRoot, activePersonaAppId());
+        assertAppAccess({ app, domain: block.domain ?? app?.domain, level: 'execute' });
+        const rawResult = await executor.executeQuery(prepared.sql, plan?.sqlParams ?? [], runtimeVariables(plan?.variables ?? {}), prepared.connection);
+        const normalized = normalizeQueryResult(rawResult);
+        return {
+            columns: normalized.columns,
+            rows: normalized.rows,
+            rowCount: normalized.rowCount,
+            executionTime: normalized.executionTime,
+            chartConfig: plan?.chartConfig ?? (block.chartType ? { chart: block.chartType } : undefined),
+            sql: prepared.sql,
+            blockName: block.name,
+            blockPath: block.filePath,
+        };
+    };
     // SSE clients for /api/watch hot-reload
     const sseClients = new Set();
     // Watch notebooks/, workbooks/, semantic-layer/, and data/ dirs for changes
@@ -122,13 +175,56 @@ export async function startLocalServer(opts) {
             catch { /* dir not watchable */ }
         }
     }
+    const validateImportCandidate = (candidate) => ({
+        ...candidate,
+        validation: validateBlockStudioSource(candidate.dqlSource, semanticLayer),
+    });
+    const runBlockStudioPreviewSource = async (source, targetConnection = connection) => {
+        let tableMapping;
+        if (semanticLayer) {
+            try {
+                const tablesResult = await executor.executeQuery(`SELECT table_schema, table_name
+           FROM information_schema.tables
+           WHERE table_schema NOT IN ('information_schema', 'pg_catalog')`, [], {}, targetConnection);
+                tableMapping = buildSemanticTableMapping(semanticLayer, tablesResult.rows);
+            }
+            catch {
+                tableMapping = undefined;
+            }
+        }
+        const semanticCompose = semanticLayer
+            ? composeSemanticBlockSql(source, semanticLayer, {
+                driver: targetConnection.driver,
+                tableMapping,
+                projectRoot,
+                projectConfig,
+                detectedProvider: semanticDetectedProvider,
+            })
+            : null;
+        const validation = validateBlockStudioSource(source, semanticLayer);
+        const executableSql = semanticCompose?.sql ?? validation.executableSql;
+        if (!executableSql) {
+            const message = semanticCompose?.diagnostics.find((item) => item.severity === 'error')?.message
+                ?? validation.diagnostics.find((item) => item.severity === 'error')?.message
+                ?? '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 sql = resolveProjectRelativeSqlPaths(semanticCompose?.sql ?? plan?.sql ?? executableSql, projectRoot, projectConfig.dataDir);
+        const result = await executor.executeQuery(sql, plan?.sqlParams ?? [], runtimeVariables(plan?.variables ?? {}), targetConnection);
+        return {
+            sql: plan?.sql ?? executableSql,
+            result: normalizeQueryResult(result),
+            chartConfig: plan?.chartConfig ?? validation.chartConfig ?? null,
+        };
+    };
     const server = createServer(async (req, res) => {
         const requestUrl = req.url || '/';
         const url = new URL(requestUrl, 'http://127.0.0.1');
         const path = url.pathname || '/';
         // CORS — needed for dql-notebook SPA dev mode
         res.setHeader('Access-Control-Allow-Origin', '*');
-        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, OPTIONS');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
         res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
         if (req.method === 'OPTIONS') {
             res.writeHead(204);
@@ -145,6 +241,121 @@ export async function startLocalServer(opts) {
             res.end(serializeJSON({ groups: collectSettingsEnvStatus() }));
             return;
         }
+        if (req.method === 'GET' && path === '/api/settings/providers') {
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({ providers: listProviderSettings(projectRoot) }));
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/settings/providers') {
+            try {
+                const body = await readJSON(req);
+                if (!isProviderSettingsId(body?.id)) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Unknown provider id.' }));
+                    return;
+                }
+                const providers = saveProviderSettings(projectRoot, {
+                    id: body.id,
+                    enabled: typeof body.enabled === 'boolean' ? body.enabled : undefined,
+                    apiKey: typeof body.apiKey === 'string' ? body.apiKey : undefined,
+                    baseUrl: typeof body.baseUrl === 'string' ? body.baseUrl : undefined,
+                    model: typeof body.model === 'string' ? body.model : undefined,
+                });
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: true, providers }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/settings/providers/test') {
+            try {
+                const body = await readJSON(req);
+                if (!isProviderSettingsId(body?.id)) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ ok: false, error: 'Unknown provider id.' }));
+                    return;
+                }
+                const ok = await testProviderConfig(projectRoot, body.id);
+                res.writeHead(ok.ok ? 200 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(ok));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: false, error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/agent/memory') {
+            const memory = new MemoryStore(defaultMemoryPath(projectRoot));
+            try {
+                const scope = url.searchParams.get('scope') ?? undefined;
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ memories: memory.list(isMemoryScope(scope) ? scope : undefined) }));
+            }
+            finally {
+                memory.close();
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/agent/memory') {
+            const body = await readJSON(req).catch(() => null);
+            if (!body || !isMemoryScope(body.scope) || typeof body.title !== 'string' || typeof body.content !== 'string') {
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: 'scope, title, and content are required.' }));
+                return;
+            }
+            const memory = new MemoryStore(defaultMemoryPath(projectRoot));
+            try {
+                const saved = memory.upsert({
+                    id: typeof body.id === 'string' ? body.id : undefined,
+                    scope: body.scope,
+                    scopeId: typeof body.scopeId === 'string' ? body.scopeId : undefined,
+                    title: body.title,
+                    content: body.content,
+                    tags: Array.isArray(body.tags) ? body.tags.map(String) : undefined,
+                    source: typeof body.source === 'string' ? body.source : 'settings-ui',
+                    confidence: typeof body.confidence === 'number' ? body.confidence : undefined,
+                    importance: typeof body.importance === 'number' ? body.importance : undefined,
+                    validFrom: typeof body.validFrom === 'string' ? body.validFrom : undefined,
+                    validTo: typeof body.validTo === 'string' ? body.validTo : undefined,
+                    supersedes: typeof body.supersedes === 'string' ? body.supersedes : undefined,
+                    enabled: typeof body.enabled === 'boolean' ? body.enabled : undefined,
+                });
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: true, memory: saved }));
+            }
+            finally {
+                memory.close();
+            }
+            return;
+        }
+        if (req.method === 'DELETE' && path === '/api/agent/memory') {
+            const id = url.searchParams.get('id');
+            if (!id) {
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: 'id is required.' }));
+                return;
+            }
+            const memory = new MemoryStore(defaultMemoryPath(projectRoot));
+            try {
+                memory.delete(id);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: true }));
+            }
+            finally {
+                memory.close();
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/agent/memory/default-files') {
+            const files = ensureDefaultMemoryFiles(projectRoot).map((p) => relative(projectRoot, p));
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({ ok: true, files }));
+            return;
+        }
         const appDashRun = path.match(/^\/api\/apps\/([^/]+)\/dashboards\/([^/]+)\/run$/);
         if (req.method === 'POST' && appDashRun) {
             try {
@@ -162,13 +373,61 @@ export async function startLocalServer(opts) {
                     ? body.variables
                     : {};
                 const tiles = [];
+                const localApps = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
                 for (const item of loaded.dashboard.layout.items) {
+                    if (item.text) {
+                        tiles.push({
+                            tileId: item.i,
+                            status: 'ok',
+                            tileType: 'text',
+                            title: item.title,
+                            viz: item.viz,
+                            text: item.text,
+                        });
+                        continue;
+                    }
+                    if (item.aiPin) {
+                        let pin = localApps.getAiPin(item.aiPin.id);
+                        if (!pin) {
+                            tiles.push({
+                                tileId: item.i,
+                                status: 'unresolved',
+                                tileType: 'aiPin',
+                                error: `AI pin "${item.aiPin.id}" could not be found`,
+                            });
+                            continue;
+                        }
+                        if (pin.refreshCadence === 'daily' && pin.sql && isAiPinRefreshDue(pin.lastRefreshedAt)) {
+                            try {
+                                const refreshed = await executeLocalSqlForStoredResult(pin.sql);
+                                pin = localApps.updateAiPinResult(pin.id, refreshed) ?? pin;
+                            }
+                            catch (err) {
+                                pin = localApps.updateAiPinResult(pin.id, pin.result, err instanceof Error ? err.message : String(err)) ?? pin;
+                            }
+                        }
+                        tiles.push({
+                            tileId: item.i,
+                            status: 'ok',
+                            tileType: 'aiPin',
+                            title: item.title ?? pin.title,
+                            viz: item.viz,
+                            chartConfig: pin.chartConfig ?? { chart: item.viz.type },
+                            result: pin.result,
+                            aiPin: pin,
+                            citation: {
+                                kind: 'ai_pin',
+                                name: pin.title,
+                            },
+                        });
+                        continue;
+                    }
                     const block = resolveDashboardItemBlock(item, manifest);
                     if (!block) {
                         tiles.push({
                             tileId: item.i,
                             status: 'unresolved',
-                            blockRef: isBlockIdRef(item.block) ? item.block.blockId : item.block.ref,
+                            blockRef: item.block ? (isBlockIdRef(item.block) ? item.block.blockId : item.block.ref) : '(missing source)',
                             error: 'Block reference could not be resolved',
                         });
                         continue;
@@ -237,6 +496,7 @@ export async function startLocalServer(opts) {
                         }
                     }
                 }
+                localApps.close();
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({
                     appId,
@@ -254,7 +514,14 @@ export async function startLocalServer(opts) {
         // Apps, dashboards, persona — see apps-api.ts. Returns true if handled.
         if (path.startsWith('/api/apps') || path === '/api/persona') {
             try {
-                const handled = await handleAppsApi({ req, res, url, path, projectRoot });
+                const handled = await handleAppsApi({
+                    req,
+                    res,
+                    url,
+                    path,
+                    projectRoot,
+                    executeSql: executeLocalSqlForStoredResult,
+                });
                 if (handled)
                     return;
             }
@@ -972,6 +1239,110 @@ export async function startLocalServer(opts) {
             }
             return;
         }
+        if (req.method === 'POST' && path === '/api/block-studio/import/preview') {
+            try {
+                const body = await readJSON(req);
+                const inputPath = typeof body.path === 'string' ? body.path : '';
+                const session = createBlockStudioImportSession(projectRoot, {
+                    inputPath,
+                    sourceKind: typeof body.sourceKind === 'string' ? body.sourceKind : 'raw-sql',
+                    domain: typeof body.domain === 'string' ? body.domain : undefined,
+                    owner: typeof body.owner === 'string' ? body.owner : undefined,
+                    tags: Array.isArray(body.tags) ? body.tags.map(String) : undefined,
+                });
+                const candidates = session.candidates.map(validateImportCandidate);
+                const validatedSession = { ...session, candidates };
+                for (const candidate of candidates) {
+                    writeBlockStudioImportCandidate(projectRoot, session.id, candidate);
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(validatedSession));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        const importPathMatch = path.match(/^\/api\/block-studio\/imports\/([^/]+)(?:\/candidates\/([^/]+)(?:\/(run|save))?)?$/);
+        if (importPathMatch) {
+            const importId = decodeURIComponent(importPathMatch[1]);
+            const candidateId = importPathMatch[2] ? decodeURIComponent(importPathMatch[2]) : null;
+            const action = importPathMatch[3] ?? null;
+            try {
+                if (req.method === 'GET' && !candidateId) {
+                    const session = loadBlockStudioImportSession(projectRoot, importId);
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(session));
+                    return;
+                }
+                if (req.method === 'PATCH' && candidateId && !action) {
+                    const body = await readJSON(req);
+                    const reviewStatus = typeof body.reviewStatus === 'string' && ['draft', 'saved', 'rejected'].includes(body.reviewStatus)
+                        ? body.reviewStatus
+                        : undefined;
+                    const candidate = updateBlockStudioImportCandidate(projectRoot, importId, candidateId, {
+                        name: typeof body.name === 'string' ? body.name : undefined,
+                        domain: typeof body.domain === 'string' ? body.domain : undefined,
+                        description: typeof body.description === 'string' ? body.description : undefined,
+                        owner: typeof body.owner === 'string' ? body.owner : undefined,
+                        tags: Array.isArray(body.tags) ? body.tags.map(String) : undefined,
+                        sql: typeof body.sql === 'string' ? body.sql : undefined,
+                        reviewStatus,
+                    });
+                    const validated = validateImportCandidate(candidate);
+                    writeBlockStudioImportCandidate(projectRoot, importId, validated);
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(validated));
+                    return;
+                }
+                if (req.method === 'POST' && candidateId && action === 'run') {
+                    const candidate = readBlockStudioImportCandidate(projectRoot, importId, candidateId);
+                    const preview = await runBlockStudioPreviewSource(candidate.dqlSource);
+                    const next = { ...candidate, preview, validation: validateBlockStudioSource(candidate.dqlSource, semanticLayer) };
+                    writeBlockStudioImportCandidate(projectRoot, importId, next);
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(next));
+                    return;
+                }
+                if (req.method === 'POST' && candidateId && action === 'save') {
+                    const candidate = readBlockStudioImportCandidate(projectRoot, importId, candidateId);
+                    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,
+                        importMeta: {
+                            importId,
+                            candidateId,
+                            sourceKind: candidate.sourceKind,
+                            sourcePath: candidate.sourcePath,
+                        },
+                    });
+                    const next = { ...candidate, reviewStatus: 'saved', savedPath };
+                    writeBlockStudioImportCandidate(projectRoot, importId, next);
+                    const payload = openBlockStudioDocument(projectRoot, savedPath, semanticLayer);
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ candidate: next, block: payload }));
+                    return;
+                }
+                res.writeHead(405, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: 'Unsupported import operation.' }));
+            }
+            catch (error) {
+                if (error instanceof Error && error.message === 'BLOCK_EXISTS') {
+                    res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Block already exists' }));
+                    return;
+                }
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
         if (req.method === 'GET' && path === '/api/block-studio/catalog') {
             try {
                 const cfg = loadProjectConfig(projectRoot);
@@ -1037,46 +1408,9 @@ export async function startLocalServer(opts) {
                 const body = await readJSON(req);
                 const source = typeof body.source === 'string' ? body.source : '';
                 const targetConnection = isConnectionConfig(body.connection) ? body.connection : connection;
-                let tableMapping;
-                if (semanticLayer) {
-                    try {
-                        const tablesResult = await executor.executeQuery(`SELECT table_schema, table_name
-               FROM information_schema.tables
-               WHERE table_schema NOT IN ('information_schema', 'pg_catalog')`, [], {}, targetConnection);
-                        tableMapping = buildSemanticTableMapping(semanticLayer, tablesResult.rows);
-                    }
-                    catch {
-                        tableMapping = undefined;
-                    }
-                }
-                const semanticCompose = semanticLayer
-                    ? composeSemanticBlockSql(source, semanticLayer, {
-                        driver: targetConnection.driver,
-                        tableMapping,
-                        projectRoot,
-                        projectConfig,
-                        detectedProvider: semanticDetectedProvider,
-                    })
-                    : null;
-                const validation = validateBlockStudioSource(source, semanticLayer);
-                const executableSql = semanticCompose?.sql ?? validation.executableSql;
-                if (!executableSql) {
-                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
-                    const message = semanticCompose?.diagnostics.find((item) => item.severity === 'error')?.message
-                        ?? validation.diagnostics.find((item) => item.severity === 'error')?.message
-                        ?? 'No executable SQL found in block source.';
-                    res.end(serializeJSON({ error: message, diagnostics: validation.diagnostics }));
-                    return;
-                }
-                const plan = buildExecutionPlan({ id: 'block-studio', type: 'dql', source, title: 'Block Studio' }, { semanticLayer, driver: targetConnection.driver });
-                const sql = resolveProjectRelativeSqlPaths(semanticCompose?.sql ?? plan?.sql ?? executableSql, projectRoot, projectConfig.dataDir);
-                const result = await executor.executeQuery(sql, plan?.sqlParams ?? [], runtimeVariables(plan?.variables ?? {}), targetConnection);
+                const preview = await runBlockStudioPreviewSource(source, targetConnection);
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
-                res.end(serializeJSON({
-                    sql: plan?.sql ?? executableSql,
-                    result: normalizeQueryResult(result),
-                    chartConfig: plan?.chartConfig ?? validation.chartConfig ?? null,
-                }));
+                res.end(serializeJSON(preview));
             }
             catch (error) {
                 res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
@@ -1109,6 +1443,15 @@ export async function startLocalServer(opts) {
                     description: metadata.description,
                     owner: metadata.owner,
                     tags: Array.isArray(metadata.tags) ? metadata.tags.map(String) : [],
+                    lineage: Array.isArray(metadata.lineage) ? metadata.lineage.map(String) : undefined,
+                    importMeta: metadata.sourceKind || metadata.sourcePath || metadata.importId || metadata.candidateId
+                        ? {
+                            importId: metadata.importId,
+                            candidateId: metadata.candidateId,
+                            sourceKind: metadata.sourceKind,
+                            sourcePath: metadata.sourcePath,
+                        }
+                        : undefined,
                 });
                 const payload = openBlockStudioDocument(projectRoot, savedPath, semanticLayer);
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
@@ -1833,10 +2176,11 @@ export async function startLocalServer(opts) {
                 return;
             }
             const { provider, messages, upstream } = body;
-            const runner = isLLMProviderId(provider) ? getLLMRunner(provider) : null;
-            if (!runner) {
+            const resolvedProvider = isLLMProviderId(provider) ? provider : resolveDefaultLLMProvider(projectRoot);
+            const runner = resolvedProvider ? getLLMRunner(resolvedProvider) : null;
+            if (!resolvedProvider || !runner) {
                 res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
-                res.end(serializeJSON({ error: `Unknown provider: ${provider}` }));
+                res.end(serializeJSON({ error: 'No AI provider is configured. Configure OpenAI, Gemini, Ollama, or a custom OpenAI-compatible endpoint in Settings.' }));
                 return;
             }
             if (!Array.isArray(messages) || messages.length === 0) {
@@ -1853,7 +2197,7 @@ 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: provider, messages, upstream, projectRoot }, emit, controller.signal);
+                await runner.run({ provider: resolvedProvider, messages, upstream, projectRoot, executeCertifiedBlock: executeCertifiedBlockForAgent }, emit, controller.signal);
             }
             catch (err) {
                 emit({ kind: 'error', message: err instanceof Error ? err.message : String(err) });
@@ -2205,6 +2549,24 @@ export async function startLocalServer(opts) {
             }
             return;
         }
+        if (req.method === 'GET' && path === '/api/lineage/scope') {
+            try {
+                const graph = buildProjectLineageGraph(projectRoot, semanticLayer);
+                const result = buildScopedLineage(graph, {
+                    domain: url.searchParams.get('domain') ?? undefined,
+                    appId: url.searchParams.get('appId') ?? undefined,
+                    dashboardId: url.searchParams.get('dashboardId') ?? undefined,
+                    blockId: url.searchParams.get('blockId') ?? undefined,
+                });
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(result));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
         if (req.method === 'GET' && path === '/api/lineage/query') {
             try {
                 const graph = buildProjectLineageGraph(projectRoot, semanticLayer);
@@ -2404,8 +2766,10 @@ export async function startLocalServer(opts) {
                     res.end(serializeJSON({ error: 'Missing notebook cell payload.' }));
                     return;
                 }
+                const resolved = resolveNotebookBlockReferenceCell(cell, projectRoot);
+                const executableCell = resolved.cell;
                 const cellConnection = isConnectionConfig(body.connection) ? body.connection : connection;
-                const plan = buildExecutionPlan(cell, { semanticLayer, driver: cellConnection.driver });
+                const plan = buildExecutionPlan(executableCell, { semanticLayer, driver: cellConnection.driver });
                 if (!plan) {
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({ cellType: cell.type, result: null }));
@@ -2413,12 +2777,14 @@ export async function startLocalServer(opts) {
                 }
                 const prepared = prepareLocalExecution(plan.sql, isConnectionConfig(body.connection) ? body.connection : connection, projectRoot, projectConfig);
                 const app = loadRuntimeApp(projectRoot, typeof body.appId === 'string' ? body.appId : activePersonaAppId());
-                assertAppAccess({ app, domain: app?.domain, level: 'execute' });
+                assertAppAccess({ app, domain: resolved.domain ?? app?.domain, level: 'execute' });
                 const rawResult = await executor.executeQuery(prepared.sql, plan.sqlParams, runtimeVariables(plan.variables), prepared.connection);
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({
                     cellType: cell.type,
                     title: plan.title,
+                    blockName: resolved.blockName,
+                    blockPath: resolved.blockPath,
                     chartConfig: plan.chartConfig,
                     tests: plan.tests,
                     result: normalizeQueryResult(rawResult),
@@ -2549,7 +2915,18 @@ function isLLMProviderId(value) {
         || value === 'claude-code'
         || value === 'openai'
         || value === 'gemini'
-        || value === 'ollama';
+        || value === 'ollama'
+        || value === 'custom-openai';
+}
+function resolveDefaultLLMProvider(projectRoot) {
+    const settings = listProviderSettings(projectRoot);
+    const preferred = ['openai', 'gemini', 'ollama', 'custom-openai'];
+    for (const id of preferred) {
+        const provider = settings.find((item) => item.id === id);
+        if (provider?.enabled && provider.hasApiKey)
+            return id;
+    }
+    return null;
 }
 function loadAppDashboard(projectRoot, appId, dashboardId) {
     for (const p of findAppDocuments(projectRoot)) {
@@ -2566,6 +2943,8 @@ function loadAppDashboard(projectRoot, appId, dashboardId) {
     return null;
 }
 function resolveDashboardItemBlock(item, manifest) {
+    if (!item.block)
+        return null;
     if (isBlockIdRef(item.block)) {
         return manifest.blocks[item.block.blockId] ?? null;
     }
@@ -2785,6 +3164,33 @@ function normalizeNotebookCell(value) {
         config: candidate.config,
     };
 }
+function resolveNotebookBlockReferenceCell(cell, projectRoot) {
+    if (cell.type !== 'dql')
+        return { cell };
+    const match = cell.source.trim().match(/^@block\(\s*["']([^"']+)["']\s*\)$/i);
+    if (!match)
+        return { cell };
+    const ref = match[1].trim();
+    const manifest = buildManifest({ projectRoot });
+    const block = manifest.blocks[ref] ?? Object.values(manifest.blocks).find((candidate) => candidate.filePath === ref);
+    if (!block) {
+        throw new Error(`Block reference "${ref}" could not be resolved.`);
+    }
+    const blockPath = join(projectRoot, block.filePath);
+    if (!existsSync(blockPath)) {
+        throw new Error(`Block "${block.name}" file is missing: ${block.filePath}`);
+    }
+    return {
+        cell: {
+            ...cell,
+            title: cell.title ?? block.name,
+            source: readFileSync(blockPath, 'utf-8'),
+        },
+        blockName: block.name,
+        blockPath: block.filePath,
+        domain: block.domain,
+    };
+}
 function isConnectionConfig(value) {
     return Boolean(value && typeof value === 'object' && 'driver' in value);
 }
@@ -3362,6 +3768,8 @@ function saveBlockStudioArtifacts(projectRoot, options) {
         tags: options.tags,
         provider: 'dql',
         content: options.source,
+        lineage: options.lineage,
+        importMeta: options.importMeta,
     });
     if (previousPath && previousPath !== targetRelativePath) {
         const previousAbsPath = join(projectRoot, previousPath);
@@ -3769,6 +4177,17 @@ function writeBlockCompanionFile(projectRoot, options) {
         if (options.gitPath)
             lines.push(`  path: ${yamlScalar(options.gitPath)}`);
     }
+    if (options.importMeta) {
+        lines.push('import:');
+        if (options.importMeta.importId)
+            lines.push(`  importId: ${yamlScalar(options.importMeta.importId)}`);
+        if (options.importMeta.candidateId)
+            lines.push(`  candidateId: ${yamlScalar(options.importMeta.candidateId)}`);
+        if (options.importMeta.sourceKind)
+            lines.push(`  sourceKind: ${yamlScalar(options.importMeta.sourceKind)}`);
+        if (options.importMeta.sourcePath)
+            lines.push(`  sourcePath: ${yamlScalar(options.importMeta.sourcePath)}`);
+    }
     lines.push('reviewStatus: draft');
     writeFileSync(companionPath, lines.join('\n') + '\n', 'utf-8');
     return relative(projectRoot, companionPath).replaceAll('\\', '/');
@@ -3994,6 +4413,38 @@ function resolveLineageNode(graph, rawNodeId) {
     const result = queryLineage(graph, { focus: rawNodeId });
     return result.focalNode;
 }
+function buildScopedLineage(graph, scope) {
+    const focus = scope.blockId
+        ? `block:${scope.blockId}`
+        : scope.dashboardId
+            ? `dashboard:${scope.appId ? `${scope.appId}/${scope.dashboardId}` : scope.dashboardId}`
+            : scope.appId
+                ? `app:${scope.appId}`
+                : undefined;
+    const result = queryLineage(graph, {
+        focus,
+        domain: focus ? undefined : scope.domain,
+        upstreamDepth: 8,
+        downstreamDepth: 4,
+    });
+    const graphJson = result.graph ?? graph.toJSON();
+    const breadcrumbs = [
+        scope.domain ? graph.getNode(`domain:${scope.domain}`) : null,
+        scope.appId ? graph.getNode(`app:${scope.appId}`) : null,
+        scope.dashboardId ? graph.getNode(`dashboard:${scope.appId ? `${scope.appId}/${scope.dashboardId}` : scope.dashboardId}`) : null,
+        scope.blockId ? graph.getNode(`block:${scope.blockId}`) : null,
+    ].filter(Boolean);
+    const paths = focus ? queryCompleteLineagePaths(graph, focus, { maxDepth: 12, maxPaths: 20 }) : null;
+    return {
+        scope,
+        focus,
+        graph: graphJson,
+        focalNode: result.focalNode,
+        breadcrumbs,
+        paths,
+        view: 'Domain > App > Dashboard tab > Tile > Block > Semantic/dbt/source',
+    };
+}
 function extractProp(block, key) {
     // Check direct AST fields first (parser puts domain, owner, type directly on the node)
     if (block[key] !== undefined && block[key] !== null)
@@ -4354,4 +4805,55 @@ function collectSettingsEnvStatus() {
         },
     ];
 }
+function isProviderSettingsId(value) {
+    return value === 'anthropic'
+        || value === 'openai'
+        || value === 'gemini'
+        || value === 'ollama'
+        || value === 'custom-openai';
+}
+async function testProviderConfig(projectRoot, id) {
+    const config = getEffectiveProviderConfig(projectRoot, id);
+    let provider;
+    switch (id) {
+        case 'anthropic':
+            provider = new ClaudeProvider({ apiKey: config.apiKey, model: config.model });
+            break;
+        case 'gemini':
+            provider = new GeminiProvider({ apiKey: config.apiKey, model: config.model });
+            break;
+        case 'ollama':
+            provider = new OllamaProvider({ baseUrl: config.baseUrl, model: config.model });
+            break;
+        case 'custom-openai':
+            provider = new OpenAIProvider({ apiKey: config.apiKey, baseUrl: config.baseUrl, model: config.model, allowNoApiKey: true });
+            break;
+        case 'openai':
+        default:
+            provider = new OpenAIProvider({ apiKey: config.apiKey, baseUrl: config.baseUrl, model: config.model });
+            break;
+    }
+    const ok = await provider.available();
+    return {
+        ok,
+        message: ok
+            ? `${id} is configured.`
+            : `${id} is not configured or not reachable. Check API key, base URL, and local service state.`,
+    };
+}
+function isAiPinRefreshDue(lastRefreshedAt) {
+    if (!lastRefreshedAt)
+        return true;
+    const last = Date.parse(lastRefreshedAt);
+    if (!Number.isFinite(last))
+        return true;
+    return Date.now() - last >= 24 * 60 * 60 * 1000;
+}
+function isMemoryScope(value) {
+    return value === 'thread'
+        || value === 'notebook'
+        || value === 'project'
+        || value === 'user'
+        || value === 'artifact';
+}
 //# sourceMappingURL=local-runtime.js.map