@duckcodeailabs/dql-cli 1.14.2 → 1.14.4

package/dist/commands/agent.js

@@ -23,15 +23,18 @@
  */
 import { answerFromRuntimeRun, driveViaRuntime, projectRuntimeRun, } from './agent-eval-runtime.js';
 import { CassetteStore, cassetteEvidenceSummary, cassetteDirFor, evalCassetteCanonicalizationV2, withCassette, } from './agent-eval-cassette.js';
+import { runAgentShadowReport } from './agent-shadow-report.js';
 import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { load as loadYaml } from 'js-yaml';
-import { KGStore, MemoryStore, defaultKgPath, defaultMemoryPath, reindexProject, loadSkills, pickProvider, answer, resolveDomainContextEnvelope, buildAnalysisQuestionPlan, buildLocalContextPack, coerceReasoningEffort, contextRetrievalBudgetForQuestion, deriveGeneratedDraftSlug, loadAgentSemanticLayer, recordQueryRun, recordRuntimeSchemaSnapshot, upsertGeneratedDqlArtifactDraft, upsertGeneratedDraft, validateSqlAgainstLocalContext, } from '@duckcodeailabs/dql-agent';
+import { AskTraceSqliteStoreV1, KGStore, MemoryStore, defaultKgPath, defaultMemoryPath, reindexProject, loadSkills, pickProvider, answer, resolveDomainContextEnvelope, buildAnalysisQuestionPlan, buildLocalContextPack, classifyProviderFailure, coerceReasoningEffort, contextRetrievalBudgetForQuestion, deriveGeneratedDraftSlug, loadAgentSemanticLayer, recordQueryRun, recordRuntimeSchemaSnapshot, upsertGeneratedDqlArtifactDraft, upsertGeneratedDraft, validateSqlAgainstLocalContext, createAskTraceObserverV1, defaultAskTraceSqlitePath, } from '@duckcodeailabs/dql-agent';
+import { createHash, randomUUID } from 'node:crypto';
 import { buildManifest, resolveDbtManifestPath } from '@duckcodeailabs/dql-core';
 import { findProjectRoot } from '../local-runtime.js';
 import { buildAnswerLoopTools, createGroundingContextExpander } from '../llm/answer-loop-tools.js';
 import { judgeAnswer } from './eval-judge.js';
 import { startProjectRuntime } from './notebook.js';
+import { runAgentTrace } from './agent-trace.js';
 /**
  * Resolve the runtime the agent posts certified blocks / generated SQL to.
  *
@@ -55,7 +58,56 @@ async function resolveAgentRuntime(projectRoot, flags) {
         return { runtimeBase: base, close: async () => { } };
     }
     const handle = await startProjectRuntime(projectRoot, { preferredPort: 0 });
-    return { runtimeBase: handle.url, close: handle.close };
+    return { runtimeBase: handle.url, close: handle.close, askTraceCapability: handle.askTraceCapability };
+}
+function isLoopbackRuntimeUrl(runtimeBase) {
+    try {
+        const hostname = new URL(runtimeBase).hostname;
+        return hostname === '127.0.0.1' || hostname === 'localhost' || hostname === '::1' || hostname === '[::1]';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * An already-running local Notebook runtime mints a one-shot, loopback-only
+ * capability for this CLI request. Remote runtimes deliberately receive no
+ * capability and therefore cannot be relabelled as CLI by arbitrary text.
+ */
+export async function requestLoopbackCliAskTraceCapability(runtimeBase) {
+    if (!isLoopbackRuntimeUrl(runtimeBase))
+        return undefined;
+    try {
+        const response = await fetch(`${runtimeBase.replace(/\/$/, '')}/api/ask-traces/cli-capability`, {
+            headers: { Accept: 'application/json' },
+        });
+        if (!response.ok)
+            return undefined;
+        const payload = await response.json();
+        return typeof payload.capability === 'string'
+            && typeof payload.expiresAt === 'string'
+            && payload.scope === 'agent-runs'
+            ? payload.capability
+            : undefined;
+    }
+    catch {
+        // A pre-observability runtime remains usable. Its request stays browser
+        // attributed rather than fabricating a client-controlled CLI surface.
+        return undefined;
+    }
+}
+function runtimeProviderForCliFlag(value) {
+    if (typeof value !== 'string' || !value.trim())
+        return undefined;
+    switch (value.trim().toLowerCase()) {
+        case 'claude': return 'anthropic';
+        case 'openai': return 'openai';
+        case 'gemini': return 'gemini';
+        case 'ollama': return 'ollama';
+        // Preserve an invalid explicit value through the host request so the
+        // canonical preflight can return a typed `model_not_found` diagnostic.
+        default: return value.trim().toLowerCase();
+    }
 }
 async function fetchRuntimeSchemaContext(runtimeBase) {
     try {
@@ -142,6 +194,137 @@ function cliAnalysisDepth(flags) {
     const value = flags.analysisDepth?.trim().toLowerCase();
     return value === 'quick' || value === 'deep' ? value : undefined;
 }
+/**
+ * Compatibility test adapter for a standalone provider boundary. Production
+ * `dql agent ask` no longer calls this: it uses the runtime AgentRun engine so
+ * the router, cascade, freeze, tools, SQL, and provider spans share one
+ * canonical trace. Keep this adapter truthful for lower-level provider tests
+ * without making it an alternate orchestration authority.
+ */
+export function createDirectCliAskTraceProvider(provider, trace) {
+    let attemptIndex = 0;
+    let lastFailedSpanId;
+    const pending = new Map();
+    const keyFor = (event) => `${event.provider}:${event.operation}:${event.attemptIndex}`;
+    const attempt = (event, retryOfSpanId) => ({
+        version: 1,
+        phase: 'generation',
+        physicalAttemptIndex: ++attemptIndex,
+        providerFingerprint: `sha256:${createHash('sha256').update(event.provider).digest('hex')}`,
+        ...(event.model ? { modelFingerprint: `sha256:${createHash('sha256').update(event.model).digest('hex')}` } : {}),
+        ...(retryOfSpanId ? { retryOfSpanId } : {}),
+        admission: 'admitted',
+        provenance: 'live',
+    });
+    const finish = (entry, outcome, error) => {
+        if (!entry.spanId)
+            return;
+        const diagnostic = outcome === 'ok' ? undefined : classifyProviderFailure({
+            phase: 'generation',
+            code: error && typeof error === 'object' ? String(error.code ?? '') : undefined,
+            message: error instanceof Error ? error.message : String(error ?? ''),
+            providerFingerprint: entry.attempt.providerFingerprint,
+            modelFingerprint: entry.attempt.modelFingerprint,
+        });
+        const finalAttempt = outcome === 'ok'
+            ? entry.attempt
+            : {
+                ...entry.attempt,
+                ...(diagnostic?.httpStatusClass ? { httpStatusClass: diagnostic.httpStatusClass } : {}),
+                ...(diagnostic ? { retryable: diagnostic.retryable, safeAction: diagnostic.safeAction } : {}),
+                cause: outcome === 'cancelled' ? 'cancelled' : diagnostic?.cause ?? 'unknown',
+            };
+        trace.finishSpan(entry.spanId, {
+            outcome: outcome === 'ok' ? 'ok' : outcome === 'cancelled' ? 'cancelled' : 'error',
+            reasonCode: outcome === 'ok' ? 'completed' : outcome === 'cancelled' ? 'cancelled' : 'provider_failure',
+            payload: { kind: 'provider', attempt: finalAttempt },
+        });
+        if (outcome !== 'ok')
+            lastFailedSpanId = entry.spanId;
+    };
+    const observedOptions = (options = {}) => ({
+        ...options,
+        onProviderDispatch: (event) => {
+            const tracedAttempt = attempt(event, lastFailedSpanId);
+            const spanId = trace.startSpan({
+                name: 'provider.attempt',
+                stage: 'provider',
+                reasonCode: 'started',
+                payload: { kind: 'provider', attempt: tracedAttempt },
+            });
+            const key = keyFor(event);
+            pending.set(key, [...(pending.get(key) ?? []), { spanId, attempt: tracedAttempt }]);
+            return options.onProviderDispatch?.(event) ?? event.envelope;
+        },
+        onProviderDispatchComplete: (event) => {
+            const key = keyFor(event);
+            const entries = pending.get(key) ?? [];
+            const entry = entries[0];
+            if (entry && event.outcome === 'ok' && (event.settlement === 'transport' || event.settlement === 'process')) {
+                entry.attempt = {
+                    ...entry.attempt,
+                    ...(event.settlement === 'transport' ? { transportOutcome: 'ok' } : { processOutcome: 'ok' }),
+                };
+            }
+            else {
+                const closed = entries.shift();
+                if (entries.length > 0)
+                    pending.set(key, entries);
+                else
+                    pending.delete(key);
+                if (closed)
+                    finish(closed, event.outcome, event.error ?? (typeof event.httpStatus === 'number' ? Object.assign(new Error(`HTTP ${event.httpStatus}`), { code: `HTTP_${event.httpStatus}` }) : undefined));
+            }
+            options.onProviderDispatchComplete?.(event);
+        },
+        onProviderDispatchRejected: (event) => {
+            const denied = trace.startSpan({
+                name: 'provider.attempt',
+                stage: 'provider',
+                reasonCode: 'provider_failure',
+                payload: {
+                    kind: 'provider',
+                    attempt: {
+                        ...attempt(event, lastFailedSpanId),
+                        admission: 'denied',
+                    },
+                },
+            });
+            trace.finishSpan(denied, { outcome: 'denied', reasonCode: 'provider_failure' });
+            lastFailedSpanId = denied;
+            options.onProviderDispatchRejected?.(event);
+        },
+    });
+    const invoke = async (options, call) => {
+        try {
+            const result = await call(observedOptions(options));
+            for (const entries of pending.values())
+                for (const entry of entries)
+                    finish(entry, 'ok');
+            pending.clear();
+            return result;
+        }
+        catch (error) {
+            const outcome = options?.signal?.aborted ? 'cancelled' : 'error';
+            for (const entries of pending.values())
+                for (const entry of entries)
+                    finish(entry, outcome, error);
+            pending.clear();
+            throw error;
+        }
+    };
+    return {
+        name: provider.name,
+        available: () => provider.available(),
+        generate: (messages, options) => invoke(options, (observed) => provider.generate(messages, observed)),
+        ...(provider.generateWithTools ? {
+            generateWithTools: (messages, tools, options) => invoke(options, (observed) => provider.generateWithTools(messages, tools, observed)),
+        } : {}),
+        ...(provider.generateStream ? {
+            generateStream: (messages, options, onDelta) => invoke(options, (observed) => provider.generateStream(messages, observed, onDelta)),
+        } : {}),
+    };
+}
 /** A DQL runtime answers `/api/connections` with a connector/connection payload. */
 async function isDqlRuntime(base) {
     try {
@@ -161,25 +344,53 @@ export async function runAgent(sub, rest, flags) {
             return runAsk(rest, flags);
         case 'threads':
             return runThreads(flags);
+        case 'trace':
+            return runAgentTrace(rest, flags);
         case 'reindex':
             return runReindex(rest, flags);
         case 'feedback':
             return runFeedback(rest, flags);
         case 'eval':
             return runEval(rest, flags);
+        case 'shadow-report':
+            return runAgentShadowReport(rest, flags);
         default:
-            throw new Error('Usage: dql agent <ask|threads|reindex|feedback|eval> [args]\n' +
+            throw new Error('Usage: dql agent <ask|threads|trace|reindex|feedback|eval|shadow-report> [args]\n' +
                 '  dql agent ask "<question>" [--provider claude|openai|gemini|ollama] [--user <id>] [--domain <d>] [--purpose <approved-purpose>] [--thread <id>]\n' +
                 '  dql agent threads [--runtime-url <url>]\n' +
+                '  dql agent trace list|show|export|validate|replay|compare\n' +
                 '  dql agent reindex [path]\n' +
                 '  dql agent feedback up|down --block <id> --question "..."\n' +
-                '  dql agent eval agent-evals.yml [--provider claude|openai|gemini|ollama] [--execute] [--save]');
+                '  dql agent eval agent-evals.yml [--provider claude|openai|gemini|ollama] [--execute] [--save]\n' +
+                '  dql agent shadow-report [path] [--json] [--limit <n>]   Compare what V1 answered with what V2 would have done');
     }
 }
+/**
+ * Canonical CLI Ask entrypoint. Direct and threaded CLI questions use the
+ * exact local AgentRun engine as the browser, so trace evidence follows the
+ * router's candidate/cascade/freeze/execution authority rather than a legacy
+ * answer-loop approximation.
+ */
 async function runAsk(rest, flags) {
     const question = rest.join(' ').trim();
     if (!question)
         throw new Error('Usage: dql agent ask "<question>"');
+    const threadId = flags.thread;
+    return threadId
+        ? runThreadAsk(question, threadId, flags)
+        : runCanonicalCliAsk(question, undefined, flags);
+}
+/**
+ * Compatibility entrypoint retained for downstream imports during the CLI
+ * transition. It deliberately delegates before allocating any legacy state,
+ * so even an old internal caller gets the canonical AgentRun trace rather than
+ * an incomplete synthetic receipt.
+ */
+async function runLegacyDirectAsk(rest, flags) {
+    const question = rest.join(' ').trim();
+    if (!question)
+        throw new Error('Usage: dql agent ask "<question>"');
+    return runCanonicalCliAsk(question, flags.thread, flags);
     // Thread-scoped ask: hand the question to the runtime's agent-run engine with
     // the thread id, so the SERVER injects prior turns and persists this run as a
     // new turn (the same conversation store the notebook UI uses).
@@ -187,8 +398,31 @@ async function runAsk(rest, flags) {
     if (threadId)
         return runThreadAsk(question, threadId, flags);
     const projectRoot = findProjectRoot(process.cwd());
+    const traceStore = new AskTraceSqliteStoreV1({ path: defaultAskTraceSqlitePath(projectRoot) });
+    const trace = createAskTraceObserverV1({
+        store: traceStore,
+        runId: `cli-${randomUUID()}`,
+        surface: 'cli',
+        mode: 'ask',
+        questionFingerprint: `sha256:${createHash('sha256').update(question).digest('hex')}`,
+    });
+    const classifySpan = trace.startSpan({
+        name: 'request.classify',
+        stage: 'request',
+        reasonCode: 'started',
+        payload: { kind: 'stage', route: 'direct_cli_legacy' },
+    });
     const kgPath = defaultKgPath(projectRoot);
-    await reindexProject(projectRoot, { kgPath });
+    try {
+        await reindexProject(projectRoot, { kgPath });
+        trace.finishSpan(classifySpan, { outcome: 'ok', reasonCode: 'completed' });
+    }
+    catch (error) {
+        trace.finishSpan(classifySpan, { outcome: 'error', reasonCode: 'unknown' });
+        trace.finalize({ status: 'failed' });
+        traceStore.close();
+        throw error;
+    }
     const providerName = flags.provider;
     const userId = flags.user;
     const domain = flags.domain;
@@ -196,12 +430,68 @@ async function runAsk(rest, flags) {
     const format = flags.format;
     const reasoningEffort = cliReasoningEffort(flags);
     const requestedDepth = cliAnalysisDepth(flags);
-    const provider = await pickProvider(providerName);
+    let provider;
+    try {
+        provider = await pickProvider(providerName);
+    }
+    catch (error) {
+        trace.finalize({ status: 'failed' });
+        traceStore.close();
+        throw error;
+    }
     const kg = new KGStore(kgPath);
     const memory = new MemoryStore(defaultMemoryPath(projectRoot));
     const { skills } = loadSkills(projectRoot);
     let closeRuntime;
     try {
+        const preflight = trace.startSpan({
+            name: 'provider.preflight',
+            stage: 'provider',
+            reasonCode: 'started',
+            payload: {
+                kind: 'provider',
+                attempt: {
+                    version: 1,
+                    phase: 'preflight',
+                    physicalAttemptIndex: 0,
+                    providerFingerprint: `sha256:${createHash('sha256').update(provider.name).digest('hex')}`,
+                    readiness: 'unknown',
+                    admission: 'unknown',
+                    provenance: 'live',
+                },
+            },
+        });
+        let providerReady = false;
+        try {
+            providerReady = await provider.available();
+        }
+        catch {
+            providerReady = false;
+        }
+        trace.finishSpan(preflight, {
+            outcome: providerReady ? 'ok' : 'unavailable',
+            reasonCode: providerReady ? 'completed' : 'provider_preflight',
+            payload: {
+                kind: 'provider',
+                attempt: {
+                    version: 1,
+                    phase: 'preflight',
+                    physicalAttemptIndex: 0,
+                    providerFingerprint: `sha256:${createHash('sha256').update(provider.name).digest('hex')}`,
+                    readiness: providerReady ? 'ready' : 'unavailable',
+                    admission: 'unknown',
+                    cause: providerReady ? undefined : 'authentication',
+                    safeAction: providerReady ? undefined : 'fix_provider_configuration',
+                    provenance: 'live',
+                },
+            },
+        });
+        if (!providerReady) {
+            throw Object.assign(new Error('The selected AI provider is not ready. Configure or sign in to the provider and retry.'), {
+                code: 'AUTHENTICATION_FAILED',
+            });
+        }
+        const tracedProvider = createDirectCliAskTraceProvider(provider, trace);
         const memoryContext = memory.search({
             query: question,
             scopes: ['project', 'user', 'artifact'],
@@ -220,6 +510,12 @@ async function runAsk(rest, flags) {
         closeRuntime = close;
         const schemaContext = await fetchRuntimeSchemaContext(runtimeBase);
         recordCliRuntimeSchemaSnapshot(projectRoot, schemaContext, 'direct CLI runtime schema');
+        const retrievalSpan = trace.startSpan({
+            name: 'retrieval',
+            stage: 'retrieval',
+            reasonCode: 'started',
+            payload: { kind: 'retrieval', candidateCount: 0 },
+        });
         const contextPack = await buildLocalContextPack(projectRoot, {
             question,
             surface: 'cli',
@@ -233,10 +529,15 @@ async function runAsk(rest, flags) {
                 }
                 : undefined,
         }).catch(() => undefined);
+        trace.finishSpan(retrievalSpan, {
+            outcome: 'ok',
+            reasonCode: 'completed',
+            payload: { kind: 'retrieval', candidateCount: contextPack?.objects.length ?? 0 },
+        });
         const answerLoopTools = buildAnswerLoopTools(projectRoot);
         const result = await answer({
             question,
-            provider,
+            provider: tracedProvider,
             kg,
             manifest,
             skills,
@@ -365,6 +666,7 @@ async function runAsk(rest, flags) {
                 });
             },
         });
+        trace.finalize({ status: 'completed' });
         if (format === 'json') {
             console.log(JSON.stringify(result, null, 2));
             return;
@@ -379,17 +681,25 @@ async function runAsk(rest, flags) {
             : '';
         const footer = result.provenanceFooter ? `\n\n— ${result.provenanceFooter}` : '';
         console.log(`${badge}\n\n${result.text}${footer}${cite}`);
-        if (result.result) {
-            console.log(`\nRows: ${result.result.rowCount}`);
-            console.log(JSON.stringify(result.result.rows.slice(0, 5), null, 2));
+        const resultPayload = result.result;
+        if (resultPayload) {
+            console.log(`\nRows: ${resultPayload.rowCount}`);
+            console.log(JSON.stringify(resultPayload.rows.slice(0, 5), null, 2));
         }
         printDqlArtifactPreview(result);
     }
+    catch (error) {
+        const cancelled = error instanceof Error && error.name === 'AbortError';
+        trace.finalize({ status: cancelled ? 'cancelled' : 'failed' });
+        throw error;
+    }
     finally {
         kg.close();
         memory.close();
-        if (closeRuntime)
-            await closeRuntime();
+        const close = closeRuntime;
+        if (close)
+            await close();
+        traceStore.close();
     }
 }
 function printDqlArtifactPreview(result) {
@@ -410,56 +720,103 @@ function printDqlArtifactPreview(result) {
             console.log(`Promote: ${result.promoteCommand}`);
     }
 }
+function printCanonicalCliAskRun(run, threadId) {
+    const badge = run.trustState === 'certified'
+        ? '✓ Certified'
+        : run.trustState === 'grounded'
+            ? '✓ Verified (grounded)'
+            : run.trustState === 'review_required'
+                ? '! AI-generated · review required'
+                : run.trustState === 'blocked'
+                    ? '✕ Blocked'
+                    : '· Reply';
+    console.log(`${badge}\n\n${(run.answer ?? run.summary ?? '').trim()}`);
+    if (threadId)
+        console.log(`\nThread: ${threadId}`);
+    const trace = run.traceReference;
+    if (trace?.traceId) {
+        console.log(`\nTrace: ${trace.traceId} (${trace.recordingStatus ?? 'recording'})`);
+    }
+    else {
+        console.log('\nTrace: unavailable');
+    }
+}
 /**
- * `dql agent ask --thread <id>` — POST the question to the runtime's
- * `/api/agent-runs` with the threadId in the body. The server injects the
- * thread's prior turns into the conversation context and records the completed
- * run as the next turn, so follow-ups resolve "those"/"that product" correctly
- * across CLI invocations (and across the notebook UI, which shares the store).
+ * Submit every user-visible CLI Ask through the runtime AgentRun endpoint.
+ * The runtime owns run IDs, conversation hydration, candidate provenance,
+ * cascade/freeze authority, physical tool/SQL execution, and final trace
+ * reference. The CLI only supplies user intent and an optional host-minted
+ * surface capability.
  */
-async function runThreadAsk(question, threadId, flags) {
+export async function runCanonicalCliAsk(question, threadId, flags) {
     const projectRoot = findProjectRoot(process.cwd());
     const format = flags.format;
-    const { runtimeBase, close } = await resolveAgentRuntime(projectRoot, flags);
+    const { runtimeBase, close, askTraceCapability: embeddedCapability } = await resolveAgentRuntime(projectRoot, flags);
     try {
+        const askTraceCapability = embeddedCapability ?? await requestLoopbackCliAskTraceCapability(runtimeBase);
         const reasoningEffort = cliReasoningEffort(flags);
         const analysisDepth = cliAnalysisDepth(flags);
+        const domain = flags.domain;
+        const purpose = flags.purpose || undefined;
+        const userId = flags.user;
+        const provider = runtimeProviderForCliFlag(flags.provider);
+        // `surface` is deliberately absent from public JSON. The runtime assigns
+        // trace surface only after consuming its own loopback capability; this
+        // context carries user intent, never attribution authority.
+        const workspaceContext = {
+            ...(domain ? { domain } : {}),
+            ...(purpose ? { purpose } : {}),
+            ...(userId ? { userId } : {}),
+            ...(provider ? { provider } : {}),
+        };
+        const hasWorkspaceContext = Object.keys(workspaceContext).length > 0;
         const response = await fetch(`${runtimeBase.replace(/\/$/, '')}/api/agent-runs`, {
             method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
+            headers: {
+                'Content-Type': 'application/json',
+                ...(askTraceCapability ? { 'X-DQL-Ask-Trace-Capability': askTraceCapability } : {}),
+            },
             body: JSON.stringify({
                 question,
-                threadId,
+                ...(threadId ? { threadId } : {}),
                 ...(reasoningEffort ? { reasoningEffort } : {}),
                 ...(analysisDepth ? { analysisDepth } : {}),
+                ...(hasWorkspaceContext ? { workspaceContext } : {}),
             }),
         });
         if (!response.ok)
             throw new Error(`Runtime returned ${response.status}: ${await response.text()}`);
         const payload = (await response.json());
-        if (!payload.run)
-            throw new Error('Runtime did not return an agent run.');
+        if (!payload.run?.id)
+            throw new Error('Runtime did not return a canonical agent run.');
+        const run = payload.run;
         if (format === 'json') {
-            console.log(JSON.stringify(payload.run, null, 2));
+            // Preserve the established top-level run shape while adding compact,
+            // content-free trace discoverability for scripts and support bundles.
+            console.log(JSON.stringify({
+                ...run,
+                runId: run.id,
+                ...(run.traceReference?.traceId ? { traceId: run.traceReference.traceId } : {}),
+                traceRecordingStatus: run.traceReference?.recordingStatus ?? 'unavailable',
+            }, null, 2));
             return;
         }
-        const run = payload.run;
-        const badge = run.trustState === 'certified'
-            ? '✓ Certified'
-            : run.trustState === 'grounded'
-                ? '✓ Verified (grounded)'
-                : run.trustState === 'review_required'
-                    ? '! AI-generated · review required'
-                    : run.trustState === 'blocked'
-                        ? '✕ Blocked'
-                        : '· Reply';
-        console.log(`${badge}\n\n${(run.answer ?? run.summary ?? '').trim()}`);
-        console.log(`\nThread: ${threadId}`);
+        printCanonicalCliAskRun(run, threadId);
     }
     finally {
         await close();
     }
 }
+/**
+ * `dql agent ask --thread <id>` — POST the question to the runtime's
+ * `/api/agent-runs` with the threadId in the body. The server injects the
+ * thread's prior turns into the conversation context and records the completed
+ * run as the next turn, so follow-ups resolve "those"/"that product" correctly
+ * across CLI invocations (and across the notebook UI, which shares the store).
+ */
+async function runThreadAsk(question, threadId, flags) {
+    return runCanonicalCliAsk(question, threadId, flags);
+}
 /** `dql agent threads` — list server-persisted conversation threads. */
 async function runThreads(flags) {
     const projectRoot = findProjectRoot(process.cwd());
@@ -757,6 +1114,7 @@ async function runEval(rest, flags) {
                         && Boolean(runtimeRun.answer?.trim()),
                     meaningResolved: Boolean(runtimeRun.routeDecision?.meaningResolution),
                 } : {}),
+                ...(runtimeProjection?.observability ? { observability: runtimeProjection.observability } : {}),
                 intent: runtimeRun?.routeDecision?.category ?? result.contextPack?.routeDecision.intent,
                 reviewStatus: result.reviewStatus,
                 contextObjects: runtimeProjection?.retrievalCandidateCount ?? result.contextPack?.objects.length,
@@ -947,6 +1305,9 @@ function evaluateCase(testCase, result, runtime) {
     if (expected.terminalOutcomeKind && runtime?.terminalOutcome?.kind !== expected.terminalOutcomeKind) {
         failures.push(`terminal outcome expected ${expected.terminalOutcomeKind}, got ${runtime?.terminalOutcome?.kind ?? 'none'}`);
     }
+    if (expected.traceRecordingStatus && runtime?.observability?.recordingStatus !== expected.traceRecordingStatus) {
+        failures.push(`trace recording status expected ${expected.traceRecordingStatus}, got ${runtime?.observability?.recordingStatus ?? 'unavailable'}`);
+    }
     for (const token of stringList(expected.sqlContains)) {
         if (!result.proposedSql?.toLowerCase().includes(token.toLowerCase()))
             failures.push(`SQL did not contain "${token}"`);
@@ -1338,6 +1699,22 @@ function buildEvalTrace(input) {
                 promoteCommand: result.promoteCommand,
             },
         },
+        {
+            stage: 'observability',
+            status: runtime?.observability?.recordingStatus === 'complete'
+                ? 'passed'
+                : runtime?.observability ? 'info' : 'not_run',
+            message: runtime?.observability
+                ? `Local Ask trace recording ${runtime.observability.recordingStatus}.`
+                : 'No runtime trace receipt was attached to this evaluation run.',
+            payload: runtime?.observability
+                ? {
+                    recordingStatus: runtime.observability.recordingStatus,
+                    storeSchemaVersion: runtime.observability.storeSchemaVersion,
+                    ...(runtime.observability.traceFingerprint ? { traceFingerprint: runtime.observability.traceFingerprint } : {}),
+                }
+                : undefined,
+        },
         {
             stage: 'scoring',
             status: evaluation.failures.length === 0 ? 'passed' : 'failed',