@kaelio/ktx 0.13.1 → 0.15.0

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

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { type CodexRuntimeMcpServerHandle } from './codex-mcp-runtime-server.js';
 import { type CodexSdkRunner } from './codex-sdk-runner.js';
 import type { RateLimitGovernor } from './rate-limit-governor.js';
-import type { KtxGenerateObjectInput, KtxGenerateTextInput, KtxLlmRuntimePort, KtxRuntimeToolSet, RunLoopParams, RunLoopResult } from './runtime-port.js';
+import type { KtxGenerateObjectInput, KtxGenerateStructuredJsonInput, KtxGenerateTextInput, KtxLlmRuntimePort, KtxRuntimeToolSet, RunLoopParams, RunLoopResult, SubprocessRuntimeForkSpec } from './runtime-port.js';
 export interface CodexKtxLlmRuntimeDeps {
     projectDir: string;
     modelSlots: {
@@ -21,7 +21,10 @@ export declare class CodexKtxLlmRuntime implements KtxLlmRuntimePort {
     constructor(deps: CodexKtxLlmRuntimeDeps);
     private runWithRateLimitRetry;
     generateText(input: KtxGenerateTextInput): Promise<string>;
+    private streamStructuredText;
     generateObject<TOutput, TSchema extends z.ZodType<TOutput>>(input: KtxGenerateObjectInput<TOutput, TSchema>): Promise<TOutput>;
+    generateStructuredJson(input: KtxGenerateStructuredJsonInput): Promise<unknown>;
+    subprocessForkSpec(): SubprocessRuntimeForkSpec;
     runAgentLoop(params: RunLoopParams): Promise<RunLoopResult>;
 }
 export declare function runCodexAuthProbe(input: {

package/dist/context/llm/codex-runtime.js

@@ -185,48 +185,61 @@ export class CodexKtxLlmRuntime {
             await mcp?.close();
         }
     }
-    async generateObject(input) {
+    // Structured generation has no tools, so it skips the MCP server that
+    // generateText/runAgentLoop need; generateObject and generateStructuredJson
+    // (the kill-boundary child path) share this one streaming implementation.
+    async streamStructuredText(input) {
         const startedAt = Date.now();
         const model = modelForRole(this.deps.modelSlots, input.role);
-        const mcp = await mcpForTools({
-            projectDir: this.deps.projectDir,
-            toolSet: input.tools,
-            startMcpServer: this.deps.startMcpServer,
+        const config = buildCodexRuntimeConfig({ model });
+        const result = await this.runWithRateLimitRetry(input.abortSignal, async () => {
+            const collected = await collectEvents(await this.runner.runStreamed({
+                projectDir: this.deps.projectDir,
+                model,
+                prompt: promptWithSystem(input.system, input.prompt),
+                configOverrides: config.configOverrides,
+                env: config.env,
+                outputSchema: input.jsonSchema,
+                ...(input.abortSignal ? { signal: input.abortSignal } : {}),
+            }));
+            const summary = summarizeCodexExecEvents(collected.events, { startedAt });
+            return { collected, summary };
+        }, ({ collected, summary }) => summaryError(summary, collected.streamError));
+        return {
+            text: assertSuccessfulText(result.summary, result.collected.streamError),
+            summary: result.summary,
+            startedAt,
+        };
+    }
+    async generateObject(input) {
+        const { text, summary, startedAt } = await this.streamStructuredText({
+            role: input.role,
+            prompt: input.prompt,
+            ...(input.system !== undefined ? { system: input.system } : {}),
+            jsonSchema: z.toJSONSchema(input.schema, { target: 'draft-7' }),
+            ...(input.abortSignal ? { abortSignal: input.abortSignal } : {}),
+        });
+        input.onMetrics?.(metrics(summary, startedAt));
+        return parseStructuredOutput(input.schema, text);
+    }
+    async generateStructuredJson(input) {
+        const { text } = await this.streamStructuredText({
+            role: input.role,
+            prompt: input.prompt,
+            ...(input.system !== undefined ? { system: input.system } : {}),
+            jsonSchema: input.jsonSchema,
+            ...(input.abortSignal ? { abortSignal: input.abortSignal } : {}),
         });
         try {
-            const config = buildCodexRuntimeConfig({
-                model,
-                ...(mcp
-                    ? {
-                        mcp: {
-                            url: mcp.url,
-                            bearerTokenEnvVar: mcp.bearerTokenEnvVar,
-                            bearerToken: mcp.bearerToken,
-                            toolNames: runtimeToolNames(input.tools),
-                        },
-                    }
-                    : {}),
-            });
-            const result = await this.runWithRateLimitRetry(input.abortSignal, async () => {
-                const collected = await collectEvents(await this.runner.runStreamed({
-                    projectDir: this.deps.projectDir,
-                    model,
-                    prompt: promptWithSystem(input.system, input.prompt),
-                    configOverrides: config.configOverrides,
-                    env: config.env,
-                    outputSchema: z.toJSONSchema(input.schema, { target: 'draft-7' }),
-                    ...(input.abortSignal ? { signal: input.abortSignal } : {}),
-                }));
-                const summary = summarizeCodexExecEvents(collected.events, { startedAt });
-                return { collected, summary };
-            }, ({ collected, summary }) => summaryError(summary, collected.streamError));
-            input.onMetrics?.(metrics(result.summary, startedAt));
-            return parseStructuredOutput(input.schema, assertSuccessfulText(result.summary, result.collected.streamError));
+            return JSON.parse(text);
         }
-        finally {
-            await mcp?.close();
+        catch (error) {
+            throw new Error(`Codex structured output is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    subprocessForkSpec() {
+        return { backend: 'codex', projectDir: this.deps.projectDir, modelSlots: this.deps.modelSlots };
+    }
     async runAgentLoop(params) {
         const startedAt = Date.now();
         const model = modelForRole(this.deps.modelSlots, params.modelRole);

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

@@ -67,10 +67,36 @@ export interface KtxGenerateObjectInput<TOutput, TSchema extends z.ZodType<TOutp
     }) => void;
     abortSignal?: AbortSignal;
 }
+/** Structured generation keyed by a raw JSON Schema instead of a Zod schema, so
+ *  the request can cross a process boundary; the caller validates the returned
+ *  value against the real Zod schema. */
+export interface KtxGenerateStructuredJsonInput {
+    role: KtxModelRole;
+    prompt: string;
+    system?: string;
+    jsonSchema: Record<string, unknown>;
+    abortSignal?: AbortSignal;
+}
+/** Serializable recipe to rebuild a subprocess-backed runtime inside a ktx-owned
+ *  child the parent can tree-kill. Returned by {@link KtxLlmRuntimePort.subprocessForkSpec}. */
+export interface SubprocessRuntimeForkSpec {
+    backend: 'codex' | 'claude-code';
+    projectDir: string;
+    modelSlots: {
+        default: string;
+    } & Partial<Record<string, string>>;
+}
 export interface KtxLlmRuntimePort {
     generateText(input: KtxGenerateTextInput): Promise<string>;
     generateObject<TOutput, TSchema extends z.ZodType<TOutput>>(input: KtxGenerateObjectInput<TOutput, TSchema>): Promise<TOutput>;
     runAgentLoop(params: RunLoopParams): Promise<RunLoopResult>;
+    /**
+     * Non-null when this runtime drives an SDK-owned child process that ktx cannot
+     * cancel by abort alone (codex/claude-code spawn a binary the SDK owns and only
+     * SIGTERM on abort). ktx routes such calls through a tree-killable boundary.
+     * Null for HTTP backends, whose native fetch abort already settles promptly.
+     */
+    subprocessForkSpec(): SubprocessRuntimeForkSpec | null;
 }
 export interface AgentRunnerPort {
     runLoop(params: RunLoopParams): Promise<RunLoopResult>;

package/dist/context/llm/subprocess-generate-object-child.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/context/llm/subprocess-generate-object-child.js

@@ -0,0 +1,34 @@
+import { ClaudeCodeKtxLlmRuntime } from './claude-code-runtime.js';
+import { CodexKtxLlmRuntime } from './codex-runtime.js';
+// Forked by the parent as a process-group leader it can SIGKILL as a tree. Hosts
+// one structured LLM call for a subprocess-backed runtime (codex/claude-code);
+// the SDK spawns the model binary as this process's own child, so a parent
+// tree-kill reaps the wedged model too. Credentials flow via inherited env — the
+// runtimes re-derive their allowlisted env from process.env — never over IPC.
+function buildRuntime(forkSpec) {
+    if (forkSpec.backend === 'codex') {
+        return new CodexKtxLlmRuntime({ projectDir: forkSpec.projectDir, modelSlots: forkSpec.modelSlots });
+    }
+    return new ClaudeCodeKtxLlmRuntime({ projectDir: forkSpec.projectDir, modelSlots: forkSpec.modelSlots });
+}
+// The parent owns this process's lifecycle. If the parent dies its IPC channel
+// drops; exit rather than linger as an orphan holding a provider connection.
+process.once('disconnect', () => process.exit(0));
+process.once('message', (request) => {
+    void (async () => {
+        let response;
+        try {
+            const output = await buildRuntime(request.forkSpec).generateStructuredJson({
+                role: request.role,
+                prompt: request.prompt,
+                ...(request.system !== undefined ? { system: request.system } : {}),
+                jsonSchema: request.jsonSchema,
+            });
+            response = { ok: true, output };
+        }
+        catch (error) {
+            response = { ok: false, message: error instanceof Error ? error.message : String(error) };
+        }
+        process.send?.(response, () => process.exit(0));
+    })();
+});

package/dist/context/llm/subprocess-generate-object.d.ts

@@ -0,0 +1,42 @@
+import { type ChildProcess } from 'node:child_process';
+import type { z } from 'zod';
+import type { KtxModelRole } from '../../llm/types.js';
+import type { SubprocessRuntimeForkSpec } from './runtime-port.js';
+export interface SubprocessGenerateObjectRequest {
+    forkSpec: SubprocessRuntimeForkSpec;
+    role: KtxModelRole;
+    prompt: string;
+    system?: string;
+    jsonSchema: Record<string, unknown>;
+}
+export type SubprocessGenerateObjectResponse = {
+    ok: true;
+    output: unknown;
+} | {
+    ok: false;
+    message: string;
+};
+/** A per-table enrichment subprocess that did not return before its deadline. */
+export declare class KtxSubprocessDeadlineError extends Error {
+    readonly deadlineMs: number;
+    constructor(deadlineMs: number);
+}
+export interface RunGenerateObjectInSubprocessInput<TOutput, TSchema extends z.ZodType<TOutput>> {
+    forkSpec: SubprocessRuntimeForkSpec;
+    role: KtxModelRole;
+    prompt: string;
+    system?: string;
+    schema: TSchema;
+    jsonSchema: Record<string, unknown>;
+    deadlineMs: number;
+    signal?: AbortSignal;
+    /** @internal Test seam: spawn the child so tests can observe its lifecycle. */
+    spawnChild?: () => ChildProcess;
+}
+/**
+ * Run one structured LLM call for a subprocess-backed runtime behind a boundary
+ * ktx can hard-kill. On the deadline or an external abort, the whole process
+ * group/tree is SIGKILLed (reaping the SDK's wedged model child) and the promise
+ * settles promptly; on success the raw output is validated against the Zod schema.
+ */
+export declare function runGenerateObjectInSubprocess<TOutput, TSchema extends z.ZodType<TOutput>>(input: RunGenerateObjectInSubprocessInput<TOutput, TSchema>): Promise<TOutput>;

package/dist/context/llm/subprocess-generate-object.js

@@ -0,0 +1,122 @@
+import { fork, spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { createAbortError } from '../core/abort.js';
+// In dist, this file and the child are siblings; under vitest the compiled .js is
+// absent and Node strips types from the .ts. The real child imports the codex /
+// claude SDKs (which use constructor parameter properties), so it only runs as
+// built .js — tests inject a fake child via the spawnChild seam.
+function childUrl() {
+    const builtChild = new URL('./subprocess-generate-object-child.js', import.meta.url);
+    return existsSync(fileURLToPath(builtChild)) ? builtChild : new URL('./subprocess-generate-object-child.ts', import.meta.url);
+}
+function forkSubprocessGenerateObjectChild() {
+    // detached: the child becomes a process-group leader so the SDK's grandchild
+    // (the codex/claude binary) inherits its group and a negative-pid SIGKILL reaps
+    // the whole tree. Empty execArgv keeps it a clean Node process.
+    return fork(childUrl(), {
+        execArgv: [],
+        serialization: 'advanced',
+        detached: true,
+        stdio: ['ignore', 'ignore', 'inherit', 'ipc'],
+    });
+}
+/** A per-table enrichment subprocess that did not return before its deadline. */
+export class KtxSubprocessDeadlineError extends Error {
+    deadlineMs;
+    constructor(deadlineMs) {
+        super(`enrichment subprocess exceeded ${Math.round(deadlineMs / 1000)}s`);
+        this.deadlineMs = deadlineMs;
+        this.name = 'KtxSubprocessDeadlineError';
+    }
+}
+// SIGTERM is too gentle for a child wedged on a hung provider socket; the SDK
+// grandchild ignores it and survives. Kill the whole tree: the detached process
+// group on POSIX, the process tree via taskkill /T on Windows.
+function killProcessTree(child) {
+    if (child.pid === undefined) {
+        return;
+    }
+    if (process.platform === 'win32') {
+        spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' }).on('error', () => undefined);
+        return;
+    }
+    try {
+        process.kill(-child.pid, 'SIGKILL');
+    }
+    catch {
+        try {
+            child.kill('SIGKILL');
+        }
+        catch {
+            // Already exited.
+        }
+    }
+}
+/**
+ * Run one structured LLM call for a subprocess-backed runtime behind a boundary
+ * ktx can hard-kill. On the deadline or an external abort, the whole process
+ * group/tree is SIGKILLed (reaping the SDK's wedged model child) and the promise
+ * settles promptly; on success the raw output is validated against the Zod schema.
+ */
+export function runGenerateObjectInSubprocess(input) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        const child = (input.spawnChild ?? forkSubprocessGenerateObjectChild)();
+        let settled = false;
+        const onDeadline = () => settle(() => rejectPromise(new KtxSubprocessDeadlineError(input.deadlineMs)));
+        const onAbort = () => settle(() => rejectPromise(createAbortError()));
+        const timer = setTimeout(onDeadline, input.deadlineMs);
+        function settle(finish) {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            input.signal?.removeEventListener('abort', onAbort);
+            if (child.exitCode === null && child.signalCode === null) {
+                killProcessTree(child);
+            }
+            finish();
+        }
+        child.on('message', (message) => {
+            if (message.ok) {
+                let parsed;
+                try {
+                    parsed = input.schema.parse(message.output);
+                }
+                catch (error) {
+                    settle(() => rejectPromise(error instanceof Error ? error : new Error(String(error))));
+                    return;
+                }
+                settle(() => resolvePromise(parsed));
+            }
+            else {
+                settle(() => rejectPromise(new Error(message.message)));
+            }
+        });
+        child.on('error', (error) => settle(() => rejectPromise(error)));
+        child.on('exit', (code, processSignal) => {
+            if (!settled) {
+                settle(() => rejectPromise(new Error(`enrichment subprocess exited before returning a result (code ${code}, signal ${processSignal}).`)));
+            }
+        });
+        if (input.signal?.aborted) {
+            onAbort();
+            return;
+        }
+        input.signal?.addEventListener('abort', onAbort, { once: true });
+        try {
+            const request = {
+                forkSpec: input.forkSpec,
+                role: input.role,
+                prompt: input.prompt,
+                ...(input.system !== undefined ? { system: input.system } : {}),
+                jsonSchema: input.jsonSchema,
+            };
+            child.send(request);
+        }
+        catch (error) {
+            settle(() => rejectPromise(error instanceof Error ? error : new Error(String(error))));
+        }
+    });
+}

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

@@ -1,4 +1,5 @@
 import type { KtxCliIo } from '../../cli-runtime.js';
+import { type KtxMcpLogger } from './logger.js';
 import type { KtxMcpClientInfo, KtxMcpContextPorts, KtxMcpServerLike, KtxMcpToolResult, KtxMcpUserContext, NonArrayObject } from './types.js';
 export interface RegisterKtxContextToolsDeps {
     server: KtxMcpServerLike;
@@ -6,6 +7,7 @@ export interface RegisterKtxContextToolsDeps {
     userContext: KtxMcpUserContext;
     projectDir?: string;
     io?: KtxCliIo;
+    logger?: KtxMcpLogger;
     getClientInfo?: () => KtxMcpClientInfo | undefined;
 }
 /** @internal */

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

@@ -3,6 +3,7 @@ import { z } from 'zod';
 import { emitTelemetryEvent, mcpTelemetrySampleRate, reportException, shouldEmitMcpTelemetry, } from '../../telemetry/index.js';
 import { collectTelemetryRedactionSecrets } from '../../telemetry/redaction-secrets.js';
 import { formatErrorDetail, scrubErrorClass } from '../../telemetry/scrubber.js';
+import { mcpSlowToolMs, serializeMcpError } from './logger.js';
 const connectionIdSchema = z.string().min(1);
 const unknownRecordSchema = z.record(z.string(), z.unknown());
 const tableRefSchema = z.object({
@@ -20,19 +21,21 @@ const toolAnnotations = {
     sl_read_source: { title: 'Semantic Layer Read Source', readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     sl_query: { title: 'Semantic Layer Query', readOnlyHint: true, openWorldHint: false },
     sql_execution: { title: 'SQL Execution', readOnlyHint: true, openWorldHint: false },
+    sql_dialect_notes: { title: 'SQL Dialect Notes', readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     memory_ingest: { title: 'Memory Ingest', destructiveHint: true, openWorldHint: false },
     memory_ingest_status: { title: 'Memory Ingest Status', readOnlyHint: true, openWorldHint: false },
 };
 const toolDescriptions = {
     connection_list: 'List configured read-only data connections available to this ktx project. Use this before connection-scoped tools when the project may have multiple warehouses. A "_ktx_federated" entry (when present) queries all its member databases together; use its id for cross-database joins.',
     discover_data: 'Search across ktx wiki pages, semantic-layer sources, measures, dimensions, raw tables, and columns. Example: discover_data({ query: "monthly orders by customer", connectionId: "warehouse", kinds: ["sl_source", "table"] }).',
-    wiki_search: 'Search ktx wiki pages for reusable business context. Example: wiki_search({ query: "revenue recognition", limit: 5 }).',
+    wiki_search: 'Search ktx wiki pages for reusable business context. Pass connectionId to scope results to one warehouse (unscoped pages plus pages tagged with that connection) when a concept name collides across databases. Example: wiki_search({ query: "revenue recognition", connectionId: "warehouse", limit: 5 }).',
     wiki_read: 'Read a ktx wiki page by key returned from wiki_search. Example: wiki_read({ key: "global/revenue" }).',
     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 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 }).',
+    sql_dialect_notes: 'Return the SQL syntax conventions for the dialect of a ktx connection: fully-qualified table-name form, identifier quoting and case-folding, date/time functions, top-N / window-filtering idiom, and JSON access. Call this before writing raw sql_execution SQL against a connection so the SQL matches that engine. Example: sql_dialect_notes({ connectionId: "warehouse" }).',
     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" }).',
 };
@@ -40,6 +43,9 @@ 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.'),
+    connectionId: connectionIdSchema
+        .optional()
+        .describe('Scope results to one connection: returns unscoped pages plus pages tagged with this connection. Omit to search all pages.'),
 });
 const knowledgeReadSchema = z.object({
     key: z.string().min(1).describe('Wiki page key returned by wiki_search, e.g. "global/revenue".'),
@@ -143,6 +149,9 @@ const sqlExecutionSchema = z.object({
     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.'),
 });
+const sqlDialectNotesSchema = z.object({
+    connectionId: connectionIdSchema.describe('Connection id whose engine dialect conventions to return.'),
+});
 const memoryIngestSchema = z.object({
     content: z
         .string()
@@ -309,6 +318,11 @@ const sqlExecutionOutputSchema = z.object({
     rows: z.array(z.array(z.unknown())),
     rowCount: z.number(),
 });
+const sqlDialectNotesOutputSchema = z.object({
+    connectionId: z.string(),
+    dialect: z.string(),
+    notes: z.string(),
+});
 const memoryIngestOutputSchema = z.object({
     runId: z.string(),
 });
@@ -444,6 +458,47 @@ function clientTelemetryFields(getClientInfo) {
         ...(client?.version ? { mcpClientVersion: client.version } : {}),
     };
 }
+function toolResultIsError(result) {
+    return (typeof result === 'object' && result !== null && 'isError' in result && result.isError === true);
+}
+/** Tool-agnostic size: byte length of the serialized text content the client reads. */
+function toolResultSize(result) {
+    if (typeof result !== 'object' || result === null || !('content' in result)) {
+        return 0;
+    }
+    const content = result.content;
+    if (!Array.isArray(content)) {
+        return 0;
+    }
+    let size = 0;
+    for (const item of content) {
+        if (item && typeof item === 'object' && item.type === 'text') {
+            const text = item.text;
+            if (typeof text === 'string') {
+                size += Buffer.byteLength(text, 'utf8');
+            }
+        }
+    }
+    return size;
+}
+function toolResultErrorText(result) {
+    if (typeof result === 'object' && result !== null && 'content' in result) {
+        const content = result.content;
+        if (Array.isArray(content)) {
+            const text = content
+                .filter((item) => !!item &&
+                typeof item === 'object' &&
+                item.type === 'text' &&
+                typeof item.text === 'string')
+                .map((item) => item.text)
+                .join('\n');
+            if (text.length > 0) {
+                return text;
+            }
+        }
+    }
+    return 'Tool returned an error result.';
+}
 // Tools registered via registerParsedTool catch their own errors and return an
 // isError result, so the telemetry layer never sees the thrown Error. Recover
 // the failure message from the result's text content (the same string the agent
@@ -463,65 +518,91 @@ function mcpErrorResultDetail(result) {
         .join('\n');
     return formatErrorDetail(text);
 }
-function instrumentMcpServer(server, telemetry) {
+function instrumentMcpServer(server, deps) {
     return {
         registerTool(name, config, handler) {
             server.registerTool(name, config, async (input, context) => {
+                const callId = randomUUID();
+                const callLogger = deps.logger?.child({
+                    tool: name,
+                    callId,
+                    ...(context?.sessionId ? { sessionId: context.sessionId } : {}),
+                });
                 const startedAt = performance.now();
+                // Synchronous, before the (possibly blocking) handler: a runaway query that never
+                // returns still leaves this start line — with its exact params — on disk.
+                callLogger?.info({ params: input }, 'tool.start');
                 try {
                     const result = await handler(input, context);
-                    if (telemetry.io && telemetry.projectDir && shouldEmitMcpTelemetry()) {
-                        const isError = typeof result === 'object' && result !== null && 'isError' in result && result.isError === true;
+                    const durationMs = Math.max(0, performance.now() - startedAt);
+                    const isError = toolResultIsError(result);
+                    if (deps.io && deps.projectDir && shouldEmitMcpTelemetry()) {
                         const errorDetail = isError ? mcpErrorResultDetail(result) : undefined;
                         await emitTelemetryEvent({
                             name: 'mcp_request_completed',
-                            projectDir: telemetry.projectDir,
-                            io: telemetry.io,
+                            projectDir: deps.projectDir,
+                            io: deps.io,
                             fields: {
                                 toolName: name,
                                 outcome: isError ? 'error' : 'ok',
-                                durationMs: Math.max(0, performance.now() - startedAt),
+                                durationMs,
                                 sampleRate: mcpTelemetrySampleRate(),
                                 ...(errorDetail ? { errorDetail } : {}),
-                                ...clientTelemetryFields(telemetry.getClientInfo),
+                                ...clientTelemetryFields(deps.getClientInfo),
                             },
                         });
                     }
+                    if (callLogger) {
+                        if (isError) {
+                            callLogger.error({ durationMs, outcome: 'error', err: serializeMcpError(toolResultErrorText(result)) }, 'tool.end');
+                        }
+                        else {
+                            const fields = { durationMs, outcome: 'ok', resultSize: toolResultSize(result) };
+                            if (durationMs > deps.slowToolMs) {
+                                callLogger.warn(fields, 'tool.end');
+                            }
+                            else {
+                                callLogger.info(fields, 'tool.end');
+                            }
+                        }
+                    }
                     return result;
                 }
                 catch (error) {
-                    if (telemetry.io) {
+                    const durationMs = Math.max(0, performance.now() - startedAt);
+                    if (deps.io) {
                         await reportException({
                             error,
                             context: { source: `mcp:${name}`, handled: true, fatal: false },
-                            projectDir: telemetry.projectDir,
-                            io: telemetry.io,
+                            projectDir: deps.projectDir,
+                            io: deps.io,
                             redactionSecrets: await collectTelemetryRedactionSecrets({
-                                projectDir: telemetry.projectDir,
+                                projectDir: deps.projectDir,
                                 includeLlm: true,
                                 includeEmbeddings: true,
                                 env: process.env,
                             }),
                         });
                     }
-                    if (telemetry.io && telemetry.projectDir && shouldEmitMcpTelemetry()) {
+                    if (deps.io && deps.projectDir && shouldEmitMcpTelemetry()) {
                         const errorClass = scrubErrorClass(error);
                         const errorDetail = formatErrorDetail(error);
                         await emitTelemetryEvent({
                             name: 'mcp_request_completed',
-                            projectDir: telemetry.projectDir,
-                            io: telemetry.io,
+                            projectDir: deps.projectDir,
+                            io: deps.io,
                             fields: {
                                 toolName: name,
                                 outcome: 'error',
                                 ...(errorClass ? { errorClass } : {}),
                                 ...(errorDetail ? { errorDetail } : {}),
-                                durationMs: Math.max(0, performance.now() - startedAt),
+                                durationMs,
                                 sampleRate: mcpTelemetrySampleRate(),
-                                ...clientTelemetryFields(telemetry.getClientInfo),
+                                ...clientTelemetryFields(deps.getClientInfo),
                             },
                         });
                     }
+                    callLogger?.error({ durationMs, outcome: 'error', err: serializeMcpError(error) }, 'tool.end');
                     throw error;
                 }
             });
@@ -534,6 +615,8 @@ export function registerKtxContextTools(deps) {
     const server = instrumentMcpServer(deps.server, {
         projectDir: deps.projectDir,
         io: deps.io,
+        logger: deps.logger,
+        slowToolMs: mcpSlowToolMs(),
         getClientInfo: deps.getClientInfo,
     });
     if (ports.connections) {
@@ -558,6 +641,7 @@ export function registerKtxContextTools(deps) {
             userId: userContext.userId,
             query: input.query,
             limit: input.limit,
+            ...(input.connectionId !== undefined ? { connectionId: input.connectionId } : {}),
         })), toolTelemetry);
         registerParsedTool(server, 'wiki_read', {
             title: toolAnnotations.wiki_read.title,
@@ -654,6 +738,16 @@ export function registerKtxContextTools(deps) {
             }, onProgress ? { onProgress } : undefined));
         }, toolTelemetry);
     }
+    if (ports.dialectNotes) {
+        const dialectNotes = ports.dialectNotes;
+        registerParsedTool(server, 'sql_dialect_notes', {
+            title: toolAnnotations.sql_dialect_notes.title,
+            description: toolDescriptions.sql_dialect_notes,
+            inputSchema: sqlDialectNotesSchema.shape,
+            outputSchema: sqlDialectNotesOutputSchema,
+            annotations: toolAnnotations.sql_dialect_notes,
+        }, sqlDialectNotesSchema, async (input) => jsonToolResult(await dialectNotes.read(input)), toolTelemetry);
+    }
     if (ports.memoryIngest) {
         const memoryIngest = ports.memoryIngest;
         registerParsedTool(server, 'memory_ingest', {

package/dist/context/mcp/local-project-ports.d.ts

@@ -1,4 +1,5 @@
 import type { KtxSqlQueryExecutorPort } from '../../context/connections/query-executor.js';
+import type { KtxProjectConnectionConfig } from '../../context/project/config.js';
 import type { KtxEmbeddingPort } from '../../context/core/embedding.js';
 import type { KtxSemanticLayerComputePort } from '../../context/daemon/semantic-layer-compute.js';
 import type { KtxLocalProject } from '../../context/project/project.js';
@@ -12,5 +13,11 @@ interface CreateLocalProjectMcpContextPortsOptions {
     localScan?: LocalScanMcpOptions;
     embeddingService: KtxEmbeddingPort | null;
 }
+/** @internal Resolves a connection's dialect SQL notes; throws KtxExpectedError for an unknown or non-SQL-warehouse connection. */
+export declare function resolveDialectNotesForConnection(connectionId: string, connection: KtxProjectConnectionConfig | undefined): {
+    connectionId: string;
+    dialect: string;
+    notes: string;
+};
 export declare function createLocalProjectMcpContextPorts(project: KtxLocalProject, options: CreateLocalProjectMcpContextPortsOptions): KtxMcpContextPorts;
 export {};