@kaelio/ktx 0.7.0 → 0.9.0

package/dist/context/llm/codex-sdk-runner.js

@@ -0,0 +1,63 @@
+import { Codex } from '@openai/codex-sdk';
+const CODEX_ENV_ALLOWLIST = new Set([
+    'HOME',
+    'USERPROFILE',
+    'APPDATA',
+    'LOCALAPPDATA',
+    'XDG_CONFIG_HOME',
+    'CODEX_HOME',
+    'CODEX_API_KEY',
+    'OPENAI_API_KEY',
+    'PATH',
+    'Path',
+    'SYSTEMROOT',
+    'COMSPEC',
+    'TMPDIR',
+    'TMP',
+    'TEMP',
+    'SSL_CERT_FILE',
+    'SSL_CERT_DIR',
+    'NODE_EXTRA_CA_CERTS',
+    'HTTPS_PROXY',
+    'HTTP_PROXY',
+    'ALL_PROXY',
+    'NO_PROXY',
+]);
+function buildCodexSdkEnv(baseEnv, overrides) {
+    const env = {};
+    for (const key of CODEX_ENV_ALLOWLIST) {
+        const value = baseEnv[key];
+        if (typeof value === 'string') {
+            env[key] = value;
+        }
+    }
+    return { ...env, ...(overrides ?? {}) };
+}
+export class CodexSdkCliRunner {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async runStreamed(input) {
+        const CodexClass = Codex;
+        const codex = new CodexClass({
+            ...(input.configOverrides ? { config: input.configOverrides } : {}),
+            env: buildCodexSdkEnv(this.options.envBase ?? process.env, input.env),
+            ...(this.options.codexPathOverride ? { codexPathOverride: this.options.codexPathOverride } : {}),
+        });
+        const thread = codex.startThread({
+            workingDirectory: input.projectDir,
+            skipGitRepoCheck: true,
+            model: input.model,
+            sandboxMode: 'read-only',
+            webSearchMode: 'disabled',
+            approvalPolicy: 'never',
+        });
+        const turnOptions = {
+            ...(input.outputSchema ? { outputSchema: input.outputSchema } : {}),
+            ...(input.signal ? { signal: input.signal } : {}),
+        };
+        const streamed = await thread.runStreamed(input.prompt, Object.keys(turnOptions).length > 0 ? turnOptions : undefined);
+        return streamed.events;
+    }
+}

package/dist/context/llm/local-config.d.ts

@@ -3,6 +3,7 @@ import { createKtxLlmProvider } from '../../llm/model-provider.js';
 import type { KtxEmbeddingConfig, KtxEmbeddingProvider, KtxLlmConfig, KtxLlmProvider } from '../../llm/types.js';
 import type { KtxProjectEmbeddingConfig, KtxProjectLlmConfig } from '../project/config.js';
 import { ClaudeCodeKtxLlmRuntime } from './claude-code-runtime.js';
+import { CodexKtxLlmRuntime } from './codex-runtime.js';
 import type { KtxLlmRuntimePort } from './runtime-port.js';
 interface LocalConfigDeps {
     env?: NodeJS.ProcessEnv;
@@ -10,6 +11,7 @@ interface LocalConfigDeps {
     createKtxLlmProvider?: typeof createKtxLlmProvider;
     createKtxEmbeddingProvider?: typeof createKtxEmbeddingProvider;
     createClaudeCodeRuntime?: (deps: ConstructorParameters<typeof ClaudeCodeKtxLlmRuntime>[0]) => KtxLlmRuntimePort;
+    createCodexRuntime?: (deps: ConstructorParameters<typeof CodexKtxLlmRuntime>[0]) => KtxLlmRuntimePort;
     createAiSdkRuntime?: (deps: {
         llmProvider: KtxLlmProvider;
     }) => KtxLlmRuntimePort;

package/dist/context/llm/local-config.js

@@ -3,6 +3,7 @@ import { createKtxLlmProvider } from '../../llm/model-provider.js';
 import { resolveKtxConfigReference } from '../core/config-reference.js';
 import { AiSdkKtxLlmRuntime } from './ai-sdk-runtime.js';
 import { ClaudeCodeKtxLlmRuntime } from './claude-code-runtime.js';
+import { CodexKtxLlmRuntime } from './codex-runtime.js';
 function resolveOptional(value, env) {
     return resolveKtxConfigReference(value, env) || undefined;
 }
@@ -70,7 +71,7 @@ export function resolveLocalKtxLlmConfig(config, env) {
 /** @internal */
 export function createLocalKtxLlmProviderFromConfig(config, deps = {}) {
     const resolved = resolveLocalKtxLlmConfig(config, deps.env ?? process.env);
-    if (!resolved || resolved.backend === 'claude-code') {
+    if (!resolved || resolved.backend === 'claude-code' || resolved.backend === 'codex') {
         return null;
     }
     return (deps.createKtxLlmProvider ?? createKtxLlmProvider)(resolved);
@@ -91,6 +92,16 @@ export function createLocalKtxLlmRuntimeFromConfig(config, deps = {}) {
             env: deps.env,
         });
     }
+    if (resolved.backend === 'codex') {
+        const projectDir = deps.projectDir;
+        if (!projectDir) {
+            throw new Error('projectDir is required when creating the codex LLM runtime');
+        }
+        return (deps.createCodexRuntime ?? ((runtimeDeps) => new CodexKtxLlmRuntime(runtimeDeps)))({
+            projectDir,
+            modelSlots: resolved.modelSlots,
+        });
+    }
     const llmProvider = (deps.createKtxLlmProvider ?? createKtxLlmProvider)(resolved);
     return (deps.createAiSdkRuntime ?? ((runtimeDeps) => new AiSdkKtxLlmRuntime(runtimeDeps)))({ llmProvider });
 }

package/dist/context/llm/runtime-port.d.ts

@@ -17,6 +17,22 @@ export interface RunLoopStepInfo {
     stepIndex: number;
     stepBudget: number;
 }
+export interface LlmTokenUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+}
+/** Timing and token metrics for a multi-step agent loop, used for ingest profiling. */
+export interface RunLoopMetrics {
+    /** Wall-clock time around the whole `generateText` call, in milliseconds. */
+    totalMs: number;
+    /** Aggregate token usage across all steps. */
+    usage: LlmTokenUsage;
+    /** Number of agent steps (model round-trips) that actually ran. */
+    stepCount: number;
+    /** Wall-clock offset (ms from loop start) at which each step finished. */
+    stepBoundariesMs: number[];
+}
 export interface RunLoopParams {
     modelRole: KtxModelRole;
     systemPrompt: string;
@@ -29,6 +45,7 @@ export interface RunLoopParams {
 export interface RunLoopResult {
     stopReason: RunLoopStopReason;
     error?: Error;
+    metrics?: RunLoopMetrics;
 }
 export interface KtxGenerateTextInput {
     role: KtxModelRole;
@@ -36,6 +53,10 @@ export interface KtxGenerateTextInput {
     system?: string;
     tools?: KtxRuntimeToolSet;
     temperature?: number;
+    onMetrics?: (metrics: {
+        totalMs: number;
+        usage: LlmTokenUsage;
+    }) => void;
 }
 export interface KtxGenerateObjectInput<TOutput, TSchema extends z.ZodType<TOutput>> {
     role: KtxModelRole;
@@ -44,6 +65,10 @@ export interface KtxGenerateObjectInput<TOutput, TSchema extends z.ZodType<TOutp
     tools?: KtxRuntimeToolSet;
     temperature?: number;
     schema: TSchema;
+    onMetrics?: (metrics: {
+        totalMs: number;
+        usage: LlmTokenUsage;
+    }) => void;
 }
 export interface KtxLlmRuntimePort {
     generateText(input: KtxGenerateTextInput): Promise<string>;

package/dist/context/mcp/context-tools.d.ts

@@ -1,11 +1,12 @@
 import type { KtxCliIo } from '../../cli-runtime.js';
-import type { KtxMcpContextPorts, KtxMcpServerLike, KtxMcpToolResult, KtxMcpUserContext, NonArrayObject } from './types.js';
+import type { KtxMcpClientInfo, KtxMcpContextPorts, KtxMcpServerLike, KtxMcpToolResult, KtxMcpUserContext, NonArrayObject } from './types.js';
 export interface RegisterKtxContextToolsDeps {
     server: KtxMcpServerLike;
     ports: KtxMcpContextPorts;
     userContext: KtxMcpUserContext;
     projectDir?: string;
     io?: KtxCliIo;
+    getClientInfo?: () => KtxMcpClientInfo | undefined;
 }
 /** @internal */
 export declare function jsonToolResult<T extends NonArrayObject>(structuredContent: T): KtxMcpToolResult<T>;

package/dist/context/mcp/context-tools.js

@@ -30,7 +30,7 @@ const toolDescriptions = {
     entity_details: 'Read table and column metadata from the latest live-database scan snapshot. Example: entity_details({ connectionId: "warehouse", entities: [{ table: { catalog: null, db: "public", name: "orders" }, columns: ["id"] }] }).',
     dictionary_search: 'Search profile-sampled warehouse values to locate likely source columns for business values. Example: dictionary_search({ values: ["Acme Corp"], connectionId: "warehouse" }).',
     sl_read_source: 'Read a semantic-layer YAML source by connection id and source name. Example: sl_read_source({ connectionId: "warehouse", sourceName: "orders" }).',
-    sl_query: 'Execute a semantic-layer query and return rows, headers, generated SQL, and plan details. Example: sl_query({ connectionId: "warehouse", measures: ["orders.order_count"], dimensions: [{ field: "orders.created_at", granularity: "month" }] }).',
+    sl_query: 'Execute a semantic-layer query and return headers, rows, and total row count, plus correctness notes (e.g. compile-only or fan-out) when relevant. The generated SQL and full query plan are omitted by default; request them with include: ["sql"] and/or include: ["plan"]. Example: sl_query({ connectionId: "warehouse", measures: ["orders.order_count"], dimensions: [{ field: "orders.created_at", granularity: "month" }], include: ["sql"] }).',
     sql_execution: 'Execute one parser-validated read-only SQL query against a configured KTX connection. Example: sql_execution({ connectionId: "warehouse", sql: "select count(*) from public.orders", maxRows: 100 }).',
     memory_ingest: 'Ingest free-form markdown knowledge into durable KTX memory. Use this for business rules, metric definitions, schema gotchas, recurring findings, or explicit user requests to remember something. Example: memory_ingest({ connectionId: "warehouse", content: "ARR is reported in cents in this warehouse." }).',
     memory_ingest_status: 'Read the current or final status for a memory ingest run. Example: memory_ingest_status({ runId: "memory-run-1" }).',
@@ -38,7 +38,7 @@ const toolDescriptions = {
 const connectionListSchema = z.object({});
 const knowledgeSearchSchema = z.object({
     query: z.string().min(1).describe('Natural-language wiki search query, e.g. "revenue recognition policy".'),
-    limit: z.number().int().min(1).max(50).default(10).describe('Maximum wiki pages to return. Defaults to 10.'),
+    limit: z.number().int().min(1).max(50).default(10).describe('Maximum wiki pages to return.'),
 });
 const knowledgeReadSchema = z.object({
     key: z.string().min(1).describe('Wiki page key returned by wiki_search, e.g. "global/revenue".'),
@@ -67,10 +67,7 @@ const slQueryOrderBySchema = z.object({
         .string()
         .min(1)
         .describe('Field/measure/dimension id to order by, e.g. "orders.created_at", a dimension key like "mart_nrr_quarterly.quarter_label", or a measure alias.'),
-    direction: z
-        .enum(['asc', 'desc'])
-        .default('asc')
-        .describe('Sort direction: "asc" or "desc". Defaults to "asc".'),
+    direction: z.enum(['asc', 'desc']).default('asc').describe('Sort direction for this field.'),
 });
 const slQuerySchema = z.object({
     connectionId: connectionIdSchema
@@ -93,8 +90,12 @@ const slQuerySchema = z.object({
         .array(slQueryOrderBySchema)
         .default([])
         .describe('Sort clauses. Use {field, direction?} entries.'),
-    limit: z.number().int().min(0).default(1000).describe('Maximum rows to return. Defaults to 1000.'),
-    include_empty: z.boolean().default(true).describe('Whether to include empty dimension groups. Defaults to true.'),
+    limit: z.number().int().min(0).default(1000).describe('Maximum rows to return.'),
+    include_empty: z.boolean().default(true).describe('Whether to include empty dimension groups.'),
+    include: z
+        .array(z.enum(['plan', 'sql']))
+        .default([])
+        .describe('Extra detail to attach to the response: "sql" for the generated SQL, "plan" for the full query plan.'),
 });
 const entityDetailsTableRefSchema = z.object({
     catalog: z.string().nullable().describe('Catalog/project/database. Use null when not applicable.'),
@@ -134,12 +135,12 @@ const discoverDataSchema = z.object({
         .optional()
         .describe('Optional connection id. Pass it when user intent pins a specific warehouse.'),
     kinds: z.array(discoverDataKindSchema.describe('Reference kind to include.')).optional().describe('Optional kind filter.'),
-    limit: z.number().int().min(1).max(50).default(15).optional().describe('Maximum refs to return. Defaults to 15.'),
+    limit: z.number().int().min(1).max(50).default(10).optional().describe('Maximum refs to return.'),
 });
 const sqlExecutionSchema = z.object({
     connectionId: connectionIdSchema.describe('Connection id to execute against. Required for raw SQL.'),
     sql: z.string().min(1).describe('Parser-validated read-only SQL, e.g. "select count(*) from public.orders".'),
-    maxRows: z.number().int().min(1).max(10_000).default(1000).optional().describe('Maximum rows to return. Defaults to 1000.'),
+    maxRows: z.number().int().min(1).max(10_000).default(1000).optional().describe('Maximum rows to return.'),
 });
 const memoryIngestSchema = z.object({
     content: z
@@ -198,10 +199,14 @@ const slReadSourceOutputSchema = z.object({
 const slQueryOutputSchema = z.object({
     connectionId: z.string().optional(),
     dialect: z.string().optional(),
-    sql: z.string(),
     headers: z.array(z.string()),
     rows: z.array(z.array(z.unknown())),
     totalRows: z.number(),
+    // Correctness signals hoisted out of `plan` so they survive default projection (e.g. compile-only
+    // status, fan-out warnings). Present only when there is something to report.
+    notes: z.array(z.string()).optional(),
+    // Opt-in detail, attached only when requested via the `include` input.
+    sql: z.string().optional(),
     plan: unknownRecordSchema.optional(),
 });
 const entityDetailsSnapshotOutputSchema = z.object({
@@ -321,11 +326,54 @@ const memoryIngestStatusOutputSchema = z.object({
 });
 /** @internal */
 export function jsonToolResult(structuredContent) {
+    // Compact (non-indented) JSON: this `content` text is the copy the model reads. Pretty-printing
+    // arrays-of-arrays (every `rows` payload) puts one scalar per line, inflating tabular results by
+    // a large constant factor. `structuredContent` carries the same data for structured-output clients.
     return {
-        content: [{ type: 'text', text: JSON.stringify(structuredContent, null, 2) }],
+        content: [{ type: 'text', text: JSON.stringify(structuredContent) }],
         structuredContent,
     };
 }
+/**
+ * Pull the correctness-critical signals out of a query plan so they survive even when the caller
+ * did not opt into the full `plan`. Returns an empty list when there is nothing to flag.
+ */
+function slQueryNotes(plan) {
+    if (!plan) {
+        return [];
+    }
+    const notes = [];
+    const execution = plan.execution;
+    if (execution &&
+        typeof execution === 'object' &&
+        execution.mode === 'compile_only') {
+        const reason = execution.reason;
+        notes.push(typeof reason === 'string' ? reason : 'Compiled SQL only; no rows were executed.');
+    }
+    if (plan.has_fan_out === true) {
+        const description = typeof plan.fan_out_description === 'string' ? plan.fan_out_description.trim() : '';
+        notes.push(description.length > 0 ? description : 'Fan-out detected: measure totals may be inflated by joins.');
+    }
+    return notes;
+}
+/**
+ * Default sl_query response is the minimum the agent needs to read the result: connection, headers,
+ * rows, totals, plus any correctness notes. The generated `sql` and the full `plan` are attached only
+ * when explicitly requested via `include`, since both are large and echo information the caller already has.
+ */
+function projectSlQueryResult(result, include) {
+    const notes = slQueryNotes(result.plan);
+    return {
+        ...(result.connectionId !== undefined ? { connectionId: result.connectionId } : {}),
+        ...(result.dialect !== undefined ? { dialect: result.dialect } : {}),
+        headers: result.headers,
+        rows: result.rows,
+        totalRows: result.totalRows,
+        ...(notes.length > 0 ? { notes } : {}),
+        ...(include.includes('sql') ? { sql: result.sql } : {}),
+        ...(include.includes('plan') && result.plan ? { plan: result.plan } : {}),
+    };
+}
 function jsonErrorToolResult(text) {
     return {
         content: [{ type: 'text', text }],
@@ -367,6 +415,18 @@ function registerParsedTool(server, name, config, schema, handler) {
         }
     });
 }
+/**
+ * Resolves the connected client's identity into the raw telemetry fields. The
+ * strings are client-controlled and untrusted, so they only ever land in the
+ * telemetry property bag — never in paths, logs, or error messages.
+ */
+function clientTelemetryFields(getClientInfo) {
+    const client = getClientInfo?.();
+    return {
+        ...(client?.name ? { mcpClientName: client.name } : {}),
+        ...(client?.version ? { mcpClientVersion: client.version } : {}),
+    };
+}
 function instrumentMcpServer(server, telemetry) {
     return {
         registerTool(name, config, handler) {
@@ -385,6 +445,7 @@ function instrumentMcpServer(server, telemetry) {
                                 outcome: isError ? 'error' : 'ok',
                                 durationMs: Math.max(0, performance.now() - startedAt),
                                 sampleRate: mcpTelemetrySampleRate(),
+                                ...clientTelemetryFields(telemetry.getClientInfo),
                             },
                         });
                     }
@@ -403,6 +464,7 @@ function instrumentMcpServer(server, telemetry) {
                                 ...(errorClass ? { errorClass } : {}),
                                 durationMs: Math.max(0, performance.now() - startedAt),
                                 sampleRate: mcpTelemetrySampleRate(),
+                                ...clientTelemetryFields(telemetry.getClientInfo),
                             },
                         });
                     }
@@ -414,7 +476,11 @@ function instrumentMcpServer(server, telemetry) {
 }
 export function registerKtxContextTools(deps) {
     const { ports, userContext } = deps;
-    const server = instrumentMcpServer(deps.server, { projectDir: deps.projectDir, io: deps.io });
+    const server = instrumentMcpServer(deps.server, {
+        projectDir: deps.projectDir,
+        io: deps.io,
+        getClientInfo: deps.getClientInfo,
+    });
     if (ports.connections) {
         const connections = ports.connections;
         registerParsedTool(server, 'connection_list', {
@@ -471,7 +537,7 @@ export function registerKtxContextTools(deps) {
             annotations: toolAnnotations.sl_query,
         }, slQuerySchema, async (input, context) => {
             const onProgress = mcpProgressCallback(context);
-            return jsonToolResult(await semanticLayer.query({
+            const result = await semanticLayer.query({
                 connectionId: input.connectionId,
                 query: {
                     measures: input.measures,
@@ -482,7 +548,8 @@ export function registerKtxContextTools(deps) {
                     limit: input.limit,
                     include_empty: input.include_empty,
                 },
-            }, onProgress ? { onProgress } : undefined));
+            }, onProgress ? { onProgress } : undefined);
+            return jsonToolResult(projectSlQueryResult(result, input.include));
         });
     }
     if (ports.entityDetails) {

package/dist/context/mcp/server.js

@@ -9,6 +9,7 @@ export function createKtxMcpServer(deps) {
             userContext: deps.userContext,
             projectDir: deps.projectDir,
             io: deps.io,
+            getClientInfo: deps.getClientInfo,
         });
     }
     return deps.server;
@@ -24,6 +25,9 @@ export function createDefaultKtxMcpServer(deps) {
         contextTools: deps.contextTools,
         projectDir: deps.projectDir,
         io: deps.io,
+        // The SDK populates the client identity after the initialize handshake, so
+        // read it lazily at emit time rather than at registration (undefined here).
+        getClientInfo: () => server.server.getClientVersion(),
     });
     return server;
 }

package/dist/context/mcp/types.d.ts

@@ -46,6 +46,15 @@ export interface MemoryIngestPort {
 export interface KtxMcpUserContext {
     userId: string;
 }
+/**
+ * Identity of the connected MCP client tool (e.g. Claude Desktop, Cursor),
+ * read from the initialize handshake. Untrusted, client-controlled strings —
+ * use only as telemetry properties, never to build paths or log lines.
+ */
+export interface KtxMcpClientInfo {
+    name: string;
+    version: string;
+}
 export interface KtxMcpServerLike {
     registerTool(name: string, config: {
         title?: string;
@@ -101,7 +110,10 @@ interface KtxSemanticLayerReadResponse {
     sourceName: string;
     yaml: string;
 }
-interface KtxSemanticLayerQueryResponse {
+/** @internal */
+export interface KtxSemanticLayerQueryResponse {
+    connectionId?: string;
+    dialect?: string;
     sql: string;
     headers: string[];
     rows: unknown[][];
@@ -165,5 +177,7 @@ export interface KtxMcpServerDeps {
     contextTools?: KtxMcpContextPorts;
     projectDir?: string;
     io?: KtxCliIo;
+    /** Reads the connected client's identity once the initialize handshake completes. */
+    getClientInfo?: () => KtxMcpClientInfo | undefined;
 }
 export {};

package/dist/context/project/config.d.ts

@@ -6,6 +6,7 @@ declare const llmSchema: z.ZodObject<{
             vertex: "vertex";
             gateway: "gateway";
             "claude-code": "claude-code";
+            codex: "codex";
             none: "none";
         }>>;
         vertex: z.ZodOptional<z.ZodObject<{
@@ -327,6 +328,7 @@ declare const ktxProjectConfigSchema: z.ZodObject<{
                 vertex: "vertex";
                 gateway: "gateway";
                 "claude-code": "claude-code";
+                codex: "codex";
                 none: "none";
             }>>;
             vertex: z.ZodOptional<z.ZodObject<{
@@ -395,6 +397,7 @@ declare const ktxProjectConfigSchema: z.ZodObject<{
                 continue: "continue";
             }>>;
         }, z.core.$strict>>;
+        profile: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"json">]>>;
     }, z.core.$strict>>;
     agent: z.ZodPrefault<z.ZodObject<{
         run_research: z.ZodPrefault<z.ZodObject<{

package/dist/context/project/config.js

@@ -2,7 +2,7 @@ import { KTX_MODEL_ROLES } from '../../llm/types.js';
 import YAML from 'yaml';
 import * as z from 'zod';
 import { connectionConfigSchema } from './driver-schemas.js';
-const KTX_LLM_BACKENDS = ['none', 'anthropic', 'vertex', 'gateway', 'claude-code'];
+const KTX_LLM_BACKENDS = ['none', 'anthropic', 'vertex', 'gateway', 'claude-code', 'codex'];
 const KTX_EMBEDDING_BACKENDS = ['none', 'openai', 'sentence-transformers'];
 const KTX_PROMPT_CACHE_TTLS = ['5m', '1h'];
 const KTX_ENRICHMENT_MODES = ['none', 'deterministic', 'llm'];
@@ -32,7 +32,7 @@ const llmProviderSchema = z
     backend: z
         .enum(KTX_LLM_BACKENDS)
         .default('none')
-        .describe('LLM provider backend. "none" disables LLM features; "anthropic" / "vertex" / "gateway" require the matching nested credentials block; "claude-code" uses the local Claude Code session.'),
+        .describe('LLM provider backend. "none" disables LLM features; "anthropic" / "vertex" / "gateway" require the matching nested credentials block; "claude-code" uses the local Claude Code session; "codex" uses the local Codex session.'),
     vertex: vertexProviderSchema.optional().describe('Vertex AI credentials, used when backend is "vertex".'),
     anthropic: apiCredentialsSchema.optional().describe('Anthropic API credentials, used when backend is "anthropic".'),
     gateway: apiCredentialsSchema.optional().describe('AI Gateway credentials, used when backend is "gateway".'),
@@ -96,6 +96,10 @@ const ingestSchema = z
         .prefault({ backend: 'none' })
         .describe('Embedding configuration used when ingest adapters need to embed documents.'),
     workUnits: workUnitsSchema.prefault({}).describe('Concurrency and failure handling for ingest work units.'),
+    profile: z
+        .union([z.boolean(), z.literal('json')])
+        .default(false)
+        .describe('Print a timing breakdown to stderr at the end of each ingest run. `true` prints a human table; `"json"` prints the raw structured profile for coding agents; `false` disables it. Equivalent to the KTX_PROFILE_INGEST environment variable (`1`/`true`/`json`).'),
 })
     .describe('Ingest pipeline configuration: adapters, embeddings, and work-unit policy.');
 const scanEnrichmentSchema = z

package/dist/context/project/driver-schemas.js

@@ -21,7 +21,7 @@ function warehouseConnectionSchema(driver) {
         enabled_tables: z
             .array(z.string().min(1))
             .optional()
-            .describe('Optional allowlist of fully-qualified table names ("schema.table") to ingest. When set, live-database ingest discards any table whose schema-qualified name is not in this list. Useful for smoke-testing deep ingest on a single table.'),
+            .describe('Optional allowlist of fully-qualified table names ("schema.table") to ingest. When set, live-database ingest discards any table whose schema-qualified name is not in this list. Useful for smoke-testing ingest on a single table.'),
     })
         .describe(`${driver} warehouse connection. Additional driver-tunable fields (e.g. context.queryHistory) are accepted and passed through.`);
 }

package/dist/context/search/discover.js

@@ -95,7 +95,7 @@ async function wikiCandidates(project, input, options, terms) {
         query: input.query,
         userId: options.userId,
         embeddingService: options.embeddingService ?? null,
-        limit: Math.max(input.limit ?? 15, 25),
+        limit: Math.max(input.limit ?? 10, 25),
     });
     const records = [];
     for (const result of searchResults) {
@@ -300,7 +300,8 @@ function hydrate(fused, refsByKey) {
         }
         return {
             ...ref,
-            score: maxScore > 0 ? Number((candidate.score / maxScore).toFixed(6)) : 0,
+            // 3 decimals is plenty for a relative-rank hint; 6 just spent bytes on noise.
+            score: maxScore > 0 ? Number((candidate.score / maxScore).toFixed(3)) : 0,
         };
     })
         .filter((result) => result !== null);
@@ -308,7 +309,7 @@ function hydrate(fused, refsByKey) {
 export function createKtxDiscoverDataService(project, options = {}) {
     return {
         async search(input) {
-            const limit = Math.max(1, Math.min(input.limit ?? 15, 50));
+            const limit = Math.max(1, Math.min(input.limit ?? 10, 50));
             const query = input.query.trim();
             if (!query) {
                 return [];

package/dist/context/sl/local-sl.d.ts

@@ -28,6 +28,7 @@ export interface LocalSlSearchInput {
     backend?: 'pglite-owner-prototype';
     pglite?: PgliteSlSearchPrototypeOwnerOptions;
 }
+/** @internal */
 export interface LocalSlSource extends LocalSlSourceSummary {
     yaml: string;
 }
@@ -38,6 +39,15 @@ export interface LocalSlValidationResult {
     valid: boolean;
     errors: string[];
 }
+export type ResolvedSlSource = {
+    kind: 'found';
+    source: LocalSlSource;
+} | {
+    kind: 'not-found';
+} | {
+    kind: 'ambiguous';
+    connectionIds: string[];
+};
 export declare function loadLocalSlSourceRecords(project: KtxLocalProject, input: {
     connectionId: string;
 }): Promise<LocalSlSourceRecord[]>;
@@ -52,10 +62,15 @@ export declare function writeLocalSlSource(project: KtxLocalProject, input: {
     sourceName: string;
     yaml: string;
 }): Promise<KtxFileWriteResult>;
+/** @internal */
 export declare function readLocalSlSource(project: KtxLocalProject, input: {
     connectionId: string;
     sourceName: string;
 }): Promise<LocalSlSource | null>;
+export declare function resolveLocalSlSource(project: KtxLocalProject, input: {
+    sourceName: string;
+    connectionId?: string;
+}): Promise<ResolvedSlSource>;
 export declare function listLocalSlSources(project: KtxLocalProject, input?: {
     connectionId?: string;
 }): Promise<LocalSlSourceSummary[]>;

package/dist/context/sl/local-sl.js

@@ -204,6 +204,7 @@ export async function writeLocalSlSource(project, input) {
     const path = slPath(input.connectionId, input.sourceName);
     return project.fileStore.writeFile(path, input.yaml.endsWith('\n') ? input.yaml : `${input.yaml}\n`, LOCAL_AUTHOR, LOCAL_AUTHOR_EMAIL, `Write semantic-layer source: ${input.connectionId}/${input.sourceName}`);
 }
+/** @internal */
 export async function readLocalSlSource(project, input) {
     const path = slPath(input.connectionId, input.sourceName);
     try {
@@ -221,6 +222,35 @@ export async function readLocalSlSource(project, input) {
         return record ? { ...record } : null;
     }
 }
+export async function resolveLocalSlSource(project, input) {
+    if (input.connectionId !== undefined) {
+        const source = await readLocalSlSource(project, {
+            connectionId: input.connectionId,
+            sourceName: input.sourceName,
+        });
+        return source ? { kind: 'found', source } : { kind: 'not-found' };
+    }
+    const summaries = await listLocalSlSources(project, {});
+    const matches = summaries.filter((summary) => summary.name === input.sourceName);
+    if (matches.length === 0) {
+        return { kind: 'not-found' };
+    }
+    if (matches.length > 1) {
+        return {
+            kind: 'ambiguous',
+            connectionIds: [...new Set(matches.map((match) => match.connectionId))].sort(),
+        };
+    }
+    const match = matches[0];
+    if (match === undefined) {
+        return { kind: 'not-found' };
+    }
+    const source = await readLocalSlSource(project, {
+        connectionId: match.connectionId,
+        sourceName: input.sourceName,
+    });
+    return source ? { kind: 'found', source } : { kind: 'not-found' };
+}
 export async function listLocalSlSources(project, input = {}) {
     if (input.connectionId) {
         return (await loadLocalSlSourceRecords(project, { connectionId: input.connectionId })).map(({ source: _source, yaml: _yaml, ...summary }) => summary);