@kaelio/ktx 0.7.0 → 0.8.0

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

@@ -7,6 +7,7 @@ import { KtxYamlMetabaseSourceStateReader, LocalMetabaseDiscoveryCache } from '.
 import { localPullConfigForAdapter } from './local-adapters.js';
 import { createLocalBundleIngestRuntime } from './local-bundle-runtime.js';
 import { buildSyncId } from './raw-sources-paths.js';
+import { ingestReportOutcome } from './reports.js';
 import { SqliteBundleIngestStore } from './sqlite-bundle-ingest-store.js';
 class LocalIngestPhase {
     async updateProgress() { }
@@ -117,11 +118,11 @@ export async function runLocalIngest(options) {
     return { result, report };
 }
 function metabaseFanoutStatus(children) {
-    const succeeded = children.filter((child) => child.report.body.failedWorkUnits.length === 0).length;
-    if (succeeded === children.length) {
+    const outcomes = children.map((child) => ingestReportOutcome(child.report));
+    if (outcomes.every((outcome) => outcome === 'done')) {
         return 'all_succeeded';
     }
-    if (succeeded === 0) {
+    if (outcomes.every((outcome) => outcome === 'error')) {
         return 'all_failed';
     }
     return 'partial_failure';
@@ -266,12 +267,13 @@ export async function runLocalMetabaseIngest(options) {
                 error,
             });
         }
+        const childOutcome = ingestReportOutcome(child.report);
         options.progress?.onMetabaseChildCompleted?.({
             metabaseConnectionId,
             metabaseDatabaseId: childPlan.metabaseDatabaseId,
             targetConnectionId,
             jobId: child.report.jobId,
-            status: child.report.body.failedWorkUnits.length > 0 ? 'failed' : 'done',
+            status: childOutcome === 'error' ? 'failed' : childOutcome,
         });
         children.push({
             jobId: child.report.jobId,

package/dist/context/ingest/memory-flow/events.js

@@ -1,3 +1,4 @@
+import { ingestReportOutcome } from '../reports.js';
 function plannedWorkUnitFromLocal(workUnit) {
     return {
         unitKey: workUnit.unitKey,
@@ -39,7 +40,7 @@ function fullModeMetadata(input) {
     };
 }
 function reportStatus(report) {
-    return report.body.failedWorkUnits.length > 0 ? 'error' : 'done';
+    return ingestReportOutcome(report) === 'error' ? 'error' : 'done';
 }
 function reportCreatedEvent(report) {
     return { type: 'report_created', runId: report.runId, reportPath: report.id };

package/dist/context/ingest/ports.d.ts

@@ -111,6 +111,8 @@ interface IngestSettingsPort {
     workUnitMaxConcurrency?: number;
     workUnitStepBudget?: number;
     workUnitFailureMode?: 'abort' | 'continue';
+    /** Print a timing breakdown to stderr at the end of each run (config-driven; see also KTX_PROFILE_INGEST). `'json'` emits the raw structured profile. */
+    profileIngest?: boolean | 'json';
     ingestTraceLevel?: IngestTraceLevel;
 }
 interface IngestGitAuthor {

package/dist/context/ingest/reports.d.ts

@@ -116,5 +116,8 @@ export interface IngestSavedMemoryCounts {
     slCount: number;
 }
 export declare function savedMemoryCountsForReport(report: IngestReportSnapshot): IngestSavedMemoryCounts;
+/** @internal */
+export type IngestReportOutcome = 'done' | 'partial' | 'error';
+export declare function ingestReportOutcome(report: IngestReportSnapshot): IngestReportOutcome;
 export declare function buildStageIndexFromReportBody(jobId: string, connectionId: string, body: IngestReportBody): StageIndex;
 export {};

package/dist/context/ingest/reports.js

@@ -8,6 +8,16 @@ export function savedMemoryCountsForReport(report) {
         slCount: actions.filter((action) => action.target === 'sl').length,
     };
 }
+export function ingestReportOutcome(report) {
+    if (report.body.status === 'failed') {
+        return 'error';
+    }
+    if (report.body.failedWorkUnits.length === 0) {
+        return 'done';
+    }
+    const { wikiCount, slCount } = savedMemoryCountsForReport(report);
+    return wikiCount + slCount > 0 ? 'partial' : 'error';
+}
 export function buildStageIndexFromReportBody(jobId, connectionId, body) {
     return {
         jobId,

package/dist/context/ingest/stages/stage-3-work-units.d.ts

@@ -1,5 +1,5 @@
 import type { KtxModelRole } from '../../../llm/types.js';
-import type { AgentRunnerPort, KtxRuntimeToolSet } from '../../../context/llm/runtime-port.js';
+import type { AgentRunnerPort, KtxRuntimeToolSet, RunLoopMetrics } from '../../../context/llm/runtime-port.js';
 import type { CaptureSession, MemoryAction } from '../../../context/memory/types.js';
 import { type TouchedSlSource } from '../../../context/tools/touched-sl-sources.js';
 import type { WorkUnit } from '../types.js';
@@ -44,6 +44,8 @@ export interface WorkUnitOutcome {
     patchPath?: string;
     patchTouchedPaths?: string[];
     childWorktreePath?: string;
+    /** Timing and token metrics for the work-unit agent loop, used for ingest profiling. */
+    metrics?: RunLoopMetrics;
 }
 export declare function executeWorkUnit(deps: WorkUnitExecutionDeps, wu: WorkUnit): Promise<WorkUnitOutcome>;
 export {};

package/dist/context/ingest/stages/stage-3-work-units.js

@@ -72,6 +72,7 @@ export async function executeWorkUnit(deps, wu) {
             touchedSlSources: [],
             slDisallowed: wu.slDisallowed,
             slDisallowedReason: wu.slDisallowedReason,
+            ...(runResult.metrics ? { metrics: runResult.metrics } : {}),
         };
     };
     if (runResult.stopReason === 'error') {
@@ -104,5 +105,6 @@ export async function executeWorkUnit(deps, wu) {
         touchedSlSources: touched,
         slDisallowed: wu.slDisallowed,
         slDisallowedReason: wu.slDisallowedReason,
+        ...(runResult.metrics ? { metrics: runResult.metrics } : {}),
     };
 }

package/dist/context/ingest/stages/stage-4-reconciliation.d.ts

@@ -1,4 +1,4 @@
-import type { AgentRunnerPort, KtxRuntimeToolSet } from '../../../context/llm/runtime-port.js';
+import type { AgentRunnerPort, KtxRuntimeToolSet, RunLoopMetrics } from '../../../context/llm/runtime-port.js';
 import type { KtxModelRole } from '../../../llm/types.js';
 import type { EvictionUnit } from '../types.js';
 import type { StageIndex } from './stage-index.types.js';
@@ -24,5 +24,6 @@ export interface ReconciliationOutcome {
     skipped: boolean;
     stopReason?: 'budget' | 'natural' | 'error';
     error?: Error;
+    metrics?: RunLoopMetrics;
 }
 export declare function runReconciliationStage4(ctx: ReconciliationContext): Promise<ReconciliationOutcome>;

package/dist/context/ingest/stages/stage-4-reconciliation.js

@@ -13,5 +13,5 @@ export async function runReconciliationStage4(ctx) {
         telemetryTags: { operationName: 'ingest-bundle-reconcile', source: ctx.sourceKey, jobId: ctx.jobId },
         onStepFinish: ctx.onStepFinish,
     });
-    return { skipped: false, stopReason: run.stopReason, error: run.error };
+    return { skipped: false, stopReason: run.stopReason, error: run.error, ...(run.metrics ? { metrics: run.metrics } : {}) };
 }

package/dist/context/ingest/tools/tool-call-logger.d.ts

@@ -30,4 +30,10 @@ interface ToolCallLoggerOptions {
  * effectively single-writer and lines land in call order.
  */
 export declare function wrapToolsWithLogger<T extends KtxRuntimeToolSet>(tools: T, logFilePath: string, wuKey: string, options?: ToolCallLoggerOptions): T;
+/**
+ * Await all in-flight tool-call log writes (best-effort, bounded by `timeoutMs`
+ * so it can never hang a caller). Lets readers such as the ingest profiler see
+ * complete transcripts despite the fire-and-forget append design.
+ */
+export declare function flushToolCallLogs(timeoutMs?: number): Promise<void>;
 export {};

package/dist/context/ingest/tools/tool-call-logger.js

@@ -59,8 +59,12 @@ export function wrapToolsWithLogger(tools, logFilePath, wuKey, options = {}) {
     }
     return wrapped;
 }
+// Fire-and-forget appends are intentional (the agent hot path must never block
+// or fail on logging), but readers like the ingest profiler need to know when
+// the writes have settled. Track in-flight appends so a consumer can flush.
+const pendingWrites = new Set();
 function appendEntry(path, entry) {
-    void (async () => {
+    const write = (async () => {
         try {
             await mkdir(dirname(path), { recursive: true });
             await appendFile(path, `${safeStringify(entry)}\n`, 'utf-8');
@@ -69,6 +73,37 @@ function appendEntry(path, entry) {
             // best-effort
         }
     })();
+    pendingWrites.add(write);
+    void write.finally(() => pendingWrites.delete(write));
+}
+/**
+ * Await all in-flight tool-call log writes (best-effort, bounded by `timeoutMs`
+ * so it can never hang a caller). Lets readers such as the ingest profiler see
+ * complete transcripts despite the fire-and-forget append design.
+ */
+export async function flushToolCallLogs(timeoutMs = 5000) {
+    const pending = [...pendingWrites];
+    if (pending.length === 0) {
+        return;
+    }
+    const settled = Promise.allSettled(pending).then(() => undefined);
+    if (timeoutMs <= 0) {
+        await settled;
+        return;
+    }
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(resolve, timeoutMs);
+        timer.unref?.();
+    });
+    try {
+        await Promise.race([settled, timeout]);
+    }
+    finally {
+        if (timer) {
+            clearTimeout(timer);
+        }
+    }
 }
 function safeStringify(v) {
     try {

package/dist/context/llm/ai-sdk-runtime.js

@@ -3,6 +3,16 @@ import { generateText, Output, stepCountIs } from 'ai';
 import { noopLogger } from '../../context/core/config.js';
 import { summarizeKtxLlmDebugRequest } from './debug-request-recorder.js';
 import { createAiSdkToolSet } from './runtime-tools.js';
+function toLlmTokenUsage(usage) {
+    if (!usage) {
+        return {};
+    }
+    return {
+        ...(usage.inputTokens !== undefined ? { inputTokens: usage.inputTokens } : {}),
+        ...(usage.outputTokens !== undefined ? { outputTokens: usage.outputTokens } : {}),
+        ...(usage.totalTokens !== undefined ? { totalTokens: usage.totalTokens } : {}),
+    };
+}
 function hasTools(tools) {
     return Object.keys(tools).length > 0;
 }
@@ -26,6 +36,7 @@ export class AiSdkKtxLlmRuntime {
             model,
         });
         const split = splitKtxSystemMessages(built.messages);
+        const startedAt = Date.now();
         const result = await generateText({
             model,
             temperature: input.temperature ?? 0,
@@ -40,6 +51,7 @@ export class AiSdkKtxLlmRuntime {
                 }
                 : {}),
         });
+        input.onMetrics?.({ totalMs: Date.now() - startedAt, usage: toLlmTokenUsage(result.totalUsage ?? result.usage) });
         if (typeof result.text !== 'string') {
             throw new Error('KTX LLM text generation returned no text');
         }
@@ -55,6 +67,7 @@ export class AiSdkKtxLlmRuntime {
             model,
         });
         const split = splitKtxSystemMessages(built.messages);
+        const startedAt = Date.now();
         const result = await generateText({
             model,
             temperature: input.temperature ?? 0,
@@ -70,6 +83,7 @@ export class AiSdkKtxLlmRuntime {
                 : {}),
             output: Output.object({ schema: input.schema }),
         });
+        input.onMetrics?.({ totalMs: Date.now() - startedAt, usage: toLlmTokenUsage(result.totalUsage ?? result.usage) });
         if (result.output == null) {
             throw new Error('KTX LLM object generation returned no output');
         }
@@ -77,6 +91,8 @@ export class AiSdkKtxLlmRuntime {
     }
     async runAgentLoop(params) {
         let stepIndex = 0;
+        const startedAt = Date.now();
+        const stepBoundariesMs = [];
         try {
             const model = this.deps.llmProvider.getModel(params.modelRole);
             const tools = createAiSdkToolSet(params.toolSet);
@@ -98,7 +114,7 @@ export class AiSdkKtxLlmRuntime {
                 messages: built.messages,
                 tools: built.tools,
             }));
-            await generateText({
+            const result = await generateText({
                 model,
                 temperature: 0,
                 stopWhen: stepCountIs(params.stepBudget),
@@ -111,6 +127,7 @@ export class AiSdkKtxLlmRuntime {
                 tools: built.tools,
                 onStepFinish: async () => {
                     stepIndex += 1;
+                    stepBoundariesMs.push(Date.now() - startedAt);
                     if (!params.onStepFinish) {
                         return;
                     }
@@ -122,12 +139,24 @@ export class AiSdkKtxLlmRuntime {
                     }
                 },
             });
-            return { stopReason: 'natural' };
+            return {
+                stopReason: 'natural',
+                metrics: {
+                    totalMs: Date.now() - startedAt,
+                    stepCount: stepIndex,
+                    stepBoundariesMs,
+                    usage: toLlmTokenUsage(result.totalUsage ?? result.usage),
+                },
+            };
         }
         catch (error) {
             const err = error instanceof Error ? error : new Error(String(error));
             this.logger.warn(`[agent-runner] loop failed: ${err.message}`);
-            return { stopReason: 'error', error: err };
+            return {
+                stopReason: 'error',
+                error: err,
+                metrics: { totalMs: Date.now() - startedAt, stepCount: stepIndex, stepBoundariesMs, usage: {} },
+            };
         }
     }
 }

package/dist/context/llm/claude-code-runtime.js

@@ -4,6 +4,19 @@ import { noopLogger } from '../../context/core/config.js';
 import { createKtxClaudeCodeEnv } from './claude-code-env.js';
 import { resolveClaudeCodeModel } from './claude-code-models.js';
 import { createClaudeSdkTools, mcpToolIds } from './runtime-tools.js';
+function claudeTokenUsage(result) {
+    const usage = result.usage;
+    if (!usage) {
+        return {};
+    }
+    const { input_tokens: inputTokens, output_tokens: outputTokens } = usage;
+    const totalTokens = inputTokens !== undefined && outputTokens !== undefined ? inputTokens + outputTokens : undefined;
+    return {
+        ...(inputTokens !== undefined ? { inputTokens } : {}),
+        ...(outputTokens !== undefined ? { outputTokens } : {}),
+        ...(totalTokens !== undefined ? { totalTokens } : {}),
+    };
+}
 const BUILTIN_TOOLS = [
     'Agent',
     'Task',
@@ -168,6 +181,7 @@ export class ClaudeCodeKtxLlmRuntime {
             maxTurns: 1,
             tools: input.tools,
         });
+        const startedAt = Date.now();
         const result = await collectResult({
             query: this.runQuery,
             prompt: [input.system, input.prompt].filter(Boolean).join('\n\n'),
@@ -175,6 +189,7 @@ export class ClaudeCodeKtxLlmRuntime {
             allowedToolIds: new Set(mcpToolIds(input.tools ?? {})),
             expectedMcpServerNames: expectedMcpServerNames(input.tools),
         });
+        input.onMetrics?.({ totalMs: Date.now() - startedAt, usage: claudeTokenUsage(result) });
         const error = resultError(result);
         if (error) {
             throw error;
@@ -200,6 +215,7 @@ export class ClaudeCodeKtxLlmRuntime {
             }),
             outputFormat: { type: 'json_schema', schema: jsonSchema(input.schema) },
         };
+        const startedAt = Date.now();
         const result = await collectResult({
             query: this.runQuery,
             prompt: [input.system, input.prompt].filter(Boolean).join('\n\n'),
@@ -207,6 +223,7 @@ export class ClaudeCodeKtxLlmRuntime {
             allowedToolIds: new Set([...mcpToolIds(input.tools ?? {}), STRUCTURED_OUTPUT_TOOL_NAME]),
             expectedMcpServerNames: expectedMcpServerNames(input.tools),
         });
+        input.onMetrics?.({ totalMs: Date.now() - startedAt, usage: claudeTokenUsage(result) });
         const error = resultError(result);
         if (error) {
             throw error;
@@ -218,6 +235,8 @@ export class ClaudeCodeKtxLlmRuntime {
     }
     async runAgentLoop(params) {
         let stepIndex = 0;
+        const startedAt = Date.now();
+        const stepBoundariesMs = [];
         try {
             const options = baseOptions({
                 projectDir: this.deps.projectDir,
@@ -234,6 +253,7 @@ export class ClaudeCodeKtxLlmRuntime {
                 expectedMcpServerNames: expectedMcpServerNames(params.toolSet),
                 onAssistantTurn: async () => {
                     stepIndex += 1;
+                    stepBoundariesMs.push(Date.now() - startedAt);
                     if (!params.onStepFinish) {
                         return;
                     }
@@ -247,11 +267,24 @@ export class ClaudeCodeKtxLlmRuntime {
             });
             const stopReason = mapClaudeCodeStopReason(result);
             const error = resultError(result);
-            return { stopReason, ...(stopReason === 'error' && error ? { error } : {}) };
+            return {
+                stopReason,
+                ...(stopReason === 'error' && error ? { error } : {}),
+                metrics: {
+                    totalMs: Date.now() - startedAt,
+                    stepCount: stepIndex,
+                    stepBoundariesMs,
+                    usage: claudeTokenUsage(result),
+                },
+            };
         }
         catch (error) {
             const err = error instanceof Error ? error : new Error(String(error));
-            return { stopReason: 'error', error: err };
+            return {
+                stopReason: 'error',
+                error: err,
+                metrics: { totalMs: Date.now() - startedAt, stepCount: stepIndex, stepBoundariesMs, usage: {} },
+            };
         }
     }
 }

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) {