@kaelio/ktx 0.8.0 → 0.9.0

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/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,8 +68,8 @@ export declare const telemetryEventSchemas: {
             databases: "databases";
             context: "context";
             runtime: "runtime";
-            agents: "agents";
             secrets: "secrets";
+            agents: "agents";
             "demo-tour": "demo-tour";
         }>;
         outcome: z.ZodEnum<{
@@ -77,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;
@@ -110,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>;
@@ -163,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;
@@ -186,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;
@@ -390,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.";
@@ -402,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.";
@@ -410,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.";

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(),
@@ -40,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
@@ -54,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(),
 })
@@ -80,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
@@ -92,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
@@ -215,6 +220,7 @@ export const telemetryEventCatalog = [
             'durationMs',
             'outcome',
             'errorClass',
+            'errorDetail',
             'flagsPresent',
             'hasProject',
             'projectGroupAttached',
@@ -223,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',
@@ -233,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',
@@ -253,6 +259,7 @@ export const telemetryEventCatalog = [
             'durationMs',
             'outcome',
             'errorClass',
+            'errorDetail',
         ],
     },
     {
@@ -267,6 +274,7 @@ export const telemetryEventCatalog = [
             'durationMs',
             'outcome',
             'errorClass',
+            'errorDetail',
         ],
     },
     {

package/dist/telemetry/identity.d.ts

@@ -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

@@ -58,12 +58,12 @@ export async function loadTelemetryIdentity(options) {
             path,
         };
     }
-    // No identity yet. Minting one means showing the one-time opt-out notice, so
-    // first-run creation requires an interactive surface; a headless first run
-    // stays disabled and defers enablement until the next interactive run.
-    if (options.stdoutIsTTY !== true) {
-        return { enabled: false, createdFile: false, noticeShown: false, 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

@@ -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,
     });
@@ -45,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,
     });
@@ -100,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;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaelio/ktx",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Standalone ktx context layer for data agents",
   "type": "module",
   "engines": {
@@ -41,6 +41,7 @@
     "@looker/sdk-rtl": "^21.6.5",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@notionhq/client": "^5.22.0",
+    "@openai/codex-sdk": "^0.133.0",
     "ai": "^6.0.188",
     "better-sqlite3": "^12.10.0",
     "commander": "14.0.3",
@@ -78,13 +79,13 @@
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Kaelio/ktx-ai-data-agents-context",
+    "url": "https://github.com/Kaelio/ktx",
     "directory": "packages/cli"
   },
   "bugs": {
-    "url": "https://github.com/Kaelio/ktx-ai-data-agents-context/issues"
+    "url": "https://github.com/Kaelio/ktx/issues"
   },
-  "homepage": "https://github.com/Kaelio/ktx-ai-data-agents-context#readme",
+  "homepage": "https://github.com/Kaelio/ktx#readme",
   "scripts": {
     "assets:demo": "node scripts/build-demo-assets.mjs",
     "build": "tsc -p tsconfig.json && node dist/telemetry/schema-writer.js src/telemetry/events.schema.json ../../python/ktx-daemon/src/ktx_daemon/telemetry/events.schema.json && node scripts/copy-runtime-assets.mjs && node ../../scripts/prepare-cli-bin.mjs",