@kaelio/ktx 0.8.0 → 0.10.0

package/dist/context/sql-analysis/http-sql-analysis-port.js

@@ -59,6 +59,13 @@ function optionalString(raw, field) {
     }
     throw new Error(`sql analysis response has invalid optional string field ${field}`);
 }
+function optionalNullableStringField(raw, field) {
+    const value = raw[field];
+    if (value === null || value === undefined || typeof value === 'string') {
+        return value ?? null;
+    }
+    throw new Error(`sql analysis response has invalid optional nullable string field ${field}`);
+}
 function requiredStringArray(raw, field) {
     const value = raw[field];
     if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
@@ -136,10 +143,32 @@ function mapColumnsByClause(raw) {
     }
     return result;
 }
+function requiredTableRef(raw, field) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error(`sql analysis response contains invalid table ref in ${field}`);
+    }
+    const record = raw;
+    const name = record.name;
+    if (typeof name !== 'string' || name.length === 0) {
+        throw new Error(`sql analysis response table ref in ${field} is missing name`);
+    }
+    return {
+        catalog: optionalNullableStringField(record, 'catalog'),
+        db: optionalNullableStringField(record, 'db'),
+        name,
+    };
+}
+function requiredTableRefArray(raw, field) {
+    const value = raw[field];
+    if (!Array.isArray(value)) {
+        throw new Error(`sql analysis response is missing table-ref[] field ${field}`);
+    }
+    return value.map((item, index) => requiredTableRef(item, `${field}.${index}`));
+}
 function mapBatchResult(raw) {
     const error = optionalString(raw, 'error');
     return {
-        tablesTouched: requiredStringArray(raw, 'tables_touched'),
+        tablesTouched: requiredTableRefArray(raw, 'tables_touched'),
         columnsByClause: mapColumnsByClause(raw),
         ...(error !== undefined ? { error } : {}),
     };
@@ -170,10 +199,11 @@ export function createHttpSqlAnalysisPort(options) {
             });
             return mapResult(raw);
         },
-        async analyzeBatch(items, dialect) {
+        async analyzeBatch(items, dialect, options) {
             const raw = await requestJson('/sql/analyze-batch', {
                 dialect,
                 items,
+                ...(options?.catalog ? { catalog: options.catalog } : {}),
             });
             return mapBatchResponse(raw);
         },

package/dist/context/sql-analysis/ports.d.ts

@@ -1,3 +1,4 @@
+import type { KtxTableRef } from '../scan/types.js';
 export type SqlAnalysisDialect = 'bigquery' | 'snowflake' | 'postgres' | 'redshift' | 'mysql' | 'sqlite' | 'tsql' | 'clickhouse' | (string & {});
 export type SqlAnalysisLiteralSlotType = 'string' | 'number' | 'timestamp' | 'date' | 'boolean' | 'null' | 'unknown';
 export interface SqlAnalysisLiteralSlot {
@@ -17,8 +18,17 @@ export interface SqlAnalysisBatchItem {
     id: string;
     sql: string;
 }
+interface SqlAnalysisCatalogTable extends KtxTableRef {
+    columns?: string[];
+}
+interface SqlAnalysisCatalog {
+    tables: SqlAnalysisCatalogTable[];
+}
+export interface SqlAnalysisBatchOptions {
+    catalog?: SqlAnalysisCatalog;
+}
 export interface SqlAnalysisBatchResult {
-    tablesTouched: string[];
+    tablesTouched: KtxTableRef[];
     columnsByClause: Partial<Record<SqlAnalysisClause, string[]>>;
     error?: string | null;
 }
@@ -28,7 +38,7 @@ export interface SqlReadOnlyValidationResult {
 }
 export interface SqlAnalysisPort {
     analyzeForFingerprint(sql: string, dialect: SqlAnalysisDialect): Promise<SqlAnalysisFingerprintResult>;
-    analyzeBatch(items: SqlAnalysisBatchItem[], dialect: SqlAnalysisDialect): Promise<Map<string, SqlAnalysisBatchResult>>;
+    analyzeBatch(items: SqlAnalysisBatchItem[], dialect: SqlAnalysisDialect, options?: SqlAnalysisBatchOptions): Promise<Map<string, SqlAnalysisBatchResult>>;
     validateReadOnly(sql: string, dialect: SqlAnalysisDialect): Promise<SqlReadOnlyValidationResult>;
 }
 export {};

package/dist/context/tools/context-candidate-mark.tool.d.ts

@@ -7,9 +7,9 @@ declare const contextCandidateMarkInputSchema: z.ZodObject<{
     status: z.ZodEnum<{
         conflict: "conflict";
         merged: "merged";
+        rejected: "rejected";
         pending: "pending";
         promoted: "promoted";
-        rejected: "rejected";
     }>;
     rejectionReason: z.ZodDefault<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
@@ -30,9 +30,9 @@ export declare class ContextCandidateMarkTool extends BaseTool<typeof contextCan
         status: z.ZodEnum<{
             conflict: "conflict";
             merged: "merged";
+            rejected: "rejected";
             pending: "pending";
             promoted: "promoted";
-            rejected: "rejected";
         }>;
         rejectionReason: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>;

package/dist/context-build-view.d.ts

@@ -2,6 +2,7 @@ import type { KtxCliIo } from './index.js';
 import type { KtxManagedPythonInstallPolicy } from './managed-python-command.js';
 import type { KtxPublicIngestArgs, KtxPublicIngestPlanTarget, KtxPublicIngestProject } from './public-ingest.js';
 import { executePublicIngestTarget } from './public-ingest.js';
+import { fetchGitHubStarCount as defaultFetchGitHubStarCount } from './star-prompt/star-count.js';
 type PhaseKey = 'database-schema' | 'query-history' | 'source-ingest';
 type PhaseStatus = 'queued' | 'running' | 'done' | 'failed' | 'skipped';
 interface PhaseState {
@@ -32,6 +33,7 @@ export interface ContextBuildViewState {
     frame: number;
     startedAt: number | null;
     totalElapsedMs: number;
+    starCount: number | null;
 }
 export interface ContextBuildArgs {
     projectDir: string;
@@ -73,6 +75,8 @@ interface CompletedItemName {
 interface ContextBuildRenderOptions {
     styled?: boolean;
     showHint?: boolean;
+    showStarPrompt?: boolean;
+    columns?: number;
     hintText?: string;
     projectDir?: string;
     title?: string;
@@ -89,6 +93,14 @@ export interface ContextBuildDeps {
     now?: () => number;
     onSourceProgress?: (sources: ContextBuildSourceProgressUpdate[]) => void;
     sourceProgressThrottleMs?: number;
+    fetchStarCount?: typeof defaultFetchGitHubStarCount;
+    starPromptEnv?: StarPromptEnv;
+    starPromptHomeDir?: string;
+}
+interface StarPromptEnv extends NodeJS.ProcessEnv {
+    CI?: string;
+    DO_NOT_TRACK?: string;
+    KTX_NO_STAR?: string;
 }
 export declare function renderContextBuildView(state: ContextBuildViewState, options?: ContextBuildRenderOptions): string;
 /** @internal */
@@ -101,6 +113,7 @@ export declare function parseIngestSummary(output: string): string | null;
 export declare function viewStateFromSourceProgress(sources: ContextBuildSourceProgressUpdate[], now: number, startedAtMs?: number): ContextBuildViewState;
 export declare function createRepainter(io: KtxCliIo): {
     paint(content: string): void;
+    columns(): number;
 };
 export declare function initViewState(targets: KtxPublicIngestPlanTarget[]): ContextBuildViewState;
 export declare function runContextBuild(project: KtxPublicIngestProject, args: ContextBuildArgs, io: KtxCliIo, deps?: ContextBuildDeps): Promise<ContextBuildResult>;

package/dist/context-build-view.js

@@ -1,7 +1,10 @@
-import { publicDatabaseIngestMessage, publicQueryHistoryMessage } from './public-ingest-copy.js';
-import { buildPublicIngestPlan, executePublicIngestTarget } from './public-ingest.js';
+import { buildPublicIngestPlan, executePublicIngestTarget, publicProgressMessage } from './public-ingest.js';
+import { createAggregateProgressPort } from './progress-port-adapter.js';
 import { formatDuration } from './demo-metrics.js';
 import { profileMark } from './startup-profile.js';
+import { isFreshStarCountCache, readStarCountCache, writeStarCountCache, } from './star-prompt/cache.js';
+import { fetchGitHubStarCount as defaultFetchGitHubStarCount } from './star-prompt/star-count.js';
+import { renderStarPromptLine } from './star-prompt/star-line.js';
 profileMark('module:context-build-view');
 const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
 const ESC = String.fromCharCode(0x1b);
@@ -286,6 +289,13 @@ export function renderContextBuildView(state, options = {}) {
         lines.push(styled ? green(summary) : summary);
         lines.push('');
     }
+    if (options.showStarPrompt && hasActive) {
+        const starPrompt = renderStarPromptLine({
+            count: state.starCount,
+            columns: options.columns ?? 80,
+        });
+        lines.push(styled ? dim(starPrompt) : starPrompt);
+    }
     if (options.showHint && hasActive) {
         const hintContent = options.hintText ?? 'Ctrl+C to stop';
         const hint = `  ${hintContent}`;
@@ -423,6 +433,7 @@ export function viewStateFromSourceProgress(sources, now, startedAtMs) {
         frame: 0,
         startedAt: startedAtMs ?? null,
         totalElapsedMs: startedAtMs ? now - startedAtMs : 0,
+        starCount: null,
     };
 }
 // --- Repaint ---
@@ -465,6 +476,9 @@ export function createRepainter(io) {
             hasPainted = true;
             lastCursorUpRows = cursorUpRowsAfterWrite(content);
         },
+        columns() {
+            return terminalColumns();
+        },
     };
 }
 // --- Orchestration ---
@@ -616,39 +630,41 @@ export function initViewState(targets) {
         frame: 0,
         startedAt: null,
         totalElapsedMs: 0,
+        starCount: null,
     };
 }
-function publicProgressMessage(message, target) {
-    let current = message;
-    if (target.operation === 'database-ingest') {
-        current = publicDatabaseIngestMessage(current);
-    }
-    if (target.steps.includes('query-history')) {
-        current = publicQueryHistoryMessage(current, target.connectionId);
-    }
-    return current;
-}
 function formatProgressDetail(update, target) {
     const percent = Math.max(0, Math.min(100, Math.round(update.percent)));
     return `[${percent}%] ${publicProgressMessage(update.message, target)}`;
 }
-function createContextBuildProgressPort(onProgress, state = { progress: 0 }, start = 0, weight = 1) {
-    return {
-        async update(value, message, options) {
-            const absoluteValue = start + Math.max(0, Math.min(1, value)) * weight;
-            state.progress = Math.max(state.progress, Math.min(1, absoluteValue));
-            if (!message)
-                return;
-            onProgress({
-                percent: Math.max(0, Math.min(100, Math.round(state.progress * 100))),
-                message,
-                ...(options?.transient !== undefined ? { transient: options.transient } : {}),
-            });
-        },
-        startPhase(phaseWeight) {
-            return createContextBuildProgressPort(onProgress, state, state.progress, weight * phaseWeight);
-        },
-    };
+const STAR_COUNT_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+function envFlag(value) {
+    return value !== undefined && value !== '' && value !== '0' && value !== 'false';
+}
+function shouldSuppressStarPrompt(env) {
+    return envFlag(env.CI) || envFlag(env.DO_NOT_TRACK) || envFlag(env.KTX_NO_STAR);
+}
+function startStarPromptCountRefresh(input) {
+    const cached = readStarCountCache({ homeDir: input.homeDir });
+    if (cached) {
+        input.state.starCount = cached.count;
+    }
+    if (isFreshStarCountCache(cached, new Date(input.now()), STAR_COUNT_CACHE_TTL_MS)) {
+        return;
+    }
+    void input.fetchStarCount()
+        .then((count) => {
+        if (typeof count !== 'number' || !Number.isFinite(count)) {
+            return;
+        }
+        input.state.starCount = count;
+        input.paint();
+        void writeStarCountCache({
+            count,
+            fetchedAt: new Date(input.now()).toISOString(),
+        }, { homeDir: input.homeDir });
+    })
+        .catch(() => undefined);
 }
 export async function runContextBuild(project, args, io, deps = {}) {
     const plan = buildPublicIngestPlan(project, {
@@ -664,13 +680,28 @@ export async function runContextBuild(project, args, io, deps = {}) {
     const nowFn = deps.now ?? (() => Date.now());
     state.startedAt = nowFn();
     const repainter = isTTY ? createRepainter(io) : null;
+    const starPromptEnabled = repainter !== null && !shouldSuppressStarPrompt(deps.starPromptEnv ?? process.env);
     const viewOpts = {
         styled: true,
         projectDir: args.projectDir,
         notices: plan.notices ?? [],
         warnings: plan.warnings,
     };
-    const paint = (hint) => repainter?.paint(renderContextBuildView(state, { ...viewOpts, showHint: hint }));
+    const paint = (hint) => repainter?.paint(renderContextBuildView(state, {
+        ...viewOpts,
+        showHint: hint,
+        showStarPrompt: starPromptEnabled && hint,
+        columns: repainter.columns(),
+    }));
+    if (starPromptEnabled) {
+        startStarPromptCountRefresh({
+            fetchStarCount: deps.fetchStarCount ?? defaultFetchGitHubStarCount,
+            homeDir: deps.starPromptHomeDir,
+            now: nowFn,
+            paint: () => paint(true),
+            state,
+        });
+    }
     paint(true);
     let spinnerInterval = null;
     if (repainter) {
@@ -802,7 +833,7 @@ export async function runContextBuild(project, args, io, deps = {}) {
                 hasPendingProgressPublish = !publishSourceProgress(false);
             };
             const progressDeps = {
-                scanProgress: createContextBuildProgressPort(updateSchemaPhase),
+                scanProgress: createAggregateProgressPort(updateSchemaPhase),
                 ingestProgress: updateIngestPhase,
                 runtimeIo: io,
                 onPhaseStart,
@@ -811,7 +842,7 @@ export async function runContextBuild(project, args, io, deps = {}) {
             let result = null;
             let thrownError = null;
             try {
-                result = await execTarget(targetState.target, runArgs, capture.io, progressDeps);
+                result = await execTarget(targetState.target, runArgs, capture.io, progressDeps, project);
             }
             catch (error) {
                 thrownError = error;

package/dist/demo-metrics.d.ts

@@ -8,8 +8,6 @@ interface DemoMetricsTuning {
 interface DemoMetricsSnapshot {
     elapsedMs: number;
     etaMs: number | null;
-    agentSteps: number;
-    agentStepBudget: number;
     toolCalls: number;
     workUnitsStarted: number;
     workUnitsFinished: number;

package/dist/demo-metrics.js

@@ -5,13 +5,6 @@ const DEFAULT_OUTPUT_PRICE_PER_MTOK_USD = 15;
 function eventsOf(events, type) {
     return events.filter((event) => event.type === type);
 }
-function maxAgentStep(events) {
-    const steps = eventsOf(events, 'work_unit_step');
-    const started = eventsOf(events, 'work_unit_started');
-    const stepIndex = steps.reduce((max, event) => Math.max(max, event.stepIndex), 0);
-    const stepBudget = Math.max(0, ...steps.map((event) => event.stepBudget), ...started.map((event) => event.stepBudget));
-    return { step: stepIndex, budget: stepBudget };
-}
 function totalToolCalls(input) {
     return input.details.transcripts.reduce((total, transcript) => total + transcript.toolCallCount, 0);
 }
@@ -49,11 +42,10 @@ export function buildDemoMetrics(input, options = {}) {
     const outputPrice = tuning.outputPricePerMTokUsd ?? DEFAULT_OUTPUT_PRICE_PER_MTOK_USD;
     const nowMs = (options.now ?? Date.now)();
     const elapsedMs = elapsedMsFromEvents(input.events, nowMs);
-    const { step, budget } = maxAgentStep(input.events);
     const toolCalls = totalToolCalls(input);
     const progress = workUnitProgress(input);
     const finishedCount = eventsOf(input.events, 'work_unit_finished').length;
-    const stepDriver = Math.max(step, toolCalls, finishedCount * 4);
+    const stepDriver = Math.max(toolCalls, finishedCount * 4);
     const inputTokens = stepDriver * inputTokensPerStep;
     const outputTokens = stepDriver * outputTokensPerStep;
     const totalTokens = inputTokens + outputTokens;
@@ -63,8 +55,6 @@ export function buildDemoMetrics(input, options = {}) {
     return {
         elapsedMs,
         etaMs: estimateEtaMs(elapsedMs, progress.finished, progress.total, input.status),
-        agentSteps: step,
-        agentStepBudget: budget,
         toolCalls,
         workUnitsStarted: progress.started,
         workUnitsFinished: progress.finished,

package/dist/ingest.d.ts

@@ -58,6 +58,7 @@ export interface KtxIngestDeps {
     readReportFile?: typeof readIngestReportSnapshotFile;
     renderStoredMemoryFlow?: typeof renderMemoryFlowTui;
     startLiveMemoryFlow?: typeof startLiveMemoryFlowTui;
+    abortSignal?: AbortSignal;
     env?: NodeJS.ProcessEnv;
     localIngestOptions?: Pick<RunLocalIngestOptions, 'agentRunner' | 'llmRuntime' | 'memoryModel' | 'semanticLayerCompute' | 'queryExecutor' | 'logger' | 'pullConfigOptions'>;
     progress?: (update: KtxIngestProgressUpdate) => void;

package/dist/ingest.js

@@ -17,6 +17,22 @@ import { renderMemoryFlowTui, startLiveMemoryFlowTui, } from './memory-flow-tui.
 import { resolveVizFallback, warnVizFallbackOnce } from './viz-fallback.js';
 import { profileMark } from './startup-profile.js';
 profileMark('module:ingest');
+function createCliAbortSignal() {
+    const controller = new AbortController();
+    let interrupted = false;
+    const onSigint = () => {
+        if (interrupted) {
+            process.exit(130);
+        }
+        interrupted = true;
+        controller.abort(new DOMException('Aborted', 'AbortError'));
+    };
+    process.on('SIGINT', onSigint);
+    return {
+        signal: controller.signal,
+        dispose: () => process.off('SIGINT', onSigint),
+    };
+}
 const REPORT_SOURCE_LABELS = new Map([
     ['live-database', 'Database schema'],
     ['historic-sql', 'Query history'],
@@ -249,6 +265,12 @@ function plainIngestEventProgress(event, snapshot, eventIndex) {
                 message: event.message,
                 ...(event.transient !== undefined ? { transient: event.transient } : {}),
             };
+        case 'rate_limit_wait':
+            return {
+                percent: 50,
+                message: `Rate-limited (${event.provider}${event.rateLimitType ? ` ${event.rateLimitType}` : ''}); resuming in ${Math.ceil(event.remainingMs / 1_000)}s`,
+                transient: true,
+            };
         case 'work_unit_started': {
             const total = plannedWorkUnitCountThrough(snapshot, eventIndex);
             const ordinal = workUnitOrdinalThrough(snapshot, eventIndex, event.unitKey);
@@ -259,9 +281,8 @@ function plainIngestEventProgress(event, snapshot, eventIndex) {
             const total = plannedWorkUnitCountThrough(snapshot, eventIndex);
             const completed = completedWorkUnitCountThrough(snapshot, eventIndex);
             const active = activeWorkUnitCountThrough(snapshot, eventIndex);
-            const stepFraction = event.stepBudget > 0 ? Math.min(1, event.stepIndex / event.stepBudget) : 0;
-            const percent = total > 0 ? 55 + Math.ceil(((completed + stepFraction) / total) * 25) : 55;
-            const latest = `${event.unitKey} step ${event.stepIndex}/${event.stepBudget}`;
+            const percent = total > 0 ? 55 + Math.ceil((completed / total) * 25) : 55;
+            const latest = `${event.unitKey} · ${pluralize(event.toolCalls, 'action')}`;
             return {
                 percent,
                 message: `Processing tasks: ${completed}/${total} complete, ${active} active; latest ${latest}`,
@@ -546,6 +567,8 @@ export async function runKtxIngest(args, io = process, deps = {}) {
                         : io, deps.progress);
                 plainProgress?.start();
                 structuredProgress?.start();
+                const cliAbort = deps.abortSignal ? null : createCliAbortSignal();
+                const abortSignal = deps.abortSignal ?? cliAbort?.signal;
                 let result;
                 try {
                     result = await executeMetabaseFanout({
@@ -559,6 +582,7 @@ export async function runKtxIngest(args, io = process, deps = {}) {
                         embeddingProvider,
                         ...(memoryFlow ? { memoryFlow } : {}),
                         ...(progress ? { progress } : {}),
+                        ...(abortSignal ? { abortSignal } : {}),
                     });
                     plainProgress?.flush();
                     if (args.outputMode === 'json') {
@@ -570,6 +594,7 @@ export async function runKtxIngest(args, io = process, deps = {}) {
                 }
                 finally {
                     plainProgress?.flush();
+                    cliAbort?.dispose();
                 }
                 return result.status === 'all_failed' ? 1 : 0;
             }
@@ -612,6 +637,8 @@ export async function runKtxIngest(args, io = process, deps = {}) {
                 : undefined;
             plainProgress?.start();
             structuredProgress?.start();
+            const cliAbort = deps.abortSignal ? null : createCliAbortSignal();
+            const abortSignal = deps.abortSignal ?? cliAbort?.signal;
             try {
                 const result = await executeLocalIngest({
                     project: ingestProject,
@@ -627,6 +654,7 @@ export async function runKtxIngest(args, io = process, deps = {}) {
                     embeddingProvider,
                     ...(args.debugLlmRequestFile ? { llmDebugRequestFile: args.debugLlmRequestFile } : {}),
                     ...(memoryFlow ? { memoryFlow } : {}),
+                    ...(abortSignal ? { abortSignal } : {}),
                 });
                 if (shouldUseLiveViz && memoryFlow) {
                     latestMemoryFlowSnapshot = finalRunMemoryFlowInput(memoryFlow.snapshot(), result.report);
@@ -646,6 +674,7 @@ export async function runKtxIngest(args, io = process, deps = {}) {
             finally {
                 plainProgress?.flush();
                 liveTui?.close();
+                cliAbort?.dispose();
             }
         }
         if (args.reportFile) {

package/dist/io/buffered-command-io.d.ts

@@ -0,0 +1,11 @@
+import type { KtxCliIo } from '../cli-runtime.js';
+export interface BufferedCommandIo extends KtxCliIo {
+    stdoutText(): string;
+    stderrText(): string;
+}
+/**
+ * Captures stdout/stderr from a command (e.g. `runKtxConnection`) into buffers
+ * instead of the terminal. Callers decide whether to flush the captured text to
+ * the user or discard it.
+ */
+export declare function createBufferedCommandIo(): BufferedCommandIo;

package/dist/io/buffered-command-io.js

@@ -0,0 +1,28 @@
+/**
+ * Captures stdout/stderr from a command (e.g. `runKtxConnection`) into buffers
+ * instead of the terminal. Callers decide whether to flush the captured text to
+ * the user or discard it.
+ */
+export function createBufferedCommandIo() {
+    let stdout = '';
+    let stderr = '';
+    return {
+        stdout: {
+            isTTY: false,
+            write(chunk) {
+                stdout += chunk;
+            },
+        },
+        stderr: {
+            write(chunk) {
+                stderr += chunk;
+            },
+        },
+        stdoutText() {
+            return stdout;
+        },
+        stderrText() {
+            return stderr;
+        },
+    };
+}

package/dist/io/symbols.d.ts

@@ -1,6 +1,8 @@
 export declare const SYMBOLS: {
     readonly middot: "-" | "·";
     readonly emDash: "--" | "—";
+    readonly star: "*" | "★";
+    readonly rightArrow: "→" | "->";
 };
 export declare function dim(text: string): string;
 export declare function bold(text: string): string;

package/dist/io/symbols.js

@@ -12,6 +12,8 @@ const unicode = detectUnicodeSupport();
 export const SYMBOLS = {
     middot: unicode ? '·' : '-',
     emDash: unicode ? '—' : '--',
+    star: unicode ? '★' : '*',
+    rightArrow: unicode ? '→' : '->',
 };
 export function dim(text) {
     return styleText('dim', text);

package/dist/llm/types.d.ts

@@ -1,7 +1,7 @@
 import type { LanguageModel, TelemetrySettings, ToolCallRepairFunction, ToolSet } from 'ai';
 export declare const KTX_MODEL_ROLES: readonly ["default", "triage", "candidateExtraction", "curator", "reconcile", "repair"];
 export type KtxModelRole = (typeof KTX_MODEL_ROLES)[number];
-type KtxLlmBackend = 'anthropic' | 'vertex' | 'gateway' | 'claude-code';
+type KtxLlmBackend = 'anthropic' | 'vertex' | 'gateway' | 'claude-code' | 'codex';
 export type KtxPromptCacheTtl = '5m' | '1h';
 type KtxJsonValue = null | string | number | boolean | KtxJsonValue[] | {
     [key: string]: KtxJsonValue | undefined;

package/dist/local-adapters.d.ts

@@ -1,14 +1,22 @@
 import { type DefaultLocalIngestAdaptersOptions } from './context/ingest/local-adapters.js';
+import type { HistoricSqlDialect, HistoricSqlReader } from './context/ingest/adapters/historic-sql/types.js';
 import type { SourceAdapter } from './context/ingest/types.js';
 import type { KtxLocalProject } from './context/project/project.js';
 import type { SqlAnalysisPort } from './context/sql-analysis/ports.js';
-import { type ManagedPythonCoreDaemonOptions } from './managed-python-http.js';
+import { type ManagedPythonDaemonHttpOptions } from './managed-python-http.js';
 import type { KtxOperationalLogger } from './io/logger.js';
 export interface KtxCliLocalIngestAdaptersOptions extends DefaultLocalIngestAdaptersOptions {
     historicSqlConnectionId?: string;
     sqlAnalysis?: SqlAnalysisPort;
     sqlAnalysisUrl?: string;
-    managedDaemon?: ManagedPythonCoreDaemonOptions;
+    managedDaemon?: ManagedPythonDaemonHttpOptions;
     logger?: KtxOperationalLogger;
 }
+export interface KtxCliHistoricSqlRuntime {
+    dialect: HistoricSqlDialect;
+    sqlAnalysis: SqlAnalysisPort;
+    reader: HistoricSqlReader;
+    queryClient: unknown;
+}
+export declare function createKtxCliHistoricSqlRuntime(project: KtxLocalProject, connectionId: string, options?: KtxCliLocalIngestAdaptersOptions): KtxCliHistoricSqlRuntime | undefined;
 export declare function createKtxCliLocalIngestAdapters(project: KtxLocalProject, options?: KtxCliLocalIngestAdaptersOptions): SourceAdapter[];

package/dist/local-adapters.js

@@ -12,7 +12,7 @@ import { isKtxSqliteConnectionConfig } from './connectors/sqlite/connector.js';
 import { createSqlServerLiveDatabaseIntrospection } from './connectors/sqlserver/live-database-introspection.js';
 import { isKtxSqlServerConnectionConfig } from './connectors/sqlserver/connector.js';
 import { BigQueryHistoricSqlQueryHistoryReader } from './context/ingest/adapters/historic-sql/bigquery-query-history-reader.js';
-import { queryHistoryDialectForConnection } from './context/ingest/adapters/historic-sql/connection-dialect.js';
+import { historicSqlDialectForConnectionDriver } from './context/ingest/adapters/historic-sql/connection-dialect.js';
 import { createDaemonLiveDatabaseIntrospection } from './context/ingest/adapters/live-database/daemon-introspection.js';
 import { createDefaultLocalIngestAdapters } from './context/ingest/local-adapters.js';
 import { LiveDatabaseSourceAdapter } from './context/ingest/adapters/live-database/live-database.adapter.js';
@@ -224,7 +224,12 @@ function historicSqlOptionsForLocalRun(project, options) {
         return undefined;
     }
     const connection = project.config.connections[connectionId];
-    const dialect = queryHistoryDialectForConnection(connection);
+    // historicSqlConnectionId is only set when query history was explicitly
+    // requested for this run (e.g. `--query-history`), so resolve the dialect from
+    // driver capability rather than the persisted context.queryHistory.enabled
+    // flag — otherwise the adapter is missing and findAdapter('historic-sql')
+    // throws even though the run asked for it.
+    const dialect = historicSqlDialectForConnectionDriver(connection);
     if (!dialect) {
         return undefined;
     }
@@ -234,6 +239,7 @@ function historicSqlOptionsForLocalRun(project, options) {
     if (dialect === 'postgres') {
         return {
             ...base,
+            dialect,
             reader: new PostgresPgssReader(),
             queryClient: createEphemeralPostgresHistoricSqlClient(project, connectionId),
         };
@@ -245,6 +251,7 @@ function historicSqlOptionsForLocalRun(project, options) {
         }
         return {
             ...base,
+            dialect,
             reader: new BigQueryHistoricSqlQueryHistoryReader({
                 projectId: bigQueryProjectId(connection, process.env),
                 region: bigQueryRegion(connection),
@@ -254,6 +261,7 @@ function historicSqlOptionsForLocalRun(project, options) {
     }
     return {
         ...base,
+        dialect,
         reader: new SnowflakeHistoricSqlQueryHistoryReader(),
         queryClient: {
             async executeQuery(query) {
@@ -264,8 +272,16 @@ function historicSqlOptionsForLocalRun(project, options) {
         },
     };
 }
+export function createKtxCliHistoricSqlRuntime(project, connectionId, options = {}) {
+    return historicSqlOptionsForLocalRun(project, {
+        ...options,
+        historicSqlConnectionId: connectionId,
+    });
+}
 export function createKtxCliLocalIngestAdapters(project, options = {}) {
-    const historicSql = historicSqlOptionsForLocalRun(project, options);
+    const historicSql = options.historicSqlConnectionId
+        ? createKtxCliHistoricSqlRuntime(project, options.historicSqlConnectionId, options)
+        : undefined;
     const base = createDefaultLocalIngestAdapters(project, {
         ...options,
         databaseIntrospection: ktxCliDaemonDatabaseIntrospectionOptions(options),