@kaelio/ktx 0.7.0 → 0.9.0

package/dist/sl.d.ts

@@ -23,10 +23,15 @@ export type KtxSlArgs = {
     output?: string;
     json?: boolean;
     cliVersion: string;
+} | {
+    command: 'read';
+    projectDir: string;
+    connectionId?: string;
+    sourceName: string;
 } | {
     command: 'validate';
     projectDir: string;
-    connectionId: string;
+    connectionId?: string;
     sourceName: string;
 } | {
     command: 'query';

package/dist/sl.js

@@ -3,7 +3,7 @@ import { createDefaultLocalQueryExecutor } from './context/connections/local-que
 import { KtxIngestEmbeddingPortAdapter } from './context/llm/embedding-port.js';
 import { loadKtxProject } from './context/project/project.js';
 import { compileLocalSlQuery } from './context/sl/local-query.js';
-import { listLocalSlSources, readLocalSlSource, searchLocalSlSources as defaultSearchLocalSlSources, validateLocalSlSource } from './context/sl/local-sl.js';
+import { listLocalSlSources, resolveLocalSlSource, searchLocalSlSources as defaultSearchLocalSlSources, validateLocalSlSource, } from './context/sl/local-sl.js';
 import { resolveProjectEmbeddingProvider, } from './embedding-resolution.js';
 import { createManagedPythonSemanticLayerComputePort, } from './managed-python-command.js';
 import { profileMark } from './startup-profile.js';
@@ -85,6 +85,9 @@ async function readSlQueryFile(path) {
     }
     return parsed;
 }
+function ambiguousSourceMessage(sourceName, connectionIds) {
+    return `Source '${sourceName}' exists in multiple connections: ${connectionIds.join(', ')}. Re-run with --connection-id <id>.`;
+}
 export async function runKtxSl(args, io = process, deps = {}) {
     const startedAt = performance.now();
     let queryForTelemetry;
@@ -132,17 +135,38 @@ export async function runKtxSl(args, io = process, deps = {}) {
             });
             return 0;
         }
+        if (args.command === 'read') {
+            const resolved = await resolveLocalSlSource(project, {
+                connectionId: args.connectionId,
+                sourceName: args.sourceName,
+            });
+            if (resolved.kind === 'not-found') {
+                throw new Error(args.connectionId !== undefined
+                    ? `No semantic-layer source '${args.sourceName}' for connection '${args.connectionId}'`
+                    : `No semantic-layer source '${args.sourceName}'`);
+            }
+            if (resolved.kind === 'ambiguous') {
+                throw new Error(ambiguousSourceMessage(args.sourceName, resolved.connectionIds));
+            }
+            io.stdout.write(resolved.source.yaml);
+            return 0;
+        }
         if (args.command === 'validate') {
-            const source = await readLocalSlSource(project, {
+            const resolved = await resolveLocalSlSource(project, {
                 connectionId: args.connectionId,
                 sourceName: args.sourceName,
             });
-            if (!source) {
-                throw new Error(`Semantic-layer source "${args.connectionId}/${args.sourceName}" was not found`);
+            if (resolved.kind === 'not-found') {
+                throw new Error(args.connectionId !== undefined
+                    ? `Semantic-layer source "${args.connectionId}/${args.sourceName}" was not found`
+                    : `Semantic-layer source "${args.sourceName}" was not found`);
             }
-            const result = await validateLocalSlSource(source.yaml, {
+            if (resolved.kind === 'ambiguous') {
+                throw new Error(ambiguousSourceMessage(args.sourceName, resolved.connectionIds));
+            }
+            const result = await validateLocalSlSource(resolved.source.yaml, {
                 project,
-                connectionId: args.connectionId,
+                connectionId: resolved.source.connectionId,
                 sourceName: args.sourceName,
             });
             await emitTelemetryEvent({
@@ -150,7 +174,7 @@ export async function runKtxSl(args, io = process, deps = {}) {
                 projectDir: args.projectDir,
                 io,
                 fields: {
-                    sourceCount: source ? 1 : 0,
+                    sourceCount: 1,
                     modelCount: 0,
                     validationErrorCount: result.valid ? 0 : result.errors.length,
                     outcome: result.valid ? 'ok' : 'error',
@@ -163,7 +187,7 @@ export async function runKtxSl(args, io = process, deps = {}) {
                 }
                 return 1;
             }
-            io.stdout.write(`Valid semantic-layer source: ${args.connectionId}/${args.sourceName}\n`);
+            io.stdout.write(`Valid semantic-layer source: ${resolved.source.connectionId}/${args.sourceName}\n`);
             return 0;
         }
         if (args.command === 'query') {

package/dist/status-project.d.ts

@@ -62,6 +62,16 @@ type ClaudeCodeAuthProbe = (input: {
     ok: false;
     message: string;
 }>;
+type CodexAuthProbe = (input: {
+    projectDir: string;
+    model: string;
+}) => Promise<{
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+    fix: string;
+}>;
 interface LocalStatsIngestPerConnection {
     connectionId: string;
     adapter: string;
@@ -135,6 +145,7 @@ export interface BuildProjectStatusOptions {
     env?: NodeJS.ProcessEnv;
     queryHistoryReadinessProbe?: HistoricSqlReadinessProbe;
     claudeCodeAuthProbe?: ClaudeCodeAuthProbe;
+    codexAuthProbe?: CodexAuthProbe;
     configIssues?: KtxConfigIssue[];
     fast?: boolean;
     useSpinner?: boolean;

package/dist/status-project.js

@@ -1,6 +1,8 @@
 import { stat as statAsync, readdir as readdirAsync } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { runClaudeCodeAuthProbe } from './context/llm/claude-code-runtime.js';
+import { CODEX_ISOLATION_WARNING, CODEX_ISOLATION_WARNING_FIX, } from './context/llm/codex-isolation.js';
+import { runCodexAuthProbe } from './context/llm/codex-runtime.js';
 import { ktxLocalStateDbPath } from './context/project/local-state-db.js';
 import { isQueryHistoryEnabled, queryHistoryDialectForConnection, } from './context/ingest/adapters/historic-sql/connection-dialect.js';
 import { historicSqlProbeCatalogName, runHistoricSqlReadinessProbe, } from './context/ingest/historic-sql-probes.js';
@@ -49,6 +51,18 @@ async function buildLlmStatus(config, options) {
             fix: 'Run: ktx setup (choose an LLM provider)',
         };
     }
+    // The runtime (resolveModelSlots) hard-requires llm.models.default for every
+    // non-none backend; without it ingest/scan/memory throw. Report that here so
+    // status never marks a project ready that the runtime would refuse to run.
+    if (!model || model.trim().length === 0) {
+        return {
+            backend,
+            model,
+            status: 'fail',
+            detail: `llm.models.default is required for backend "${backend}"`,
+            fix: 'Set llm.models.default in ktx.yaml, then rerun `ktx status` (or rerun `ktx setup`).',
+        };
+    }
     if (backend === 'anthropic') {
         const ref = config.provider.anthropic?.api_key;
         const resolved = resolveRef(ref, env);
@@ -90,7 +104,7 @@ async function buildLlmStatus(config, options) {
         };
     }
     if (backend === 'claude-code') {
-        const modelName = model ?? 'sonnet';
+        const modelName = model;
         if (options.fast === true) {
             return {
                 backend,
@@ -117,6 +131,34 @@ async function buildLlmStatus(config, options) {
             fix: 'Authenticate Claude Code locally with the Claude Code CLI, then rerun `ktx status`.',
         };
     }
+    if (backend === 'codex') {
+        const modelName = model;
+        if (options.fast === true) {
+            return {
+                backend,
+                model: modelName,
+                status: 'skipped',
+                detail: 'auth probe skipped (--fast)',
+            };
+        }
+        const probe = options.codexAuthProbe ?? runCodexAuthProbe;
+        const auth = await withSpinner(options.useSpinner === true, 'Probing Codex authentication', () => probe({ projectDir: options.projectDir, model: modelName }));
+        if (auth.ok) {
+            return {
+                backend,
+                model: modelName,
+                status: 'ok',
+                detail: 'local Codex session authenticated',
+            };
+        }
+        return {
+            backend,
+            model: modelName,
+            status: 'fail',
+            detail: auth.message,
+            fix: auth.fix,
+        };
+    }
     return { backend, model, status: 'warn', detail: 'unknown LLM backend' };
 }
 function buildEmbeddingsStatus(config, env) {
@@ -378,6 +420,12 @@ function buildWarnings(config, connections, llm, embeddings) {
             fix: formatClaudeCodePromptCachingFix(),
         });
     }
+    if (llm.backend === 'codex') {
+        warnings.push({
+            message: CODEX_ISOLATION_WARNING,
+            fix: CODEX_ISOLATION_WARNING_FIX,
+        });
+    }
     return warnings;
 }
 function buildVerdict(llm, embeddings, connections, queryHistory, warnings) {
@@ -625,6 +673,7 @@ export async function buildProjectStatus(project, options = {}) {
         projectDir: project.projectDir,
         env,
         claudeCodeAuthProbe: options.claudeCodeAuthProbe,
+        codexAuthProbe: options.codexAuthProbe,
         fast: options.fast,
         useSpinner: options.useSpinner,
     });

package/dist/telemetry/command-hook.d.ts

@@ -12,6 +12,7 @@ export interface CompletedCommandSpan {
     durationMs: number;
     outcome: CommandOutcome;
     errorClass?: string;
+    errorDetail?: string;
     flagsPresent: Record<string, boolean>;
     hasProject: boolean;
     projectDir?: string;

package/dist/telemetry/command-hook.js

@@ -1,4 +1,4 @@
-import { scrubErrorClass } from './scrubber.js';
+import { formatErrorDetail, scrubErrorClass } from './scrubber.js';
 let activeCommandSpan;
 export function beginCommandSpan(input) {
     activeCommandSpan = input;
@@ -10,11 +10,13 @@ export function completeCommandSpan(input) {
         return undefined;
     }
     const errorClass = input.error ? scrubErrorClass(input.error) : undefined;
+    const errorDetail = input.error ? formatErrorDetail(input.error) : undefined;
     return {
         commandPath: span.commandPath,
         durationMs: Math.max(0, input.completedAt - span.startedAt),
         outcome: input.outcome,
         ...(errorClass ? { errorClass } : {}),
+        ...(errorDetail ? { errorDetail } : {}),
         flagsPresent: span.flagsPresent,
         hasProject: span.hasProject,
         projectDir: span.projectDir,

package/dist/telemetry/emitter.js

@@ -17,7 +17,7 @@ async function getPostHogClient(projectApiKey, host) {
         return null;
     }
     clientPromise ??= import('posthog-node')
-        .then(({ PostHog }) => new PostHog(projectApiKey, { host, flushAt: 1, flushInterval: 0 }))
+        .then(({ PostHog }) => new PostHog(projectApiKey, { host, flushAt: 1, flushInterval: 0, disableGeoip: false }))
         .catch(() => null);
     return await clientPromise;
 }

package/dist/telemetry/events.d.ts

@@ -44,6 +44,7 @@ export declare const telemetryEventSchemas: {
             aborted: "aborted";
         }>;
         errorClass: z.ZodOptional<z.ZodString>;
+        errorDetail: z.ZodOptional<z.ZodString>;
         flagsPresent: z.ZodRecord<z.ZodString, z.ZodBoolean>;
         hasProject: z.ZodBoolean;
         projectGroupAttached: z.ZodBoolean;
@@ -67,9 +68,8 @@ export declare const telemetryEventSchemas: {
             databases: "databases";
             context: "context";
             runtime: "runtime";
-            agents: "agents";
             secrets: "secrets";
-            "database-context-depth": "database-context-depth";
+            agents: "agents";
             "demo-tour": "demo-tour";
         }>;
         outcome: z.ZodEnum<{
@@ -78,6 +78,7 @@ export declare const telemetryEventSchemas: {
             abandoned: "abandoned";
         }>;
         durationMs: z.ZodNumber;
+        errorDetail: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
     readonly connection_added: z.ZodObject<{
         cliVersion: z.ZodString;
@@ -111,6 +112,7 @@ export declare const telemetryEventSchemas: {
             error: "error";
         }>;
         errorClass: z.ZodOptional<z.ZodString>;
+        errorDetail: z.ZodOptional<z.ZodString>;
         durationMs: z.ZodNumber;
         serverVersion: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
@@ -164,6 +166,7 @@ export declare const telemetryEventSchemas: {
             error: "error";
         }>;
         errorClass: z.ZodOptional<z.ZodString>;
+        errorDetail: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
     readonly scan_completed: z.ZodObject<{
         cliVersion: z.ZodString;
@@ -187,6 +190,7 @@ export declare const telemetryEventSchemas: {
             error: "error";
         }>;
         errorClass: z.ZodOptional<z.ZodString>;
+        errorDetail: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
     readonly sl_validate_completed: z.ZodObject<{
         cliVersion: z.ZodString;
@@ -299,7 +303,9 @@ export declare const telemetryEventSchemas: {
         }>;
         durationMs: z.ZodNumber;
         errorClass: z.ZodOptional<z.ZodString>;
-        sampleRate: z.ZodLiteral<0.1>;
+        sampleRate: z.ZodLiteral<1>;
+        mcpClientName: z.ZodOptional<z.ZodString>;
+        mcpClientVersion: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
     readonly daemon_started: z.ZodObject<{
         cliVersion: z.ZodString;
@@ -389,11 +395,11 @@ export declare const telemetryEventCatalog: readonly [{
 }, {
     readonly name: "command";
     readonly description: "Emitted once for each Commander action that reaches preAction.";
-    readonly fields: readonly ["commandPath", "durationMs", "outcome", "errorClass", "flagsPresent", "hasProject", "projectGroupAttached"];
+    readonly fields: readonly ["commandPath", "durationMs", "outcome", "errorClass", "errorDetail", "flagsPresent", "hasProject", "projectGroupAttached"];
 }, {
     readonly name: "setup_step";
     readonly description: "Emitted after an interactive setup step completes, skips, or aborts.";
-    readonly fields: readonly ["step", "outcome", "durationMs"];
+    readonly fields: readonly ["step", "outcome", "durationMs", "errorDetail"];
 }, {
     readonly name: "connection_added";
     readonly description: "Emitted when setup writes a database, source, or demo connection.";
@@ -401,7 +407,7 @@ export declare const telemetryEventCatalog: readonly [{
 }, {
     readonly name: "connection_test";
     readonly description: "Emitted after ktx connection test completes.";
-    readonly fields: readonly ["driver", "isDemoConnection", "outcome", "errorClass", "durationMs", "serverVersion"];
+    readonly fields: readonly ["driver", "isDemoConnection", "outcome", "errorClass", "errorDetail", "durationMs", "serverVersion"];
 }, {
     readonly name: "project_stack_snapshot";
     readonly description: "Emitted after commands that can summarize the local project stack.";
@@ -409,11 +415,11 @@ export declare const telemetryEventCatalog: readonly [{
 }, {
     readonly name: "ingest_completed";
     readonly description: "Emitted after a public ingest target completes.";
-    readonly fields: readonly ["driver", "isDemoConnection", "schemaCount", "tableCount", "columnCount", "rowsBucket", "durationMs", "outcome", "errorClass"];
+    readonly fields: readonly ["driver", "isDemoConnection", "schemaCount", "tableCount", "columnCount", "rowsBucket", "durationMs", "outcome", "errorClass", "errorDetail"];
 }, {
     readonly name: "scan_completed";
     readonly description: "Emitted after schema scan or relationship inference completes.";
-    readonly fields: readonly ["driver", "tableCount", "columnCount", "inferredFkCount", "declaredFkCount", "durationMs", "outcome", "errorClass"];
+    readonly fields: readonly ["driver", "tableCount", "columnCount", "inferredFkCount", "declaredFkCount", "durationMs", "outcome", "errorClass", "errorDetail"];
 }, {
     readonly name: "sl_validate_completed";
     readonly description: "Emitted after ktx sl validate completes.";
@@ -433,7 +439,7 @@ export declare const telemetryEventCatalog: readonly [{
 }, {
     readonly name: "mcp_request_completed";
     readonly description: "Emitted for sampled MCP tool requests.";
-    readonly fields: readonly ["toolName", "outcome", "durationMs", "errorClass", "sampleRate"];
+    readonly fields: readonly ["toolName", "outcome", "durationMs", "errorClass", "sampleRate", "mcpClientName", "mcpClientVersion"];
 }, {
     readonly name: "daemon_started";
     readonly description: "Emitted when the long-lived ktx-daemon HTTP server starts.";

package/dist/telemetry/events.js

@@ -18,6 +18,7 @@ const commandSchema = telemetryCommonEnvelopeSchema
     durationMs: z.number().nonnegative(),
     outcome: z.enum(['ok', 'error', 'aborted']),
     errorClass: z.string().optional(),
+    errorDetail: z.string().max(1000).optional(),
     flagsPresent: z.record(z.string(), z.boolean()),
     hasProject: z.boolean(),
     projectGroupAttached: z.boolean(),
@@ -33,7 +34,6 @@ const setupStepSchema = telemetryCommonEnvelopeSchema
         'embeddings',
         'secrets',
         'databases',
-        'database-context-depth',
         'sources',
         'context',
         'agents',
@@ -41,6 +41,7 @@ const setupStepSchema = telemetryCommonEnvelopeSchema
     ]),
     outcome: z.enum(['completed', 'skipped', 'abandoned']),
     durationMs: z.number().nonnegative(),
+    errorDetail: z.string().max(1000).optional(),
 })
     .strict();
 const connectionAddedSchema = telemetryCommonEnvelopeSchema
@@ -55,6 +56,7 @@ const connectionTestSchema = telemetryCommonEnvelopeSchema
     isDemoConnection: z.boolean(),
     outcome: outcomeSchema,
     errorClass: z.string().optional(),
+    errorDetail: z.string().max(1000).optional(),
     durationMs: z.number().nonnegative(),
     serverVersion: z.string().optional(),
 })
@@ -81,6 +83,7 @@ const ingestCompletedSchema = telemetryCommonEnvelopeSchema
     durationMs: z.number().nonnegative(),
     outcome: outcomeSchema,
     errorClass: z.string().optional(),
+    errorDetail: z.string().max(1000).optional(),
 })
     .strict();
 const scanCompletedSchema = telemetryCommonEnvelopeSchema
@@ -93,6 +96,7 @@ const scanCompletedSchema = telemetryCommonEnvelopeSchema
     durationMs: z.number().nonnegative(),
     outcome: outcomeSchema,
     errorClass: z.string().optional(),
+    errorDetail: z.string().max(1000).optional(),
 })
     .strict();
 const slValidateCompletedSchema = telemetryCommonEnvelopeSchema
@@ -141,7 +145,12 @@ const mcpRequestCompletedSchema = telemetryCommonEnvelopeSchema
     outcome: outcomeSchema,
     durationMs: z.number().nonnegative(),
     errorClass: z.string().optional(),
-    sampleRate: z.literal(0.1),
+    sampleRate: z.literal(1),
+    // Raw, client-tool-controlled identity from the MCP initialize handshake
+    // (clientInfo.name/version). Optional: clients may omit clientInfo. Stored
+    // verbatim — normalize the free-form names at query time, not at write time.
+    mcpClientName: z.string().optional(),
+    mcpClientVersion: z.string().optional(),
 })
     .strict();
 const daemonStartedSchema = telemetryCommonEnvelopeSchema
@@ -211,6 +220,7 @@ export const telemetryEventCatalog = [
             'durationMs',
             'outcome',
             'errorClass',
+            'errorDetail',
             'flagsPresent',
             'hasProject',
             'projectGroupAttached',
@@ -219,7 +229,7 @@ export const telemetryEventCatalog = [
     {
         name: 'setup_step',
         description: 'Emitted after an interactive setup step completes, skips, or aborts.',
-        fields: ['step', 'outcome', 'durationMs'],
+        fields: ['step', 'outcome', 'durationMs', 'errorDetail'],
     },
     {
         name: 'connection_added',
@@ -229,7 +239,7 @@ export const telemetryEventCatalog = [
     {
         name: 'connection_test',
         description: 'Emitted after ktx connection test completes.',
-        fields: ['driver', 'isDemoConnection', 'outcome', 'errorClass', 'durationMs', 'serverVersion'],
+        fields: ['driver', 'isDemoConnection', 'outcome', 'errorClass', 'errorDetail', 'durationMs', 'serverVersion'],
     },
     {
         name: 'project_stack_snapshot',
@@ -249,6 +259,7 @@ export const telemetryEventCatalog = [
             'durationMs',
             'outcome',
             'errorClass',
+            'errorDetail',
         ],
     },
     {
@@ -263,6 +274,7 @@ export const telemetryEventCatalog = [
             'durationMs',
             'outcome',
             'errorClass',
+            'errorDetail',
         ],
     },
     {
@@ -304,7 +316,7 @@ export const telemetryEventCatalog = [
     {
         name: 'mcp_request_completed',
         description: 'Emitted for sampled MCP tool requests.',
-        fields: ['toolName', 'outcome', 'durationMs', 'errorClass', 'sampleRate'],
+        fields: ['toolName', 'outcome', 'durationMs', 'errorClass', 'sampleRate', 'mcpClientName', 'mcpClientVersion'],
     },
     {
         name: 'daemon_started',

package/dist/telemetry/identity.d.ts

@@ -1,5 +1,5 @@
 /** @internal */
-export declare const TELEMETRY_NOTICE = "ktx collects anonymous usage data to improve the product. Opt out: set KTX_TELEMETRY_DISABLED=1.";
+export declare const TELEMETRY_NOTICE = "ktx collects usage data to improve the product. Opt out: set KTX_TELEMETRY_DISABLED=1.";
 /** @internal */
 export interface TelemetryIdentityEnv {
     KTX_TELEMETRY_DISABLED?: string;
@@ -11,7 +11,6 @@ export interface TelemetryIdentityEnv {
 export interface LoadTelemetryIdentityOptions {
     homeDir?: string;
     env?: TelemetryIdentityEnv;
-    stdoutIsTTY: boolean;
     stderr: {
         write(chunk: string): void;
     };

package/dist/telemetry/identity.js

@@ -4,7 +4,7 @@ import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { z } from 'zod';
 /** @internal */
-export const TELEMETRY_NOTICE = 'ktx collects anonymous usage data to improve the product. Opt out: set KTX_TELEMETRY_DISABLED=1.';
+export const TELEMETRY_NOTICE = 'ktx collects usage data to improve the product. Opt out: set KTX_TELEMETRY_DISABLED=1.';
 const NOTICE_VERSION = 1;
 const telemetryFileSchema = z
     .object({
@@ -41,16 +41,13 @@ async function writeTelemetryFile(path, value) {
 export async function loadTelemetryIdentity(options) {
     const env = options.env ?? process.env;
     const path = telemetryPath(options.homeDir ?? homedir());
-    if (envDisablesTelemetry(env) || options.stdoutIsTTY !== true) {
-        const existing = await readTelemetryFile(path);
-        return {
-            installId: existing?.installId,
-            enabled: false,
-            createdFile: false,
-            noticeShown: false,
-            path,
-        };
+    if (envDisablesTelemetry(env)) {
+        return { enabled: false, createdFile: false, noticeShown: false, path };
     }
+    // Honor an already-consented identity regardless of the current surface.
+    // Telemetry enablement follows the persisted decision and opt-out env vars,
+    // not whether this invocation happens to own a TTY — MCP servers always run
+    // headless (stdio stubs stdout; the HTTP server runs detached).
     const existing = await readTelemetryFile(path);
     if (existing) {
         return {
@@ -61,6 +58,12 @@ export async function loadTelemetryIdentity(options) {
             path,
         };
     }
+    // No identity yet → mint one regardless of surface. Telemetry is opt-out, so
+    // a fresh install is counted even when its first run is headless (an
+    // IDE-launched `ktx mcp stdio`, a scripted invocation); otherwise those
+    // installs would be permanently invisible. Opt-out env vars are honored
+    // above. The one-time notice is written to stderr — safe even under MCP
+    // stdio, which reserves stdout for its JSON-RPC protocol.
     const timestamp = (options.now ?? (() => new Date()))().toISOString();
     const next = {
         installId: randomUUID(),

package/dist/telemetry/index.d.ts

@@ -7,7 +7,7 @@ export type { CommandOutcome, CompletedCommandSpan };
 export declare function showTelemetryNoticeIfNeeded(io: KtxCliIo, packageInfo: KtxCliPackageInfo): Promise<void>;
 type TelemetryEventFields<Name extends TelemetryEventName> = Omit<TelemetryEventProperties<Name>, keyof TelemetryCommonEnvelope>;
 export declare function shouldEmitMcpTelemetry(): boolean;
-export declare function mcpTelemetrySampleRate(): 0.1;
+export declare function mcpTelemetrySampleRate(): 1;
 export declare function emitTelemetryEvent<Name extends TelemetryEventName>(input: {
     name: Name;
     fields: TelemetryEventFields<Name>;
@@ -25,3 +25,15 @@ export declare function emitCompletedCommand(input: {
     packageInfo: KtxCliPackageInfo;
     io: KtxCliIo;
 }): Promise<void>;
+/**
+ * Flush telemetry when the process is interrupted (Ctrl-C / kill). The normal
+ * `command` emit + flush lives in a `finally` that a signal skips, so without
+ * this an interrupted long-running command (ingest, `mcp stdio`) loses its
+ * `command` event and any queued events. Marks the active command span as
+ * `aborted`, emits it, and drains the emitter. Best-effort and idempotent: if
+ * the span was already completed (normal exit racing a signal) the emit no-ops.
+ */
+export declare function emitAbortedCommandAndShutdown(input: {
+    packageInfo: KtxCliPackageInfo;
+    io: KtxCliIo;
+}): Promise<void>;

package/dist/telemetry/index.js

@@ -8,7 +8,6 @@ import { buildProjectStackSnapshotFields } from './project-snapshot.js';
 export { beginCommandSpan, completeCommandSpan, shutdownTelemetryEmitter };
 export async function showTelemetryNoticeIfNeeded(io, packageInfo) {
     const identity = await loadTelemetryIdentity({
-        stdoutIsTTY: io.stdout.isTTY === true,
         stderr: io.stderr,
         env: process.env,
     });
@@ -26,7 +25,11 @@ export async function showTelemetryNoticeIfNeeded(io, packageInfo) {
     });
 }
 const emittedProjectSnapshots = new Set();
-const MCP_SAMPLE_RATE = 0.1;
+// MCP tool calls are captured at full rate while ktx is early-stage: at current
+// install counts any sampling below 1.0 yields too few events to be useful, and
+// the recorded sampleRate lets us dial this down (and reweight history) once
+// per-session call volume justifies it.
+const MCP_SAMPLE_RATE = 1;
 let mcpSampled;
 function telemetryDebugEnabled() {
     return process.env.KTX_TELEMETRY_DEBUG === '1';
@@ -41,7 +44,6 @@ export function mcpTelemetrySampleRate() {
 export async function emitTelemetryEvent(input) {
     const debug = telemetryDebugEnabled();
     const identity = await loadTelemetryIdentity({
-        stdoutIsTTY: input.io.stdout.isTTY === true,
         stderr: input.io.stderr,
         env: process.env,
     });
@@ -96,3 +98,16 @@ export async function emitCompletedCommand(input) {
         packageInfo: input.packageInfo,
     });
 }
+/**
+ * Flush telemetry when the process is interrupted (Ctrl-C / kill). The normal
+ * `command` emit + flush lives in a `finally` that a signal skips, so without
+ * this an interrupted long-running command (ingest, `mcp stdio`) loses its
+ * `command` event and any queued events. Marks the active command span as
+ * `aborted`, emits it, and drains the emitter. Best-effort and idempotent: if
+ * the span was already completed (normal exit racing a signal) the emit no-ops.
+ */
+export async function emitAbortedCommandAndShutdown(input) {
+    const completed = completeCommandSpan({ completedAt: performance.now(), outcome: 'aborted' });
+    await emitCompletedCommand({ completed, packageInfo: input.packageInfo, io: input.io });
+    await shutdownTelemetryEmitter();
+}

package/dist/telemetry/scrubber.d.ts

@@ -1 +1,11 @@
 export declare function scrubErrorClass(error: unknown): string | undefined;
+/**
+ * Human-readable failure detail for telemetry: the error's `.code` (when
+ * present) prefixed onto its `message`, collapsed to a single line and
+ * length-capped. Captures the message only — never the stack.
+ *
+ * This intentionally forwards raw error text, which can include identifiers from
+ * the user's environment (table/column names, hostnames, usernames), so that
+ * funnel failures are diagnosable. Callers must gate it to the failure path.
+ */
+export declare function formatErrorDetail(error: unknown): string | undefined;

package/dist/telemetry/scrubber.js

@@ -20,3 +20,23 @@ export function scrubErrorClass(error) {
     }
     return constructorName;
 }
+const MAX_ERROR_DETAIL_LENGTH = 1000;
+/**
+ * Human-readable failure detail for telemetry: the error's `.code` (when
+ * present) prefixed onto its `message`, collapsed to a single line and
+ * length-capped. Captures the message only — never the stack.
+ *
+ * This intentionally forwards raw error text, which can include identifiers from
+ * the user's environment (table/column names, hostnames, usernames), so that
+ * funnel failures are diagnosable. Callers must gate it to the failure path.
+ */
+export function formatErrorDetail(error) {
+    if (error === undefined || error === null) {
+        return undefined;
+    }
+    const code = error.code;
+    const message = error instanceof Error ? error.message : String(error);
+    const prefix = typeof code === 'string' || typeof code === 'number' ? `${code}: ` : '';
+    const detail = `${prefix}${message}`.replace(/\s+/g, ' ').trim();
+    return detail.length > 0 ? detail.slice(0, MAX_ERROR_DETAIL_LENGTH) : undefined;
+}