@kaelio/ktx 0.13.1 → 0.14.0

package/dist/context/mcp/local-project-ports.js

@@ -1,6 +1,9 @@
 import { KtxExpectedError, KtxQueryError, isNativeProgrammingFault } from '../../errors.js';
+import { isDatabaseDriver, normalizeConnectionDriver } from '../../connection-drivers.js';
+import { sqlDialectNotes } from '../../context/sql-analysis/dialect-notes.js';
 import { executeProjectReadOnlySql } from '../../context/connections/project-sql-executor.js';
 import { FEDERATED_CONNECTION_ID, federatedConnectionListing } from '../../context/connections/federation.js';
+import { assertSqlQueryableConnection } from '../../context/connections/dialects.js';
 import { resolveConfiguredConnection } from '../../context/connections/resolve-connection.js';
 import { localConnectionInfoFromConfig, } from '../../context/connections/local-warehouse-descriptor.js';
 import { createKtxEntityDetailsService } from '../../context/scan/entity-details.js';
@@ -10,6 +13,7 @@ import { compileLocalSlQuery } from '../../context/sl/local-query.js';
 import { createKtxDictionarySearchService } from '../../context/sl/dictionary-search.js';
 import { readLocalSlSource } from '../../context/sl/local-sl.js';
 import { assertSafeConnectionId } from '../../context/sl/source-files.js';
+import { assertConfiguredConnectionId } from '../../context/connections/configured-connections.js';
 import { readLocalKnowledgePage, searchLocalKnowledgePages } from '../wiki/local-knowledge.js';
 async function executeValidatedReadOnlySql(project, options, input, onProgress) {
     await onProgress?.({ progress: 0, message: 'Validating SQL' });
@@ -23,6 +27,9 @@ async function executeValidatedReadOnlySql(project, options, input, onProgress)
     const isFederated = input.connectionId === FEDERATED_CONNECTION_ID;
     const connectionId = isFederated ? input.connectionId : assertSafeConnectionId(input.connectionId);
     const connection = isFederated ? undefined : resolveConfiguredConnection(project.config, connectionId);
+    if (!isFederated) {
+        assertSqlQueryableConnection(connectionId, connection.driver);
+    }
     const dialect = sqlAnalysisDialectForDriver(isFederated ? 'duckdb' : connection.driver);
     const validation = await options.sqlAnalysis.validateReadOnly(input.sql, dialect);
     if (!validation.ok) {
@@ -62,6 +69,18 @@ async function executeValidatedReadOnlySql(project, options, input, onProgress)
     await onProgress?.({ progress: 1, message: `Fetched ${response.rowCount} rows` });
     return response;
 }
+/** @internal Resolves a connection's dialect SQL notes; throws KtxExpectedError for an unknown or non-SQL-warehouse connection. */
+export function resolveDialectNotesForConnection(connectionId, connection) {
+    if (!connection) {
+        throw new KtxExpectedError(`Connection "${connectionId}" is not configured in ktx.yaml`);
+    }
+    const driver = normalizeConnectionDriver(connection);
+    if (!isDatabaseDriver(driver)) {
+        throw new KtxExpectedError(`Connection "${connectionId}" uses the "${driver}" context source, not a SQL warehouse; sql_dialect_notes applies only to SQL database connections.`);
+    }
+    const dialect = sqlAnalysisDialectForDriver(driver);
+    return { connectionId, dialect, notes: sqlDialectNotes(dialect) };
+}
 export function createLocalProjectMcpContextPorts(project, options) {
     const embeddingService = options.embeddingService;
     const ports = {
@@ -86,11 +105,15 @@ export function createLocalProjectMcpContextPorts(project, options) {
         },
         knowledge: {
             async search(input) {
+                const connectionId = input.connectionId === undefined
+                    ? undefined
+                    : assertConfiguredConnectionId(project.config.connections, input.connectionId);
                 const results = await searchLocalKnowledgePages(project, {
                     query: input.query,
                     userId: input.userId,
                     limit: input.limit,
                     embeddingService,
+                    ...(connectionId !== undefined ? { connectionId } : {}),
                 });
                 return {
                     results: results.slice(0, input.limit).map((result) => ({
@@ -161,6 +184,12 @@ export function createLocalProjectMcpContextPorts(project, options) {
                 return createKtxDiscoverDataService(project, { userId: 'local', embeddingService }).search(input);
             },
         },
+        dialectNotes: {
+            async read(input) {
+                const connectionId = assertSafeConnectionId(input.connectionId);
+                return resolveDialectNotesForConnection(connectionId, project.config.connections[connectionId]);
+            },
+        },
     };
     if (options.sqlAnalysis && options.localScan?.createConnector) {
         ports.sqlExecution = {

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

@@ -0,0 +1,24 @@
+import { type Logger } from 'pino';
+import type { KtxCliIo } from '../../cli-runtime.js';
+export type KtxMcpLogger = Logger;
+/** @internal */
+export declare function mcpLogLevel(env?: NodeJS.ProcessEnv): string;
+/** @internal */
+export declare function mcpSlowToolMs(env?: NodeJS.ProcessEnv): number;
+/**
+ * Serialize an error for a structured `err` field. Genuine `Error`s get pino's
+ * standard serializer (type + message + stack); everything else is reduced to a
+ * message — the in-band tool-error path has already lost the original stack.
+ */
+export declare function serializeMcpError(error: unknown): Record<string, unknown>;
+/**
+ * One synchronous pino logger per MCP server process, written to the `io.stderr`
+ * sink. stderr is the only universally-correct sink: the stdio transport reserves
+ * stdout for JSON-RPC, and the HTTP daemon redirects stderr into `.ktx/logs/mcp.log`.
+ * Synchronous writes are load-bearing — a `tool.start` line must reach the fd before
+ * a blocking handler runs, so a runaway query still leaves its start record on disk.
+ * Format follows the terminal, not a flag: pretty for a TTY, plain JSON otherwise.
+ */
+export declare function createMcpLogger(io: KtxCliIo, options?: {
+    isTTY?: boolean;
+}): KtxMcpLogger;

package/dist/context/mcp/logger.js

@@ -0,0 +1,49 @@
+import { Writable } from 'node:stream';
+import pino from 'pino';
+import PinoPretty from 'pino-pretty';
+const LOG_LEVELS = new Set(['trace', 'debug', 'info', 'warn', 'error', 'fatal', 'silent']);
+const DEFAULT_LEVEL = 'info';
+const DEFAULT_SLOW_TOOL_MS = 10_000;
+/** @internal */
+export function mcpLogLevel(env = process.env) {
+    const raw = env.KTX_MCP_LOG_LEVEL?.trim().toLowerCase();
+    return raw && LOG_LEVELS.has(raw) ? raw : DEFAULT_LEVEL;
+}
+/** @internal */
+export function mcpSlowToolMs(env = process.env) {
+    const raw = Number(env.KTX_MCP_SLOW_TOOL_MS);
+    return Number.isFinite(raw) && raw >= 0 ? raw : DEFAULT_SLOW_TOOL_MS;
+}
+/**
+ * Serialize an error for a structured `err` field. Genuine `Error`s get pino's
+ * standard serializer (type + message + stack); everything else is reduced to a
+ * message — the in-band tool-error path has already lost the original stack.
+ */
+export function serializeMcpError(error) {
+    if (error instanceof Error) {
+        return { ...pino.stdSerializers.err(error) };
+    }
+    return { message: typeof error === 'string' ? error : String(error) };
+}
+/**
+ * One synchronous pino logger per MCP server process, written to the `io.stderr`
+ * sink. stderr is the only universally-correct sink: the stdio transport reserves
+ * stdout for JSON-RPC, and the HTTP daemon redirects stderr into `.ktx/logs/mcp.log`.
+ * Synchronous writes are load-bearing — a `tool.start` line must reach the fd before
+ * a blocking handler runs, so a runaway query still leaves its start record on disk.
+ * Format follows the terminal, not a flag: pretty for a TTY, plain JSON otherwise.
+ */
+export function createMcpLogger(io, options = {}) {
+    const level = mcpLogLevel();
+    const isTTY = options.isTTY ?? process.stderr.isTTY === true;
+    if (isTTY) {
+        const sink = new Writable({
+            write(chunk, _encoding, callback) {
+                io.stderr.write(typeof chunk === 'string' ? chunk : chunk.toString('utf8'));
+                callback();
+            },
+        });
+        return pino({ level }, PinoPretty({ colorize: true, sync: true, destination: sink }));
+    }
+    return pino({ level }, io.stderr);
+}

package/dist/context/mcp/server.js

@@ -9,6 +9,7 @@ export function createKtxMcpServer(deps) {
             userContext: deps.userContext,
             projectDir: deps.projectDir,
             io: deps.io,
+            logger: deps.logger,
             getClientInfo: deps.getClientInfo,
         });
     }
@@ -25,6 +26,7 @@ export function createDefaultKtxMcpServer(deps) {
         contextTools: deps.contextTools,
         projectDir: deps.projectDir,
         io: deps.io,
+        logger: deps.logger,
         // 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(),

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

@@ -1,5 +1,6 @@
 import type { MemoryIngestService } from '../../context/memory/memory-runs.js';
 import type { KtxCliIo } from '../../cli-runtime.js';
+import type { KtxMcpLogger } from './logger.js';
 import type { KtxEntityDetailsInput, KtxEntityDetailsResponse } from '../scan/entity-details.js';
 import type { KtxDiscoverDataInput, KtxDiscoverDataResponse } from '../../context/search/discover.js';
 import type { KtxDictionarySearchInput, KtxDictionarySearchResponse } from '../../context/sl/dictionary-search.js';
@@ -24,6 +25,8 @@ interface KtxMcpProgressEvent {
 }
 export type KtxMcpProgressCallback = (event: KtxMcpProgressEvent) => void | Promise<void>;
 export interface KtxMcpToolHandlerContext {
+    /** Present for the HTTP StreamableHTTP transport (one per session); absent for stdio. */
+    sessionId?: string;
     _meta?: {
         progressToken?: string | number;
         [key: string]: unknown;
@@ -102,6 +105,7 @@ export interface KtxKnowledgeMcpPort {
         userId: string;
         query: string;
         limit: number;
+        connectionId?: string;
     }): Promise<KtxKnowledgeSearchResponse>;
     read(input: {
         userId: string;
@@ -163,6 +167,16 @@ export interface KtxSqlExecutionMcpPort {
         onProgress?: KtxMcpProgressCallback;
     }): Promise<KtxSqlExecutionResponse>;
 }
+/** @internal */
+export interface KtxDialectNotesMcpPort {
+    read(input: {
+        connectionId: string;
+    }): Promise<{
+        connectionId: string;
+        dialect: string;
+        notes: string;
+    }>;
+}
 export interface KtxMcpContextPorts {
     connections?: KtxConnectionsMcpPort;
     knowledge?: KtxKnowledgeMcpPort;
@@ -171,6 +185,7 @@ export interface KtxMcpContextPorts {
     dictionarySearch?: KtxDictionarySearchMcpPort;
     discover?: KtxDiscoverDataMcpPort;
     sqlExecution?: KtxSqlExecutionMcpPort;
+    dialectNotes?: KtxDialectNotesMcpPort;
     memoryIngest?: MemoryIngestPort;
 }
 export interface KtxMcpServerDeps {
@@ -179,6 +194,8 @@ export interface KtxMcpServerDeps {
     contextTools?: KtxMcpContextPorts;
     projectDir?: string;
     io?: KtxCliIo;
+    /** Shared per-process logger for tool-call observability; tool-call logging is off when absent. */
+    logger?: KtxMcpLogger;
     /** Reads the connected client's identity once the initialize handshake completes. */
     getClientInfo?: () => KtxMcpClientInfo | undefined;
 }

package/dist/context/memory/memory-agent.service.js

@@ -131,7 +131,7 @@ export class MemoryAgentService {
             : '';
         const prompt = [
             `# Wiki Index\n\n${wikiIndex}`,
-            hasSL ? `\n# Semantic Layer Sources\n\n${slIndex}` : '',
+            hasSL ? `\n# Semantic Layer Sources (connectionId: ${input.connectionId})\n\n${slIndex}` : '',
             '\n---\n',
             assistantSection,
             `\n## User Message\n\n${input.userMessage.trim()}`,

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

@@ -102,35 +102,51 @@ declare const scanRelationshipsSchema: z.ZodObject<{
     profileConcurrency: z.ZodDefault<z.ZodInt>;
     validationConcurrency: z.ZodDefault<z.ZodInt>;
     validationBudget: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodInt]>>;
+    detectionBudgetMs: z.ZodDefault<z.ZodInt>;
 }, z.core.$strict>;
 declare const connectionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     driver: z.ZodLiteral<"postgres">;
     url: z.ZodOptional<z.ZodString>;
     enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    query_timeout_ms: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>, z.ZodObject<{
     driver: z.ZodLiteral<"mysql">;
     url: z.ZodOptional<z.ZodString>;
     enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    query_timeout_ms: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>, z.ZodObject<{
     driver: z.ZodLiteral<"snowflake">;
     url: z.ZodOptional<z.ZodString>;
     enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    query_timeout_ms: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>, z.ZodObject<{
     driver: z.ZodLiteral<"bigquery">;
     url: z.ZodOptional<z.ZodString>;
     enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    query_timeout_ms: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>, z.ZodObject<{
     driver: z.ZodLiteral<"sqlite">;
     url: z.ZodOptional<z.ZodString>;
     enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    query_timeout_ms: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>, z.ZodObject<{
     driver: z.ZodLiteral<"clickhouse">;
     url: z.ZodOptional<z.ZodString>;
     enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    query_timeout_ms: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>, z.ZodObject<{
     driver: z.ZodLiteral<"sqlserver">;
     url: z.ZodOptional<z.ZodString>;
     enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    query_timeout_ms: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>, z.ZodObject<{
+    driver: z.ZodLiteral<"mongodb">;
+    url: z.ZodString;
+    database: z.ZodOptional<z.ZodString>;
+    databases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    sample_size: z.ZodOptional<z.ZodNumber>;
+    order_by: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>, z.ZodObject<{
     driver: z.ZodLiteral<"metabase">;
     api_url: z.ZodString;
@@ -184,6 +200,11 @@ declare const connectionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     max_pages_per_run: z.ZodOptional<z.ZodNumber>;
     max_knowledge_creates_per_run: z.ZodOptional<z.ZodNumber>;
     max_knowledge_updates_per_run: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>, z.ZodObject<{
+    driver: z.ZodLiteral<"gdrive">;
+    service_account_key_ref: z.ZodString;
+    folder_id: z.ZodString;
+    recursive: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$loose>, z.ZodObject<{
     driver: z.ZodLiteral<"dbt">;
     source_dir: z.ZodOptional<z.ZodString>;
@@ -211,30 +232,45 @@ declare const ktxProjectConfigSchema: z.ZodObject<{
         driver: z.ZodLiteral<"postgres">;
         url: z.ZodOptional<z.ZodString>;
         enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        query_timeout_ms: z.ZodOptional<z.ZodNumber>;
     }, z.core.$loose>, z.ZodObject<{
         driver: z.ZodLiteral<"mysql">;
         url: z.ZodOptional<z.ZodString>;
         enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        query_timeout_ms: z.ZodOptional<z.ZodNumber>;
     }, z.core.$loose>, z.ZodObject<{
         driver: z.ZodLiteral<"snowflake">;
         url: z.ZodOptional<z.ZodString>;
         enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        query_timeout_ms: z.ZodOptional<z.ZodNumber>;
     }, z.core.$loose>, z.ZodObject<{
         driver: z.ZodLiteral<"bigquery">;
         url: z.ZodOptional<z.ZodString>;
         enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        query_timeout_ms: z.ZodOptional<z.ZodNumber>;
     }, z.core.$loose>, z.ZodObject<{
         driver: z.ZodLiteral<"sqlite">;
         url: z.ZodOptional<z.ZodString>;
         enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        query_timeout_ms: z.ZodOptional<z.ZodNumber>;
     }, z.core.$loose>, z.ZodObject<{
         driver: z.ZodLiteral<"clickhouse">;
         url: z.ZodOptional<z.ZodString>;
         enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        query_timeout_ms: z.ZodOptional<z.ZodNumber>;
     }, z.core.$loose>, z.ZodObject<{
         driver: z.ZodLiteral<"sqlserver">;
         url: z.ZodOptional<z.ZodString>;
         enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        query_timeout_ms: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>, z.ZodObject<{
+        driver: z.ZodLiteral<"mongodb">;
+        url: z.ZodString;
+        database: z.ZodOptional<z.ZodString>;
+        databases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        sample_size: z.ZodOptional<z.ZodNumber>;
+        order_by: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>, z.ZodObject<{
         driver: z.ZodLiteral<"metabase">;
         api_url: z.ZodString;
@@ -288,6 +324,11 @@ declare const ktxProjectConfigSchema: z.ZodObject<{
         max_pages_per_run: z.ZodOptional<z.ZodNumber>;
         max_knowledge_creates_per_run: z.ZodOptional<z.ZodNumber>;
         max_knowledge_updates_per_run: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>, z.ZodObject<{
+        driver: z.ZodLiteral<"gdrive">;
+        service_account_key_ref: z.ZodString;
+        folder_id: z.ZodString;
+        recursive: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$loose>, z.ZodObject<{
         driver: z.ZodLiteral<"dbt">;
         source_dir: z.ZodOptional<z.ZodString>;
@@ -455,6 +496,7 @@ declare const ktxProjectConfigSchema: z.ZodObject<{
             profileConcurrency: z.ZodDefault<z.ZodInt>;
             validationConcurrency: z.ZodDefault<z.ZodInt>;
             validationBudget: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodInt]>>;
+            detectionBudgetMs: z.ZodDefault<z.ZodInt>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;

package/dist/context/project/config.js

@@ -187,6 +187,11 @@ const scanRelationshipsSchema = z
         .union([z.literal('all'), z.int().nonnegative()])
         .optional()
         .describe('Cap on validation queries per scan run. Use "all" for unlimited, an integer for a hard cap, or omit for the runtime default.'),
+    detectionBudgetMs: z
+        .int()
+        .positive()
+        .default(600_000)
+        .describe('Wall-clock budget (ms) for the whole relationship-detection stage. Checked at table-profile, LLM-proposal, candidate-validation, and composite-probe boundaries; above the per-query deadline. On exhaustion the stage stops scheduling new work and returns the relationships found so far, marked partial. Raise it to trigger a fresher, fuller run.'),
 })
     .describe('Schema-scan relationship discovery and validation tunables.');
 const scanSchema = z

package/dist/context/project/driver-schemas.d.ts

@@ -3,30 +3,45 @@ export declare const connectionConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
     driver: z.ZodLiteral<"postgres">;
     url: z.ZodOptional<z.ZodString>;
     enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    query_timeout_ms: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>, z.ZodObject<{
     driver: z.ZodLiteral<"mysql">;
     url: z.ZodOptional<z.ZodString>;
     enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    query_timeout_ms: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>, z.ZodObject<{
     driver: z.ZodLiteral<"snowflake">;
     url: z.ZodOptional<z.ZodString>;
     enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    query_timeout_ms: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>, z.ZodObject<{
     driver: z.ZodLiteral<"bigquery">;
     url: z.ZodOptional<z.ZodString>;
     enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    query_timeout_ms: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>, z.ZodObject<{
     driver: z.ZodLiteral<"sqlite">;
     url: z.ZodOptional<z.ZodString>;
     enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    query_timeout_ms: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>, z.ZodObject<{
     driver: z.ZodLiteral<"clickhouse">;
     url: z.ZodOptional<z.ZodString>;
     enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    query_timeout_ms: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>, z.ZodObject<{
     driver: z.ZodLiteral<"sqlserver">;
     url: z.ZodOptional<z.ZodString>;
     enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    query_timeout_ms: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>, z.ZodObject<{
+    driver: z.ZodLiteral<"mongodb">;
+    url: z.ZodString;
+    database: z.ZodOptional<z.ZodString>;
+    databases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    sample_size: z.ZodOptional<z.ZodNumber>;
+    order_by: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>, z.ZodObject<{
     driver: z.ZodLiteral<"metabase">;
     api_url: z.ZodString;
@@ -80,6 +95,11 @@ export declare const connectionConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
     max_pages_per_run: z.ZodOptional<z.ZodNumber>;
     max_knowledge_creates_per_run: z.ZodOptional<z.ZodNumber>;
     max_knowledge_updates_per_run: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>, z.ZodObject<{
+    driver: z.ZodLiteral<"gdrive">;
+    service_account_key_ref: z.ZodString;
+    folder_id: z.ZodString;
+    recursive: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$loose>, z.ZodObject<{
     driver: z.ZodLiteral<"dbt">;
     source_dir: z.ZodOptional<z.ZodString>;

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

@@ -21,7 +21,13 @@ 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 ingest on a single table.'),
+            .describe('Optional allowlist of object names to ingest. Accepted forms: "catalog.db.name", "db.name" (schema-qualified), or bare "name". When set, live-database ingest restricts the scan to the listed objects and fails with a clear error if none match. For SQLite, "main.<name>" and the bare "<name>" are equivalent (SQLite exposes a single "main" schema). Useful for smoke-testing ingest on a single table.'),
+        query_timeout_ms: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe('Maximum execution time for a single read-only query, in milliseconds (default 30000). Enforced as a server-side statement timeout for remote engines and by SIGKILL-ing a forked query subprocess for in-process SQLite. A query exceeding it is cancelled and returns a "query exceeded Ns" error so the agent can revise.'),
     })
         .describe(`${driver} warehouse connection. Additional driver-tunable fields (e.g. context.queryHistory) are accepted and passed through.`);
 }
@@ -34,6 +40,36 @@ const warehouseConnectionSchemas = [
     warehouseConnectionSchema('clickhouse'),
     warehouseConnectionSchema('sqlserver'),
 ];
+const mongodbConnectionSchema = z
+    .looseObject({
+    driver: z.literal('mongodb'),
+    url: z
+        .string()
+        .min(1)
+        .describe('MongoDB connection string (mongodb:// or mongodb+srv://, including TLS/Atlas); may contain a reference like env:MONGO_URL.'),
+    database: z.string().min(1).optional().describe('Single database to introspect when not using databases or a URL path.'),
+    databases: z
+        .array(z.string().min(1))
+        .optional()
+        .describe('Databases whose collections ktx introspects as tables. Falls back to the URL path database.'),
+    enabled_tables: z
+        .array(z.string().min(1))
+        .optional()
+        .describe('Optional allowlist of "database.collection" names to introspect.'),
+    sample_size: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe('How many recent documents to sample per collection when inferring the schema (default 1000).'),
+    order_by: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Field to sort by descending when sampling. Defaults to _id; set this when _id is not an ObjectId. ' +
+        'Should be indexed — an unindexed sort hits MongoDB\'s in-memory sort limit on large collections.'),
+})
+    .describe('MongoDB primary-source connection. Schema is inferred by sampling the most recent documents.');
 const positiveIntKeyMessage = (field) => `${field} keys must be positive-integer strings (e.g. "1", "42")`;
 const positiveIntKeyRegex = /^[1-9]\d*$/;
 const metabaseMappingsStrictSchema = metabaseMappingsSchema.superRefine((value, ctx) => {
@@ -145,6 +181,17 @@ const notionConnectionSchema = z
         .describe('Maximum existing wiki pages updated per run.'),
 })
     .describe('Notion context-source connection.');
+const gdriveConnectionSchema = z
+    .looseObject({
+    driver: z.literal('gdrive'),
+    service_account_key_ref: z
+        .string()
+        .min(1)
+        .describe('Reference to a Google service-account JSON key file. Must use file:/absolute/path/to/key.json.'),
+    folder_id: z.string().min(1).describe('Google Drive folder ID to ingest.'),
+    recursive: z.boolean().optional().describe('When true, recursively traverse subfolders beneath folder_id.'),
+})
+    .describe('Google Drive Google Docs context-source connection.');
 const dbtConnectionSchema = z
     .looseObject({
     driver: z.literal('dbt'),
@@ -173,10 +220,12 @@ const metricflowConnectionSchema = z
     .describe('MetricFlow / SL context-source connection.');
 export const connectionConfigSchema = z.discriminatedUnion('driver', [
     ...warehouseConnectionSchemas,
+    mongodbConnectionSchema,
     metabaseConnectionSchema,
     lookerConnectionSchema,
     lookmlConnectionSchema,
     notionConnectionSchema,
+    gdriveConnectionSchema,
     dbtConnectionSchema,
     metricflowConnectionSchema,
 ]);

package/dist/context/project/project.js

@@ -7,7 +7,7 @@ import { LocalGitFileStore } from './local-git-file-store.js';
 const TRACKED_SCAFFOLD_FILES = [
     {
         path: '.ktx/.gitignore',
-        content: 'cache/\ndb.sqlite\ndb.sqlite-*\ningest-transcripts/\nsecrets/\nsetup/\nagents/\n',
+        content: 'cache/\ndb.sqlite\ndb.sqlite-*\ningest-transcripts/\nlogs/\nsecrets/\nsetup/\nagents/\n',
     },
     { path: '.ktx/prompts/.gitkeep', content: '' },
     { path: '.ktx/skills/.gitkeep', content: '' },

package/dist/context/project/setup-config.js

@@ -15,6 +15,7 @@ const SETUP_GITIGNORE_ENTRIES = [
     'db.sqlite',
     'db.sqlite-*',
     'ingest-transcripts/',
+    'logs/',
     'secrets/',
     'setup/',
     'agents/',

package/dist/context/scan/description-generation.d.ts

@@ -1,3 +1,4 @@
+import type { ChildProcess } from 'node:child_process';
 import type { KtxLlmRuntimePort } from '../../context/llm/runtime-port.js';
 import type { KtxColumnSampleInput, KtxColumnSampleResult, KtxScanContext, KtxScanLoggerPort, KtxScanWarning, KtxTableRef, KtxTableSampleInput, KtxTableSampleResult } from './types.js';
 interface KtxDescriptionTableColumn {
@@ -113,6 +114,8 @@ export interface KtxDescriptionGeneratorOptions {
     logger?: KtxScanLoggerPort;
     onWarning?: (warning: KtxScanWarning) => void;
     settings: KtxDescriptionGenerationSettings;
+    /** @internal Test seam: spawn the kill-boundary child for subprocess backends. */
+    spawnSubprocessGenerateChild?: () => ChildProcess;
 }
 export interface KtxDescriptionPrompt {
     system: string;
@@ -136,6 +139,7 @@ export declare class KtxDescriptionGenerator {
     private readonly logger?;
     private readonly onWarning?;
     private readonly settings;
+    private readonly spawnSubprocessGenerateChild?;
     constructor(options: KtxDescriptionGeneratorOptions);
     generateColumnDescriptions(input: KtxGenerateColumnDescriptionsInput): Promise<KtxColumnAnalysisResult>;
     generateTableDescription(input: KtxGenerateTableDescriptionInput): Promise<string | null>;