@duckcodeailabs/dql-cli 1.6.27 → 1.6.29

package/dist/local-runtime.js

@@ -11,11 +11,13 @@ import { loadSemanticLayerFromDir, resolveSemanticLayerAsync, getDialect, Parser
 import { load as loadYaml } from 'js-yaml';
 import { listBlockTemplates } from './block-templates.js';
 import { getRunner as getLLMRunner } from './llm/index.js';
+import { createDqlAgentProviderRunner } from './llm/providers/dql-agent-provider.js';
 import { listRemoteMcpSettings, saveRemoteMcpSettings } from './llm/mcp-config.js';
-import { ClaudeProvider, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildLocalContextPack, defaultMemoryPath, ensureDefaultMemoryFiles, ensureMetadataCatalogFresh, propose, proposePlan, recordCorrectionTrace, reviewHint, AgentRunEngine, FileAgentRunStore, defaultAgentRunGates, createLlmAgentRunPlanner, narrateResult, normalizeAnthropicBaseUrl, buildProposePreview, buildFromPrompt, defaultAgentRunStorePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, loadSkills, writeSkill, deleteSkill, reindexProject, defaultKgPath, planApp, planResearch, loadSemanticMetrics, } from '@duckcodeailabs/dql-agent';
+import { ClaudeProvider, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildLocalContextPack, defaultMemoryPath, ensureDefaultMemoryFiles, ensureMetadataCatalogFresh, propose, proposePlan, recordCorrectionTrace, reviewHint, AgentRunEngine, FileAgentRunStore, defaultAgentRunGates, createLlmAgentRunPlanner, createHybridRouter, synthesizeAnswer, streamOrGenerate, narrateResult, normalizeAnthropicBaseUrl, buildProposePreview, buildFromPrompt, defaultAgentRunStorePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, loadSkills, writeSkill, deleteSkill, reindexProject, defaultKgPath, planApp, planResearch, loadSemanticMetrics, } from '@duckcodeailabs/dql-agent';
 import { gatherProposeEnrichment } from './propose-enrich.js';
-import { createAppAiBuildSession, handleAppsApi, recommendVisualization } from './apps-api.js';
+import { handleAppsApi, proposeAppAiBuild, recommendVisualization } from './apps-api.js';
 import { getActiveProvider, getEffectiveProviderConfig, listProviderSettings, saveProviderSettings, } from './settings/provider-settings.js';
+import { ClaudeCodeCliProvider, CodexCliProvider } from './providers/subscription-cli.js';
 import { DQLAccessDeniedError, activePersonaAppId, assertAppAccess, loadRuntimeApp, runtimeVariables, } from './governance-runtime.js';
 import { LocalAppStorage, LocalNotebookResearchStorage, defaultLocalAppsDbPath, defaultNotebookResearchDbPath } from '@duckcodeailabs/dql-project';
 import { Certifier, ENTERPRISE_RULES, evaluateInvariants, hasInvariantViolation, } from '@duckcodeailabs/dql-governance';
@@ -365,10 +367,11 @@ export async function startLocalServer(opts) {
         },
     });
     async function runGovernedAgentAnswerForRun(request, repair) {
-        const resolvedProvider = resolveDefaultLLMProvider(projectRoot);
-        const runner = resolvedProvider ? getLLMRunner(resolvedProvider) : null;
+        const governed = resolveGovernedAnswerRunner(projectRoot);
+        const resolvedProvider = governed?.provider ?? null;
+        const runner = governed?.runner ?? null;
         if (!resolvedProvider || !runner) {
-            throw new Error('No AI provider is configured. Configure OpenAI, Gemini, Ollama, or a custom OpenAI-compatible endpoint in Settings.');
+            throw new Error('No AI provider is configured. Configure a subscription (Claude Code / Codex), OpenAI, Gemini, Ollama, or a custom OpenAI-compatible endpoint in Settings.');
         }
         let governedAnswer;
         let providerError;
@@ -413,7 +416,7 @@ export async function startLocalServer(opts) {
         }
         return governedAnswer;
     }
-    const answerRunExecutor = async ({ request, routeDecision, attempt, repairHint }) => {
+    const answerRunExecutor = async ({ request, routeDecision, attempt, repairHint, emitAnswerDelta }) => {
         let governedAnswer;
         try {
             governedAnswer = await runGovernedAgentAnswerForRun(request, { attempt, repairHint });
@@ -443,6 +446,37 @@ export async function startLocalServer(opts) {
         const isCertified = governedAnswer.certification === 'certified' || governedAnswer.kind === 'certified';
         const needsClarification = governedAnswer.kind === 'no_answer';
         const sql = governedAnswer.proposedSql ?? governedAnswer.sql;
+        // Synthesis: for a genuinely generated (non-certified) answer, compose an
+        // adaptive, well-formatted reply over the executed rows — streamed — instead of
+        // the loop's raw draft. Certified answers keep their fast path (no extra call).
+        let synthesizedAnswer;
+        if (!needsClarification && !isCertified) {
+            try {
+                const provider = await createBlockStudioAssistProvider(projectRoot);
+                if (provider) {
+                    const preview = agentResultToSynthesisPreview(governedAnswer.result);
+                    const draft = governedAnswer.answer ?? governedAnswer.text;
+                    const result = await synthesizeAnswer({
+                        question: request.question,
+                        category: routeDecision?.category,
+                        audience: request.audience ?? 'analyst',
+                        resultPreview: preview,
+                        sql: sql,
+                        draftText: draft,
+                        gaps: governedAnswer.validationWarnings,
+                    }, {
+                        onDelta: emitAnswerDelta,
+                        complete: ({ system, user, signal, onDelta }) => streamOrGenerate(provider, [{ role: 'system', content: system }, { role: 'user', content: user }], { maxTokens: 350, temperature: 0.3, signal }, onDelta ?? (() => { })),
+                    });
+                    if (result.text)
+                        synthesizedAnswer = result.text;
+                }
+            }
+            catch {
+                // Keep the governed draft on any synthesis failure.
+                synthesizedAnswer = undefined;
+            }
+        }
         const status = needsClarification ? 'needs_clarification' : isCertified ? 'completed' : 'needs_review';
         const trustState = needsClarification ? 'not_applicable' : isCertified ? 'certified' : 'review_required';
         const stopReason = needsClarification ? 'needs_clarification' : isCertified ? 'certified_answer_found' : 'human_review_required';
@@ -455,7 +489,7 @@ export async function startLocalServer(opts) {
             ];
         return {
             summary: governedAnswer.route?.label ?? (isCertified ? 'Answered from certified DQL context.' : 'Answered with review-required generated analysis.'),
-            answer: governedAnswer.answer ?? governedAnswer.text,
+            answer: synthesizedAnswer ?? governedAnswer.answer ?? governedAnswer.text,
             status,
             trustState,
             stopReason,
@@ -476,7 +510,54 @@ export async function startLocalServer(opts) {
             nextActions,
         };
     };
+    const conversationRunExecutor = async ({ request, routeDecision, emitAnswerDelta }) => {
+        const kind = routeDecision?.conversationalKind ?? 'smalltalk';
+        const isGeneralKnowledge = routeDecision?.category === 'general_knowledge';
+        const answerKind = isGeneralKnowledge ? 'general_knowledge' : 'conversational';
+        const catalogContext = buildAgentRunCatalogContext();
+        const suggestions = buildConversationSuggestions(projectRoot, kind);
+        const nextActions = suggestions.map((prompt, index) => ({
+            id: `suggest-question-${index + 1}`,
+            label: prompt,
+        }));
+        let text;
+        try {
+            const provider = await createBlockStudioAssistProvider(projectRoot);
+            if (provider) {
+                const system = buildConversationSystemPrompt(kind, isGeneralKnowledge, catalogContext, request.audience ?? 'analyst');
+                const messages = [
+                    { role: 'system', content: system },
+                    ...(request.history ?? []).slice(-6).map((message) => ({ role: message.role, content: message.text })),
+                    { role: 'user', content: request.question },
+                ];
+                text = (await provider.generate(messages, { maxTokens: 320, temperature: 0.6 })).trim();
+                // Perceived-latency: surface the reply as one delta for surfaces wired to stream.
+                if (text)
+                    emitAnswerDelta?.(text);
+            }
+        }
+        catch {
+            // Provider unavailable / errored — fall through to the deterministic reply.
+            text = undefined;
+        }
+        if (!text) {
+            text = buildConversationalFallback(kind, isGeneralKnowledge, request.question, suggestions);
+            emitAnswerDelta?.(text);
+        }
+        return {
+            summary: 'Replied conversationally.',
+            answer: text,
+            answerKind,
+            status: 'completed',
+            trustState: 'not_applicable',
+            stopReason: 'conversational_reply',
+            artifacts: [],
+            evaluations: [],
+            nextActions,
+        };
+    };
     const agentRunExecutors = {
+        conversation: conversationRunExecutor,
         certified_answer: answerRunExecutor,
         generated_answer: answerRunExecutor,
         research: async ({ runId, request, routeDecision, emit }) => {
@@ -672,18 +753,29 @@ export async function startLocalServer(opts) {
         app_build: async ({ request, routeDecision, emit }) => {
             emit({
                 type: 'executor.started',
-                message: 'Creating app build session from governed app builder.',
+                message: 'Planning the app: matching certified blocks and finding coverage gaps.',
                 route: 'app_build',
             });
+            // Two-phase build: this run only PROPOSES the content list (no files). The
+            // user confirms the selection and the UI calls the commit endpoint directly.
             let session;
             try {
-                session = await createAppAiBuildSession(projectRoot, {
+                session = await proposeAppAiBuild(projectRoot, {
                     prompt: request.question,
                     domain: agentRunWorkspaceValue(request, 'domain'),
                     owner: agentRunWorkspaceValue(request, 'owner'),
                     notebookPath: agentRunWorkspaceValue(request, 'notebookPath') ?? request.selectedObject?.path,
                     selectedBlockIds: parseAgentRunSelectedBlockIds(request),
                     plannerMode: 'deterministic',
+                }, {
+                    generateGovernedAnswer: async (question) => {
+                        emit({
+                            type: 'executor.started',
+                            message: `Generating review-required SQL for an uncovered question: ${question}`,
+                            route: 'app_build',
+                        });
+                        return runGovernedAgentAnswerForRun({ question });
+                    },
                 });
             }
             catch (error) {
@@ -703,37 +795,46 @@ export async function startLocalServer(opts) {
                     ],
                 };
             }
-            const ready = session.status === 'ready';
+            const proposal = session.status === 'proposed' ? session.proposal : undefined;
+            // A real app needs a certified anchor: only offer confirmation when at least
+            // one certified tile is present. Otherwise fall through to the escalate path
+            // (research / draft the missing blocks) so the user isn't sent to a dead end.
+            const proposed = Boolean(proposal && proposal.tiles.some((tile) => tile.certification === 'certified' && !tile.error));
             const sessionPlan = agentRunRecord(session.plan);
-            const appTitle = agentRunString(sessionPlan?.name) ?? 'App draft';
+            const appTitle = agentRunString(sessionPlan?.name) ?? 'App proposal';
+            const certifiedCount = proposal?.coverage.certifiedTiles ?? 0;
+            const generatedCount = proposal?.coverage.generatedTiles ?? 0;
+            const gapCount = proposal?.coverage.gaps ?? 0;
             // A coverage gap is NOT terminal — leave status open so the gate can escalate to
             // drafting the missing blocks. Only genuine infra errors (the catch above) block.
             return {
-                summary: ready
-                    ? 'Created a review-required app draft session from certified DQL assets.'
-                    : 'App build needs more certified DQL coverage before files can be generated.',
-                status: ready ? 'needs_review' : undefined,
-                trustState: ready ? 'review_required' : undefined,
-                stopReason: ready ? 'human_review_required' : undefined,
-                artifacts: ready ? [agentRunArtifact('app_draft', appTitle, {
-                        session,
+                summary: proposed
+                    ? `Proposed ${certifiedCount} certified tile${certifiedCount === 1 ? '' : 's'}`
+                        + (generatedCount > 0 ? ` + ${generatedCount} AI-generated (review required)` : '')
+                        + (gapCount > 0 ? `; ${gapCount} question${gapCount === 1 ? '' : 's'} still uncovered` : '')
+                        + '. Review the list and confirm to create the app.'
+                    : 'App build needs more certified DQL coverage before a proposal can be assembled.',
+                status: proposed ? 'needs_review' : undefined,
+                trustState: proposed ? 'review_required' : undefined,
+                stopReason: proposed ? 'human_review_required' : undefined,
+                artifacts: proposed ? [agentRunArtifact('app_proposal', appTitle, {
                         sessionId: session.id,
                         appId: session.appId,
                         dashboardId: session.dashboardId,
-                        generatedPaths: session.generatedPaths,
                         plan: session.plan,
-                        validation: session.validation,
+                        proposal,
+                        warnings: session.warnings,
                     }, session.appId)] : [],
                 evaluations: [
                     agentRunEvaluation('route-decision', 'Route decision', true, 'info', routeDecision?.reason ?? 'Routed request to app build.'),
-                    agentRunEvaluation('app-coverage', 'Certified coverage', ready, ready ? 'info' : 'blocking', ready
-                        ? 'Generated app files are backed by certified block tiles and saved as a draft app session.'
+                    agentRunEvaluation('app-coverage', 'Certified coverage', proposed, proposed ? 'info' : 'blocking', proposed
+                        ? `Proposal is backed by ${certifiedCount} certified tile${certifiedCount === 1 ? '' : 's'}; nothing is created until you confirm.`
                         : session.error ?? 'No certified app tiles matched the request.', session),
                 ],
-                nextActions: ready
+                nextActions: proposed
                     ? [
-                        { id: 'open-app', label: 'Open app draft', artifactKind: 'app_draft' },
-                        { id: 'create-gap-blocks', label: 'Create DQL drafts for gaps', route: 'dql_block_draft', artifactKind: 'dql_block_draft' },
+                        { id: 'confirm-app-build', label: 'Create this app', artifactKind: 'app_proposal' },
+                        { id: 'adjust-app-build', label: 'Adjust the plan', route: 'app_build', artifactKind: 'app_proposal' },
                     ]
                     : [
                         { id: 'research-coverage', label: 'Research missing coverage', route: 'research', artifactKind: 'research_run' },
@@ -780,12 +881,29 @@ export async function startLocalServer(opts) {
         },
         getCatalogContext: buildAgentRunCatalogContext,
     });
+    // Hybrid router: keep the deterministic decision when it is confident (certified
+    // fast paths + greetings stay 0-LLM); spend one cheap classification call only for
+    // the ambiguous middle so Auto reliably picks quick-answer vs deep research without
+    // the user clicking "Dig deeper". Same provider completion as the planner.
+    const agentRunRouter = createHybridRouter({
+        complete: async ({ system, user, signal }) => {
+            const provider = await createBlockStudioAssistProvider(projectRoot);
+            if (!provider)
+                throw new Error('No AI provider configured for routing.');
+            return provider.generate([
+                { role: 'system', content: system },
+                { role: 'user', content: user },
+            ], { maxTokens: 250, temperature: 0, signal });
+        },
+        getCatalogContext: () => buildAgentRunCatalogContext(),
+    });
     const agentRunStore = new FileAgentRunStore({ path: defaultAgentRunStorePath(projectRoot) });
     const agentRunEngine = new AgentRunEngine({
         store: agentRunStore,
         executors: agentRunExecutors,
         gates: defaultAgentRunGates,
         planner: agentRunPlanner,
+        router: agentRunRouter,
     });
     const runNotebookForApp = async (appId, notebookPath) => {
         const absPath = safeJoin(projectRoot, notebookPath);
@@ -967,10 +1085,11 @@ export async function startLocalServer(opts) {
         }
     };
     const generateInvestigationSqlForApp = async (input) => {
-        const resolvedProvider = resolveDefaultLLMProvider(projectRoot);
-        const runner = resolvedProvider ? getLLMRunner(resolvedProvider) : null;
+        const governed = resolveGovernedAnswerRunner(projectRoot);
+        const resolvedProvider = governed?.provider ?? null;
+        const runner = governed?.runner ?? null;
         if (!resolvedProvider || !runner) {
-            throw new Error('No AI provider is configured. Configure OpenAI, Gemini, Ollama, or a custom OpenAI-compatible endpoint in Settings.');
+            throw new Error('No AI provider is configured. Configure a subscription (Claude Code / Codex), OpenAI, Gemini, Ollama, or a custom OpenAI-compatible endpoint in Settings.');
         }
         let governedAnswer;
         let providerError;
@@ -1182,8 +1301,9 @@ export async function startLocalServer(opts) {
             let providerError;
             const generationWarnings = [];
             if (!generatedSql && !reviewedSql) {
-                const resolvedProvider = resolveDefaultLLMProvider(projectRoot);
-                const runner = resolvedProvider ? getLLMRunner(resolvedProvider) : null;
+                const governedResearch = resolveGovernedAnswerRunner(projectRoot);
+                const resolvedProvider = governedResearch?.provider ?? null;
+                const runner = governedResearch?.runner ?? null;
                 if (!resolvedProvider || !runner) {
                     generationWarnings.push('No AI provider is configured. Metadata context was saved as a research plan; paste SQL or configure an AI provider to generate candidate SQL.');
                 }
@@ -1934,6 +2054,11 @@ export async function startLocalServer(opts) {
                     res.end(serializeJSON({ error: parsed.error ?? 'Invalid agent run request.' }));
                     return;
                 }
+                // The UI does not send retrieval signals; probe the local catalog so the
+                // router can short-circuit obvious governed matches without an LLM call.
+                if (!parsed.request.signals && !parsed.request.requestedMode) {
+                    parsed.request.signals = computeAgentRunSignals(projectRoot, parsed.request.question);
+                }
                 const wantsStream = url.searchParams.get('stream') === '1' || url.searchParams.get('stream') === 'true';
                 if (wantsStream) {
                     res.writeHead(200, {
@@ -1944,6 +2069,8 @@ export async function startLocalServer(opts) {
                     });
                     const run = await agentRunEngine.run(parsed.request, (event) => {
                         writeAgentRunSse(res, 'agent-run-event', event);
+                    }, (delta) => {
+                        writeAgentRunSse(res, 'agent-run-answer-delta', { runId: parsed.request.runId, delta });
                     });
                     writeAgentRunSse(res, 'agent-run-complete', run);
                     res.end();
@@ -2453,6 +2580,24 @@ export async function startLocalServer(opts) {
             res.end(serializeJSON({ providers: listProviderSettings(projectRoot) }));
             return;
         }
+        // Live detection for subscription-CLI providers: is the CLI installed and logged
+        // in, and (for Claude) which account/plan. Lets Settings show real status instead
+        // of a static hint. Spawns the CLIs, so it's a separate async call from the list.
+        if (req.method === 'GET' && path === '/api/settings/providers/cli-status') {
+            try {
+                const [claudeCode, codex] = await Promise.all([
+                    ClaudeCodeCliProvider.detect(),
+                    CodexCliProvider.detect(),
+                ]);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ status: { 'claude-code': claudeCode, codex } }));
+            }
+            catch (error) {
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ status: {}, error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
         if (req.method === 'POST' && path === '/api/settings/providers') {
             try {
                 const body = await readJSON(req);
@@ -2861,6 +3006,12 @@ export async function startLocalServer(opts) {
                             blocks = collectPlanBlocks(projectRoot, { certifiedOnly: false });
                         return planResearch({ question, metrics, blocks, isFollowUp });
                     },
+                    // Two-phase app build gap-fill: bounded governed answers for uncovered
+                    // questions. Throws when no provider is configured — propose degrades
+                    // gracefully by listing the gap instead.
+                    generateGovernedAnswer: (question) => runGovernedAgentAnswerForRun({ question }),
+                    // Story narration for commit — LLM-backed with deterministic fallback.
+                    narrate: narrateForAgentRun,
                 });
                 if (handled)
                     return;
@@ -6482,6 +6633,7 @@ function isLLMProviderId(value) {
     return value === 'anthropic'
         || value === 'claude-agent-sdk'
         || value === 'claude-code'
+        || value === 'codex'
         || value === 'openai'
         || value === 'gemini'
         || value === 'ollama'
@@ -6492,7 +6644,9 @@ export function resolveDefaultLLMProvider(projectRoot) {
     const activeProvider = getActiveProvider(projectRoot);
     if (activeProvider) {
         const active = settings.find((item) => item.id === activeProvider);
-        if (active?.enabled)
+        // Only return it for the chat-cell runner path if it's a runner provider id
+        // (subscription-only ids like `codex` aren't runners; they fall through).
+        if (active?.enabled && isLLMProviderId(activeProvider))
             return activeProvider;
     }
     const preferred = ['openai', 'gemini', 'anthropic', 'custom-openai', 'ollama'];
@@ -6503,6 +6657,23 @@ export function resolveDefaultLLMProvider(projectRoot) {
     }
     return null;
 }
+/**
+ * Resolve the runner that produces a GOVERNED answer (answer-loop with a completion
+ * provider). Subscription CLI providers (Claude Code / Codex) are forced through the
+ * answer-loop runner — never the MCP `claudeCodeRunner`, which doesn't emit a governed
+ * answer envelope. Everything else uses the Settings-resolved default runner.
+ */
+function resolveGovernedAnswerRunner(projectRoot) {
+    const active = getActiveProvider(projectRoot);
+    if (active === 'claude-code' || active === 'codex') {
+        return { provider: active, runner: createDqlAgentProviderRunner(active) };
+    }
+    const resolved = resolveDefaultLLMProvider(projectRoot);
+    if (!resolved)
+        return null;
+    const runner = getLLMRunner(resolved);
+    return runner ? { provider: resolved, runner } : null;
+}
 function loadAppDashboard(projectRoot, appId, dashboardId) {
     for (const p of findAppDocuments(projectRoot)) {
         const { document: app } = loadAppDocument(p);
@@ -9887,10 +10058,13 @@ async function buildBlockStudioAiAssistSummary(projectRoot, action, candidate, v
 async function createBlockStudioAssistProvider(projectRoot, requestedProvider) {
     const settings = listProviderSettings(projectRoot);
     const activeProvider = getActiveProvider(projectRoot);
+    // Subscription CLI providers (Claude Code / Codex) carry no API key — they're
+    // usable when enabled; their real "installed + logged in" check runs in available().
+    const isUsable = (provider) => provider.enabled && (provider.hasApiKey || provider.authMode === 'subscription_cli');
     const selected = requestedProvider
-        ? settings.find((provider) => provider.id === requestedProvider && provider.enabled && provider.hasApiKey)
+        ? settings.find((provider) => provider.id === requestedProvider && isUsable(provider))
         : settings.find((provider) => provider.id === activeProvider && provider.enabled)
-            ?? settings.find((provider) => provider.enabled && provider.hasApiKey);
+            ?? settings.find(isUsable);
     if (!selected)
         return null;
     const config = getEffectiveProviderConfig(projectRoot, selected.id);
@@ -9911,11 +10085,171 @@ async function createBlockStudioAssistProvider(projectRoot, requestedProvider) {
         case 'custom-openai':
             provider = new OpenAIProvider({ apiKey: config.apiKey, baseUrl: config.baseUrl, model: config.model, allowNoApiKey: true });
             break;
+        case 'claude-code':
+            provider = new ClaudeCodeCliProvider({ model: config.model });
+            break;
+        case 'codex':
+            provider = new CodexCliProvider({ model: config.model });
+            break;
         default:
             return null;
     }
     return await provider.available() ? provider : null;
 }
+/** Convert a governed answer's result payload into a bounded synthesis preview. */
+function agentResultToSynthesisPreview(result) {
+    if (!result)
+        return undefined;
+    const columns = Array.isArray(result.columns)
+        ? result.columns.map((col) => typeof col === 'string' ? col : col?.name ?? String(col))
+        : [];
+    const rawRows = Array.isArray(result.rows) ? result.rows.slice(0, 20) : [];
+    const rows = rawRows.map((row) => {
+        if (row && typeof row === 'object' && !Array.isArray(row))
+            return row;
+        // Array-shaped rows → zip with column names.
+        if (Array.isArray(row)) {
+            const obj = {};
+            row.forEach((value, index) => { obj[columns[index] ?? `col${index}`] = value; });
+            return obj;
+        }
+        return { value: row };
+    });
+    return {
+        columns: columns.length > 0 ? columns : Object.keys(rows[0] ?? {}),
+        rows,
+        rowCount: typeof result.rowCount === 'number' ? result.rowCount : rows.length,
+    };
+}
+const SIGNAL_STOPWORDS = new Set([
+    'the', 'a', 'an', 'of', 'for', 'to', 'by', 'in', 'on', 'and', 'or', 'is', 'are', 'was', 'were',
+    'what', 'which', 'how', 'show', 'me', 'my', 'our', 'this', 'that', 'top', 'give', 'get', 'list',
+]);
+function signalTokens(text) {
+    return new Set(text.toLowerCase().replace(/[^a-z0-9\s]/g, ' ').split(/\s+/)
+        .filter((token) => token.length > 2 && !SIGNAL_STOPWORDS.has(token)));
+}
+/** Best token-overlap ratio between the question and any candidate name/description. */
+function bestOverlap(questionTokens, candidates) {
+    if (questionTokens.size === 0)
+        return 0;
+    let best = 0;
+    for (const candidate of candidates) {
+        const candTokens = signalTokens(candidate);
+        if (candTokens.size === 0)
+            continue;
+        let hits = 0;
+        for (const token of candTokens)
+            if (questionTokens.has(token))
+                hits += 1;
+        if (hits === 0)
+            continue;
+        // Ratio of the candidate's tokens the question covers — rewards a tight match.
+        const ratio = hits / Math.min(candTokens.size, questionTokens.size);
+        if (ratio > best)
+            best = ratio;
+    }
+    return Math.min(1, best);
+}
+/**
+ * Cheap, offline retrieval-signal probe. Fills certifiedScore/metricScore/hasRetrieval
+ * from local catalog name/description overlap so the deterministic router can reach
+ * confidence (and skip the LLM) on obvious governed matches. Best-effort — any failure
+ * yields empty signals and the router simply leans on its LLM classification.
+ */
+function computeAgentRunSignals(projectRoot, question) {
+    try {
+        const tokens = signalTokens(question);
+        if (tokens.size === 0)
+            return { certifiedScore: 0, metricScore: 0, hasRetrieval: false };
+        const certifiedBlocks = collectPlanBlocks(projectRoot, { certifiedOnly: true });
+        const blockStrings = certifiedBlocks.flatMap((block) => [block.name, block.description ?? ''].filter(Boolean));
+        const metrics = loadSemanticMetrics(projectRoot);
+        const metricStrings = metrics.map((metric) => {
+            const node = metric;
+            return node.name ?? node.label ?? node.id ?? '';
+        }).filter(Boolean);
+        const certifiedScore = bestOverlap(tokens, blockStrings);
+        const metricScore = bestOverlap(tokens, metricStrings);
+        return { certifiedScore, metricScore, hasRetrieval: certifiedScore > 0 || metricScore > 0 };
+    }
+    catch {
+        return { certifiedScore: 0, metricScore: 0, hasRetrieval: false };
+    }
+}
+/** Up to three example questions built from real catalog blocks (falls back to generic asks). */
+function buildConversationSuggestions(projectRoot, kind) {
+    if (kind === 'gratitude')
+        return [];
+    let names = [];
+    try {
+        let blocks = collectPlanBlocks(projectRoot, { certifiedOnly: true });
+        if (blocks.length === 0)
+            blocks = collectPlanBlocks(projectRoot, { certifiedOnly: false });
+        names = blocks.slice(0, 3).map((block) => block.name).filter(Boolean);
+    }
+    catch {
+        names = [];
+    }
+    if (names.length === 0) {
+        return [
+            'What is total revenue?',
+            'Top customers by revenue this quarter',
+            'Why is revenue down by region?',
+        ];
+    }
+    const humanize = (name) => name.replace(/[_-]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+    return names.map((name) => `Show me ${humanize(name)}`);
+}
+/** The system prompt for a conversational reply — persona + capability card + catalog. */
+function buildConversationSystemPrompt(kind, isGeneralKnowledge, catalogContext, audience) {
+    const capabilities = audience === 'stakeholder'
+        ? [
+            'answer questions about their data, grounded in certified metrics and dbt lineage',
+            'run a deeper investigation when a question needs it ("dig deeper")',
+        ]
+        : [
+            'answer questions about their data, grounded in certified metrics and dbt lineage',
+            'run a deeper multi-step investigation ("dig deeper")',
+            'draft SQL cells and DQL blocks for review',
+            'build dashboards and apps from certified blocks',
+        ];
+    const lines = [
+        'You are DQL\'s assistant inside a governed analytics notebook. Be warm, concise, and helpful.',
+        `You can: ${capabilities.map((c) => `(${c})`).join(', ')}.`,
+        'Reply in at most 2-3 short sentences. Do NOT invent data values, metrics, or numbers.',
+        'If the user seems to want data, invite them to ask — their question will run through the governed loop.',
+    ];
+    if (isGeneralKnowledge) {
+        lines.push('This is a general-knowledge question. Answer from your own knowledge, plainly and briefly.', 'Do NOT imply the answer comes from the user\'s data or warehouse. If it relates to their work, offer to look at their governed data next.');
+    }
+    else if (kind === 'meta_capability') {
+        lines.push('The user is asking what you can do — briefly describe your capabilities and suggest a concrete first question.');
+    }
+    if (catalogContext) {
+        lines.push('', 'When suggesting example questions, prefer these real objects in their workspace:', catalogContext);
+    }
+    return lines.join('\n');
+}
+/** Deterministic, warm reply when no AI provider is configured — never governance-speak. */
+function buildConversationalFallback(kind, isGeneralKnowledge, question, suggestions) {
+    const examples = suggestions.length > 0
+        ? ` For example: ${suggestions.map((s) => `"${s}"`).join(', ')}.`
+        : '';
+    if (isGeneralKnowledge) {
+        return `That's a general-knowledge question, so I can't answer it from your governed data. Ask me about your metrics or dbt models and I'll ground the answer in your workspace.${examples}`;
+    }
+    switch (kind) {
+        case 'greeting':
+            return `Hi! I'm your DQL assistant — I answer questions about your data, grounded in your certified metrics and dbt lineage.${examples}`;
+        case 'gratitude':
+            return "You're welcome! Ask me anything else about your data whenever you're ready.";
+        case 'meta_capability':
+            return `I can answer questions about your data (grounded in certified metrics and dbt lineage), dig deeper with a multi-step investigation, draft SQL and DQL blocks, and build apps from certified blocks.${examples}`;
+        default:
+            return `I'm here to help you explore your data. Ask me a question and I'll ground the answer in your certified metrics and dbt models.${examples}`;
+    }
+}
 function buildDeterministicAiAssistSummary(action, candidate, validation) {
     const tables = candidate.lineage.sourceTables.length > 0 ? candidate.lineage.sourceTables.join(', ') : 'no source tables detected';
     const params = candidate.lineage.parameters.length > 0 ? candidate.lineage.parameters.join(', ') : 'no parameters detected';
@@ -11687,7 +12021,10 @@ async function testProviderConfig(projectRoot, id, overrides) {
     };
     const label = providerSettingsLabel(id);
     const details = providerConfigDetails(id, config);
-    if (!config.enabled) {
+    const isSubscriptionCli = id === 'claude-code' || id === 'codex';
+    // Subscription CLI providers are always testable — detection (installed + logged in)
+    // needs no saved config; the others require enabling/saving first.
+    if (!config.enabled && !isSubscriptionCli) {
         return { ok: false, message: `${label} is disabled. Enable it (or Save) before testing.` };
     }
     if (id === 'openai')
@@ -11702,6 +12039,12 @@ async function testProviderConfig(projectRoot, id, overrides) {
         case 'ollama':
             provider = new OllamaProvider({ baseUrl: config.baseUrl, model: config.model });
             break;
+        case 'claude-code':
+            provider = new ClaudeCodeCliProvider({ model: config.model });
+            break;
+        case 'codex':
+            provider = new CodexCliProvider({ model: config.model });
+            break;
         case 'custom-openai':
         default:
             provider = new OpenAIProvider({ apiKey: config.apiKey, baseUrl: config.baseUrl, model: config.model, allowNoApiKey: true });
@@ -11709,9 +12052,12 @@ async function testProviderConfig(projectRoot, id, overrides) {
     }
     const available = await provider.available().catch(() => false);
     if (!available) {
+        const cli = id === 'claude-code' ? 'claude' : 'codex';
         return {
             ok: false,
-            message: `${label} is not configured or reachable${details}. Check API key, base URL, and local service state.`,
+            message: isSubscriptionCli
+                ? `${label} is not ready. Install the \`${cli}\` CLI and run \`${cli} ${id === 'claude-code' ? '/login' : 'login'}\` with your subscription, then test again.`
+                : `${label} is not configured or reachable${details}. Check API key, base URL, and local service state.`,
         };
     }
     try {
@@ -11788,6 +12134,8 @@ function providerSettingsLabel(id) {
         case 'gemini': return 'Gemini';
         case 'ollama': return 'Ollama';
         case 'custom-openai': return 'Custom OpenAI-compatible provider';
+        case 'claude-code': return 'Claude subscription (Claude Code CLI)';
+        case 'codex': return 'ChatGPT subscription (Codex CLI)';
     }
 }
 function providerConfigDetails(id, config) {