@kaelio/ktx 0.10.0 → 0.12.0

package/dist/telemetry/command-hook.js

@@ -3,18 +3,52 @@ let activeCommandSpan;
 export function beginCommandSpan(input) {
     activeCommandSpan = input;
 }
+/**
+ * Let a command action record the true outcome and reason on the active span.
+ *
+ * The Commander wrapper can only derive an outcome from a thrown error or the
+ * process exit code, so a command that exits non-zero *without throwing* (e.g.
+ * `ktx setup` when the user abandons the wizard) lands as `outcome: 'error'`
+ * with no `errorClass`/`errorDetail` — an unactionable blank in the dashboard.
+ * The action is the decision-maker: it can mark the run `aborted`, or attach a
+ * scrubbed reason so the next occurrence is self-diagnosing. A later thrown
+ * error still wins (see {@link completeCommandSpan}), since that is the most
+ * authoritative signal and also feeds the `$exception` stream. No-ops when no
+ * span is active so call sites stay safe in tests and bare-help paths.
+ *
+ * Values are emitted verbatim and must already satisfy the telemetry privacy
+ * rules — pass synthetic or already-scrubbed strings, never raw user input.
+ */
+export function annotateCommandOutcome(input) {
+    if (!activeCommandSpan) {
+        return;
+    }
+    if (input.outcome !== undefined) {
+        activeCommandSpan.annotatedOutcome = input.outcome;
+    }
+    if (input.errorClass !== undefined) {
+        activeCommandSpan.annotatedErrorClass = input.errorClass;
+    }
+    if (input.errorDetail !== undefined) {
+        activeCommandSpan.annotatedErrorDetail = input.errorDetail;
+    }
+}
 export function completeCommandSpan(input) {
     const span = activeCommandSpan;
     activeCommandSpan = undefined;
     if (!span) {
         return undefined;
     }
-    const errorClass = input.error ? scrubErrorClass(input.error) : undefined;
-    const errorDetail = input.error ? formatErrorDetail(input.error) : undefined;
+    // Precedence: a thrown error is authoritative; otherwise an action's own
+    // annotation; otherwise the wrapper's exit-code-derived outcome.
+    const thrown = Boolean(input.error);
+    const outcome = thrown ? input.outcome : (span.annotatedOutcome ?? input.outcome);
+    const errorClass = thrown ? scrubErrorClass(input.error) : span.annotatedErrorClass;
+    const errorDetail = thrown ? formatErrorDetail(input.error) : span.annotatedErrorDetail;
     return {
         commandPath: span.commandPath,
         durationMs: Math.max(0, input.completedAt - span.startedAt),
-        outcome: input.outcome,
+        outcome,
         ...(errorClass ? { errorClass } : {}),
         ...(errorDetail ? { errorDetail } : {}),
         flagsPresent: span.flagsPresent,

package/dist/telemetry/events.d.ts

@@ -357,9 +357,9 @@ export declare const telemetryEventSchemas: {
             error: "error";
         }>;
         stage: z.ZodEnum<{
+            resolve: "resolve";
             parse: "parse";
             compile: "compile";
-            resolve: "resolve";
             transpile: "transpile";
         }>;
         errorClass: z.ZodOptional<z.ZodString>;

package/dist/telemetry/exception.js

@@ -1,5 +1,6 @@
 import { inspect } from 'node:util';
 import { getKtxCliPackageInfo } from '../cli-runtime.js';
+import { KtxExpectedError } from '../errors.js';
 import { buildCommonEnvelope } from './events.js';
 import { trackTelemetryException } from './emitter.js';
 import { computeTelemetryProjectId, loadTelemetryIdentity } from './identity.js';
@@ -24,6 +25,16 @@ function consumeHandledPrimitive(value) {
     recentHandledPrimitives.splice(index, 1);
     return true;
 }
+/**
+ * Expected operational errors are surfaced to the caller and recorded by the
+ * outcome-tagged telemetry events; they are not ktx faults, so they never reach
+ * Error Tracking. ktx marks these with KtxExpectedError at the site that knows
+ * the rejection is expected — the classification is never inferred globally from
+ * a generic error type, which would also swallow internal/fatal faults.
+ */
+function isExpectedError(error) {
+    return error instanceof KtxExpectedError;
+}
 function shouldSkipAsAlreadyReported(error, handled) {
     if ((typeof error === 'object' || typeof error === 'function') && error !== null) {
         if (reportedObjects.has(error)) {
@@ -116,6 +127,9 @@ function sanitizedError(error, secrets) {
 }
 export async function reportException(input) {
     try {
+        if (isExpectedError(input.error)) {
+            return;
+        }
         if (shouldSkipAsAlreadyReported(input.error, input.context.handled)) {
             return;
         }

package/dist/telemetry/index.d.ts

@@ -1,9 +1,9 @@
 import { type KtxCliIo, type KtxCliPackageInfo } from '../cli-runtime.js';
-import { beginCommandSpan, completeCommandSpan, type CommandOutcome, type CompletedCommandSpan } from './command-hook.js';
+import { annotateCommandOutcome, beginCommandSpan, completeCommandSpan, type CommandOutcome, type CompletedCommandSpan } from './command-hook.js';
 import { shutdownTelemetryEmitter } from './emitter.js';
 import { reportException, type ExceptionContext } from './exception.js';
 import { type TelemetryCommonEnvelope, type TelemetryEventName, type TelemetryEventProperties } from './events.js';
-export { beginCommandSpan, completeCommandSpan, reportException, shutdownTelemetryEmitter };
+export { annotateCommandOutcome, beginCommandSpan, completeCommandSpan, reportException, shutdownTelemetryEmitter };
 export type { CommandOutcome, CompletedCommandSpan, ExceptionContext };
 export declare function showTelemetryNoticeIfNeeded(io: KtxCliIo, packageInfo: KtxCliPackageInfo): Promise<void>;
 type TelemetryEventFields<Name extends TelemetryEventName> = Omit<TelemetryEventProperties<Name>, keyof TelemetryCommonEnvelope>;

package/dist/telemetry/index.js

@@ -1,12 +1,12 @@
 import { getKtxCliPackageInfo } from '../cli-runtime.js';
 import { loadKtxProject } from '../context/project/project.js';
-import { beginCommandSpan, completeCommandSpan, } from './command-hook.js';
+import { annotateCommandOutcome, beginCommandSpan, completeCommandSpan, } from './command-hook.js';
 import { shutdownTelemetryEmitter, trackTelemetryEvent } from './emitter.js';
 import { reportException } from './exception.js';
 import { buildCommonEnvelope, buildTelemetryEvent, } from './events.js';
 import { computeTelemetryProjectId, loadTelemetryIdentity } from './identity.js';
 import { buildProjectStackSnapshotFields } from './project-snapshot.js';
-export { beginCommandSpan, completeCommandSpan, reportException, shutdownTelemetryEmitter };
+export { annotateCommandOutcome, beginCommandSpan, completeCommandSpan, reportException, shutdownTelemetryEmitter };
 export async function showTelemetryNoticeIfNeeded(io, packageInfo) {
     const identity = await loadTelemetryIdentity({
         stderr: io.stderr,

package/dist/text-ingest.js

@@ -213,7 +213,7 @@ export async function runKtxTextIngest(args, io, deps = {}) {
                 const ingestInput = {
                     userId: args.userId,
                     chatId: `cli-text-ingest-${batchId}-${index + 1}`,
-                    userMessage: `Ingest external text artifact ${artifactReference(item.label)} into KTX memory.`,
+                    userMessage: `Ingest external text artifact ${artifactReference(item.label)} into ktx memory.`,
                     assistantMessage: item.content.trim(),
                     ...(args.connectionId ? { connectionId: args.connectionId } : {}),
                     sourceType: 'external_ingest',

package/dist/tree-picker-tui.d.ts

@@ -33,7 +33,6 @@ export type TreePickerResult = {
 };
 export interface TreePickerChrome {
     title: string;
-    helpText?: string;
     subtitleLines?: readonly string[];
     warningLines?: readonly string[];
     confirmSaveMessage?: (state: PickerState) => string;

package/dist/tree-picker-tui.js

@@ -3,6 +3,7 @@ import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 import { Box, Text, render as renderInkRuntime, useApp, useInput } from 'ink';
 import { useEffect, useMemo, useRef, useState } from 'react';
 import { filterTree, flattenSelection, hasPartialChildren, isAncestorChecked, reducer, visibleNodeIds, } from './tree-picker-state.js';
+import { TREE_PICKER_NAVIGATION_HINT } from './prompt-navigation.js';
 const COLOR_THEME = {
     text: 'white',
     muted: 'gray',
@@ -17,7 +18,6 @@ const NO_COLOR_THEME = {
     selected: 'white',
     warning: 'white',
 };
-const DEFAULT_TREE_PICKER_HELP_TEXT = 'Up/Down to move, Right/Left to expand or collapse, Tab to select, Type to search, Enter to confirm, Escape to clear search or go back, Ctrl+C to exit.';
 const DEFAULT_SKIP_EMPTY_MESSAGE = 'Nothing selected. Skip this step? Press Enter to skip or Escape to go back.';
 function resolveTheme(env = process.env) {
     return env.NO_COLOR || env.TERM === 'dumb' ? NO_COLOR_THEME : COLOR_THEME;
@@ -136,7 +136,6 @@ export function TreePickerApp(props) {
     const hiddenBelow = Math.max(0, visibleIds.length - rows.offset - rows.items.length);
     const searchMatchCount = filterTree(state).visibleIds.size;
     const width = resolveTreePickerWidth(props.terminalWidth);
-    const helpText = props.chrome.helpText ?? DEFAULT_TREE_PICKER_HELP_TEXT;
     const skipEmptyMessage = props.chrome.skipEmptyMessage ?? DEFAULT_SKIP_EMPTY_MESSAGE;
     stateRef.current = state;
     useEffect(() => {
@@ -177,7 +176,7 @@ export function TreePickerApp(props) {
             app.exit();
         }
     });
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { children: [_jsx(Text, { color: theme.active, children: "\u25C6" }), _jsxs(Text, { bold: true, children: [" ", props.chrome.title] })] }), _jsxs(Box, { flexDirection: "column", borderStyle: "single", borderTop: false, borderRight: false, borderBottom: false, borderColor: theme.active, paddingLeft: 1, children: [_jsx(Text, { color: theme.muted, children: helpText }), _jsx(Text, { children: " " }), (props.chrome.subtitleLines ?? []).map((line, idx) => (_jsx(Text, { color: theme.muted, children: line }, `subtitle-${idx}`))), (props.chrome.warningLines ?? []).map((line, idx) => (_jsx(Text, { color: theme.warning, children: line }, `chromewarn-${idx}`))), state.preLoadWarnings.map((warning) => (_jsx(Text, { color: theme.warning, children: warning }, warning))), _jsxs(Text, { children: [_jsx(Text, { color: theme.muted, children: "Search: " }), state.isNavigating ? (_jsx(Text, { color: theme.muted, children: state.search.query || '(type to filter)' })) : (_jsxs(Text, { children: [state.search.query, _jsx(Text, { inverse: true, children: " " })] })), _jsxs(Text, { color: theme.muted, children: ["  (", searchMatchCount, " match", searchMatchCount === 1 ? '' : 'es', ")"] })] }), _jsx(Text, { children: " " }), hiddenAbove > 0 ? _jsxs(Text, { color: theme.muted, children: ["\u2191 ", hiddenAbove, " more"] }) : null, rows.items.map((nodeId) => (_jsx(PickerRow, { state: state, nodeId: nodeId, width: width, theme: theme }, nodeId))), hiddenBelow > 0 ? _jsxs(Text, { color: theme.muted, children: ["\u2193 ", hiddenBelow, " more"] }) : null, state.pendingConfirm === 'save-confirm' ? (_jsx(Text, { color: theme.warning, children: props.chrome.confirmSaveMessage
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { children: [_jsx(Text, { color: theme.active, children: "\u25C6" }), _jsxs(Text, { bold: true, children: [" ", props.chrome.title] })] }), _jsxs(Box, { flexDirection: "column", borderStyle: "single", borderTop: false, borderRight: false, borderBottom: false, borderColor: theme.active, paddingLeft: 1, children: [_jsx(Text, { color: theme.muted, children: TREE_PICKER_NAVIGATION_HINT }), _jsx(Text, { children: " " }), (props.chrome.subtitleLines ?? []).map((line, idx) => (_jsx(Text, { color: theme.muted, children: line }, `subtitle-${idx}`))), (props.chrome.warningLines ?? []).map((line, idx) => (_jsx(Text, { color: theme.warning, children: line }, `chromewarn-${idx}`))), state.preLoadWarnings.map((warning) => (_jsx(Text, { color: theme.warning, children: warning }, warning))), _jsxs(Text, { children: [_jsx(Text, { color: theme.muted, children: "Search: " }), state.isNavigating ? (_jsx(Text, { color: theme.muted, children: state.search.query || '(type to search)' })) : (_jsxs(Text, { children: [state.search.query, _jsx(Text, { inverse: true, children: " " })] })), _jsxs(Text, { color: theme.muted, children: ["  (", searchMatchCount, " match", searchMatchCount === 1 ? '' : 'es', ")"] })] }), _jsx(Text, { children: " " }), hiddenAbove > 0 ? _jsxs(Text, { color: theme.muted, children: ["\u2191 ", hiddenAbove, " more"] }) : null, rows.items.map((nodeId) => (_jsx(PickerRow, { state: state, nodeId: nodeId, width: width, theme: theme }, nodeId))), hiddenBelow > 0 ? _jsxs(Text, { color: theme.muted, children: ["\u2193 ", hiddenBelow, " more"] }) : null, state.pendingConfirm === 'save-confirm' ? (_jsx(Text, { color: theme.warning, children: props.chrome.confirmSaveMessage
                             ? props.chrome.confirmSaveMessage(state)
                             : 'Confirm save? Press Enter to confirm or Escape to go back.' })) : null, state.pendingConfirm === 'skip-empty' ? _jsx(Text, { color: theme.warning, children: skipEmptyMessage }) : null, state.transientHint ? _jsx(Text, { color: theme.warning, children: state.transientHint.text }) : null] }), _jsx(Text, { color: theme.active, children: "\u2514" })] }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaelio/ktx",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Standalone ktx context layer for data agents",
   "author": {
     "name": "Kaelio",