@kaelio/ktx 0.12.0 → 0.13.1

package/dist/context/connections/read-only-sql.js

@@ -1,3 +1,4 @@
+import { KtxQueryError } from '../../errors.js';
 const MUTATING_SQL = /^\s*(insert|update|delete|merge|alter|drop|create|truncate|grant|revoke|copy|call|do|vacuum|analyze|refresh)\b/i;
 const READ_SQL = /^\s*(select|with)\b/i;
 // Agents (and the daemon's sqlglot validator, which ignores comments) routinely
@@ -77,7 +78,7 @@ function assertSingleSqlStatement(sql) {
             sawSemicolon = true;
         }
         else if (sawSemicolon && !/\s/.test(sql[index])) {
-            throw new Error('Only one SQL statement can be executed.');
+            throw new KtxQueryError('Only one SQL statement can be executed.');
         }
         index += 1;
     }
@@ -85,11 +86,148 @@ function assertSingleSqlStatement(sql) {
 export function assertReadOnlySql(sql) {
     const trimmed = stripLeadingSqlComments(sql).trim();
     if (!READ_SQL.test(trimmed) || MUTATING_SQL.test(trimmed)) {
-        throw new Error('Only read-only SELECT/WITH queries can be executed locally.');
+        throw new KtxQueryError('Only read-only SELECT/WITH queries can be executed locally.');
     }
     assertSingleSqlStatement(trimmed);
     return trimmed;
 }
+function isSqlIdentifierPart(char) {
+    return char !== undefined && /[A-Za-z0-9_$]/.test(char);
+}
+function keywordAt(sql, index, keyword) {
+    if (sql.slice(index, index + keyword.length).toLowerCase() !== keyword.toLowerCase()) {
+        return false;
+    }
+    return !isSqlIdentifierPart(sql[index - 1]) && !isSqlIdentifierPart(sql[index + keyword.length]);
+}
+function skipWhitespaceAndComments(sql, index) {
+    let current = index;
+    while (current < sql.length) {
+        while (/\s/.test(sql[current] ?? '')) {
+            current += 1;
+        }
+        if (sql.startsWith('--', current) || sql.startsWith('/*', current)) {
+            current = skipQuotedOrComment(sql, current);
+            continue;
+        }
+        return current;
+    }
+    return current;
+}
+function skipBracketIdentifier(sql, index) {
+    let current = index + 1;
+    while (current < sql.length) {
+        if (sql[current] === ']') {
+            if (sql[current + 1] === ']') {
+                current += 2;
+                continue;
+            }
+            return current + 1;
+        }
+        current += 1;
+    }
+    return -1;
+}
+function skipBacktickIdentifier(sql, index) {
+    let current = index + 1;
+    while (current < sql.length) {
+        if (sql[current] === '`') {
+            if (sql[current + 1] === '`') {
+                current += 2;
+                continue;
+            }
+            return current + 1;
+        }
+        current += 1;
+    }
+    return -1;
+}
+function skipIdentifier(sql, index) {
+    if (sql[index] === '"') {
+        const skipped = skipQuotedOrComment(sql, index);
+        return skipped > index ? skipped : -1;
+    }
+    if (sql[index] === '[') {
+        return skipBracketIdentifier(sql, index);
+    }
+    if (sql[index] === '`') {
+        return skipBacktickIdentifier(sql, index);
+    }
+    let current = index;
+    while (isSqlIdentifierPart(sql[current])) {
+        current += 1;
+    }
+    return current > index ? current : -1;
+}
+function skipBalancedParentheses(sql, index) {
+    if (sql[index] !== '(') {
+        return -1;
+    }
+    let current = index;
+    let depth = 0;
+    while (current < sql.length) {
+        const skipped = skipQuotedOrComment(sql, current);
+        if (skipped > current) {
+            current = skipped;
+            continue;
+        }
+        if (sql[current] === '(') {
+            depth += 1;
+        }
+        else if (sql[current] === ')') {
+            depth -= 1;
+            if (depth === 0) {
+                return current + 1;
+            }
+        }
+        current += 1;
+    }
+    return -1;
+}
+/** @internal */
+export function hoistLeadingCte(sql) {
+    const trimmed = sql.trim();
+    if (!keywordAt(trimmed, 0, 'with')) {
+        return { withPrefix: '', body: sql };
+    }
+    let current = skipWhitespaceAndComments(trimmed, 4);
+    if (keywordAt(trimmed, current, 'recursive')) {
+        current = skipWhitespaceAndComments(trimmed, current + 'recursive'.length);
+    }
+    while (current < trimmed.length) {
+        current = skipIdentifier(trimmed, current);
+        if (current < 0) {
+            return { withPrefix: '', body: trimmed };
+        }
+        current = skipWhitespaceAndComments(trimmed, current);
+        if (trimmed[current] === '(') {
+            current = skipBalancedParentheses(trimmed, current);
+            if (current < 0) {
+                return { withPrefix: '', body: trimmed };
+            }
+            current = skipWhitespaceAndComments(trimmed, current);
+        }
+        if (!keywordAt(trimmed, current, 'as')) {
+            return { withPrefix: '', body: trimmed };
+        }
+        current = skipWhitespaceAndComments(trimmed, current + 2);
+        current = skipBalancedParentheses(trimmed, current);
+        if (current < 0) {
+            return { withPrefix: '', body: trimmed };
+        }
+        current = skipWhitespaceAndComments(trimmed, current);
+        if (trimmed[current] === ',') {
+            current = skipWhitespaceAndComments(trimmed, current + 1);
+            continue;
+        }
+        const body = trimmed.slice(current).trimStart();
+        if (!body) {
+            return { withPrefix: '', body: trimmed };
+        }
+        return { withPrefix: `${trimmed.slice(0, current).trimEnd()} `, body };
+    }
+    return { withPrefix: '', body: trimmed };
+}
 // `assertReadOnlySql` deliberately keeps trailing semicolons, comments, and
 // whitespace (e.g. `select 1; -- done`) — harmless for direct single-statement
 // execution. A row-limit subquery wrapper needs a bare expression instead: a
@@ -127,7 +265,8 @@ export function limitSqlForExecution(sql, maxRows) {
         return trimmed;
     }
     if (!Number.isInteger(maxRows) || maxRows <= 0) {
-        throw new Error('maxRows must be a positive integer.');
+        throw new KtxQueryError('maxRows must be a positive integer.');
     }
-    return `select * from (${trimmed}) as ktx_query_result limit ${maxRows}`;
+    const { withPrefix, body } = hoistLeadingCte(trimmed);
+    return `${withPrefix}select * from (${body}) as ktx_query_result limit ${maxRows}`;
 }

package/dist/context/connections/resolve-connection.d.ts

@@ -0,0 +1,12 @@
+import type { KtxProjectConfig, KtxProjectConnectionConfig } from '../project/config.js';
+/**
+ * Look up a connection by id, throwing an expected (caller-driven) error that
+ * names the configured connections so an agent or CLI user can self-correct.
+ */
+export declare function resolveConfiguredConnection(config: KtxProjectConfig, connectionId: string): KtxProjectConnectionConfig;
+/**
+ * Resolve the connection id to run against: validate a requested id against the
+ * configured connections, or default to the sole connection when none is given.
+ * Throws an expected error that lists the configured connections otherwise.
+ */
+export declare function resolveRequiredConnectionId(config: KtxProjectConfig, requested: string | undefined): string;

package/dist/context/connections/resolve-connection.js

@@ -0,0 +1,37 @@
+import { KtxExpectedError } from '../../errors.js';
+function configuredConnectionIds(config) {
+    return Object.keys(config.connections).sort();
+}
+function availableConnectionsHint(config) {
+    const ids = configuredConnectionIds(config);
+    return ids.length === 0
+        ? 'No connections are configured in ktx.yaml.'
+        : `Configured connections: ${ids.join(', ')}.`;
+}
+/**
+ * Look up a connection by id, throwing an expected (caller-driven) error that
+ * names the configured connections so an agent or CLI user can self-correct.
+ */
+export function resolveConfiguredConnection(config, connectionId) {
+    const connection = config.connections[connectionId];
+    if (!connection) {
+        throw new KtxExpectedError(`Connection "${connectionId}" is not configured in ktx.yaml. ${availableConnectionsHint(config)}`);
+    }
+    return connection;
+}
+/**
+ * Resolve the connection id to run against: validate a requested id against the
+ * configured connections, or default to the sole connection when none is given.
+ * Throws an expected error that lists the configured connections otherwise.
+ */
+export function resolveRequiredConnectionId(config, requested) {
+    if (requested !== undefined) {
+        resolveConfiguredConnection(config, requested);
+        return requested;
+    }
+    const ids = configuredConnectionIds(config);
+    if (ids.length === 1) {
+        return ids[0];
+    }
+    throw new KtxExpectedError(`connectionId is required. ${availableConnectionsHint(config)}`);
+}

package/dist/context/core/git-env.d.ts

@@ -6,6 +6,10 @@ import { type SimpleGit } from 'simple-git';
  * directory is an existing repo ktx did not create and the machine has no configured git
  * identity (e.g. a fresh Mac with no ~/.gitconfig), without mutating the user's repo config.
  * Explicit `--author` flags on individual commits still take precedence over GIT_AUTHOR_NAME.
+ *
+ * `commit.gpgsign=false` is injected as a per-invocation `-c` override so ktx's commits never
+ * attempt GPG signing: ktx commits under a synthetic identity that can never own a secret key, so
+ * a user's `commit.gpgsign=true` would otherwise fail every commit with "No secret key".
  */
 export declare function createSimpleGit(baseDir: string, identity?: {
     name: string;

package/dist/context/core/git-env.js

@@ -28,6 +28,10 @@ function sanitizedGitEnv(env = process.env) {
  * directory is an existing repo ktx did not create and the machine has no configured git
  * identity (e.g. a fresh Mac with no ~/.gitconfig), without mutating the user's repo config.
  * Explicit `--author` flags on individual commits still take precedence over GIT_AUTHOR_NAME.
+ *
+ * `commit.gpgsign=false` is injected as a per-invocation `-c` override so ktx's commits never
+ * attempt GPG signing: ktx commits under a synthetic identity that can never own a secret key, so
+ * a user's `commit.gpgsign=true` would otherwise fail every commit with "No secret key".
  */
 export function createSimpleGit(baseDir, identity) {
     const env = sanitizedGitEnv();
@@ -37,5 +41,5 @@ export function createSimpleGit(baseDir, identity) {
         env.GIT_COMMITTER_NAME = identity.name;
         env.GIT_COMMITTER_EMAIL = identity.email;
     }
-    return simpleGit({ baseDir, unsafe: { allowUnsafeAskPass: true } }).env(env);
+    return simpleGit({ baseDir, config: ['commit.gpgsign=false'], unsafe: { allowUnsafeAskPass: true } }).env(env);
 }

package/dist/context/ingest/adapters/live-database/manifest.d.ts

@@ -56,11 +56,14 @@ export interface BuildLiveDatabaseManifestShardsInput {
     existingPreservedJoins?: Map<string, LiveDatabaseManifestJoinEntry[]>;
     existingDescriptions?: Map<string, LiveDatabaseManifestExistingDescriptions>;
     existingUsage?: Map<string, TableUsageOutput>;
+    federatedSiblingTargets?: Set<string>;
 }
 export interface BuildLiveDatabaseManifestShardsResult {
     shards: Map<string, LiveDatabaseManifestShard>;
     tablesProcessed: number;
 }
 export declare function mergeUsagePreservingExternal(existing: TableUsageOutput | undefined, incoming: TableUsageOutput | undefined): TableUsageOutput | undefined;
+/** @internal */
+export declare function buildJoinsByTable(tableNames: Set<string>, joins: LiveDatabaseManifestJoinData[], preservedJoins: Map<string, LiveDatabaseManifestJoinEntry[]>, federatedSiblingTargets?: Set<string>): Map<string, LiveDatabaseManifestJoinEntry[]>;
 export declare function buildLiveDatabaseManifestShards(input: BuildLiveDatabaseManifestShardsInput): BuildLiveDatabaseManifestShardsResult;
 export {};

package/dist/context/ingest/adapters/live-database/manifest.js

@@ -106,10 +106,14 @@ function joinCondition(leftTable, leftColumns, rightTable, rightColumns) {
     })
         .join(' AND ');
 }
-function buildJoinsByTable(tableNames, joins, preservedJoins) {
+/** @internal */
+export function buildJoinsByTable(tableNames, joins, preservedJoins, federatedSiblingTargets = new Set()) {
     const joinsByTable = new Map();
     for (const join of joins) {
-        if (!tableNames.has(join.fromTable) || !tableNames.has(join.toTable)) {
+        const fromLocal = tableNames.has(join.fromTable);
+        const toLocal = tableNames.has(join.toTable);
+        const toSibling = federatedSiblingTargets.has(join.toTable);
+        if (!fromLocal || (!toLocal && !toSibling)) {
             continue;
         }
         const relationship = RELATIONSHIP_MAP[join.relationship] ?? join.relationship;
@@ -119,20 +123,24 @@ function buildJoinsByTable(tableNames, joins, preservedJoins) {
             relationship,
             source: join.source,
         });
-        const reverseRelationship = RELATIONSHIP_INVERSE[relationship] ?? 'one_to_many';
-        addJoinOnce(joinsByTable, join.toTable, {
-            to: join.fromTable,
-            on: joinCondition(join.toTable, join.toColumns, join.fromTable, join.fromColumns),
-            relationship: reverseRelationship,
-            source: join.source,
-        });
+        // Reverse direction only when the target is a local table in THIS snapshot;
+        // a federated sibling has no shard here, so it gets no reverse entry.
+        if (toLocal) {
+            const reverseRelationship = RELATIONSHIP_INVERSE[relationship] ?? 'one_to_many';
+            addJoinOnce(joinsByTable, join.toTable, {
+                to: join.fromTable,
+                on: joinCondition(join.toTable, join.toColumns, join.fromTable, join.fromColumns),
+                relationship: reverseRelationship,
+                source: join.source,
+            });
+        }
     }
     for (const [tableName, tableJoins] of preservedJoins) {
         if (!tableNames.has(tableName)) {
             continue;
         }
         for (const join of tableJoins) {
-            if (tableNames.has(join.to)) {
+            if (tableNames.has(join.to) || federatedSiblingTargets.has(join.to)) {
                 addJoinOnce(joinsByTable, tableName, join);
             }
         }
@@ -141,7 +149,7 @@ function buildJoinsByTable(tableNames, joins, preservedJoins) {
 }
 export function buildLiveDatabaseManifestShards(input) {
     const tableNames = new Set(input.tables.map((table) => table.name));
-    const joinsByTable = buildJoinsByTable(tableNames, input.joins, input.existingPreservedJoins ?? new Map());
+    const joinsByTable = buildJoinsByTable(tableNames, input.joins, input.existingPreservedJoins ?? new Map(), input.federatedSiblingTargets ?? new Set());
     const shards = new Map();
     for (const table of input.tables) {
         const shardKey = getShardKey(input.connectionType, table.catalog, table.db);

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

@@ -89,7 +89,23 @@ function assertInitIsolation(message, allowedToolIds, expectedMcpServerNames) {
 function expectedMcpServerNames(tools) {
     return tools && Object.keys(tools).length > 0 ? new Set([KTX_MCP_SERVER_NAME]) : new Set();
 }
-const CLAUDE_RATE_LIMIT_ERROR_MARKERS = /\b429\b|rate limit|too many requests|quota exceeded|overloaded|max_retries/i;
+// "session limit" is the Claude Code subscription cap ("You've hit your session
+// limit · resets …"); the rest are transient 429-style throttling. All mean
+// Claude Code authenticated successfully, so they must not be read as auth
+// failures by the governor classifier or the auth probe.
+const CLAUDE_RATE_LIMIT_ERROR_MARKERS = /\b429\b|rate limit|session limit|usage limit|too many requests|quota exceeded|overloaded|max_retries/i;
+// The subscription cap is its own case: re-authenticating and retrying both fail
+// until reset, so it gets a distinct message from transient rate limiting.
+const CLAUDE_SESSION_LIMIT_MARKERS = /session limit|usage limit/i;
+function describeClaudeProbeFailure(message) {
+    if (CLAUDE_SESSION_LIMIT_MARKERS.test(message)) {
+        return `Claude Code session limit reached. Wait for the reset shown, then rerun setup or the command. Details: ${message}`;
+    }
+    if (CLAUDE_RATE_LIMIT_ERROR_MARKERS.test(message)) {
+        return `Claude Code is rate limited. Retry shortly, then rerun setup or the command. Details: ${message}`;
+    }
+    return `Claude Code authentication is not usable. Authenticate Claude Code locally with the Claude Code CLI, then rerun setup or the command. ${message}`;
+}
 function normalizeClaudeResetAtMs(value) {
     if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
         return Math.round(value < 10_000_000_000 ? value * 1_000 : value);
@@ -402,7 +418,7 @@ export async function runClaudeCodeAuthProbe(input) {
         const message = error instanceof Error ? error.message : String(error);
         return {
             ok: false,
-            message: `Claude Code authentication is not usable. Authenticate Claude Code locally with the Claude Code CLI, then rerun setup or the command. ${message}`,
+            message: describeClaudeProbeFailure(message),
         };
     }
 }

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

@@ -2,7 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 import { emitTelemetryEvent, mcpTelemetrySampleRate, reportException, shouldEmitMcpTelemetry, } from '../../telemetry/index.js';
 import { collectTelemetryRedactionSecrets } from '../../telemetry/redaction-secrets.js';
-import { scrubErrorClass } from '../../telemetry/scrubber.js';
+import { formatErrorDetail, scrubErrorClass } from '../../telemetry/scrubber.js';
 const connectionIdSchema = z.string().min(1);
 const unknownRecordSchema = z.record(z.string(), z.unknown());
 const tableRefSchema = z.object({
@@ -24,7 +24,7 @@ const toolAnnotations = {
     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.',
+    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_read: 'Read a ktx wiki page by key returned from wiki_search. Example: wiki_read({ key: "global/revenue" }).',
@@ -160,6 +160,8 @@ const connectionListOutputSchema = z.object({
         id: z.string(),
         name: z.string(),
         connectionType: z.string(),
+        members: z.array(z.string()).optional(),
+        hint: z.string().optional(),
     })),
 });
 const wikiSearchOutputSchema = z.object({
@@ -442,6 +444,25 @@ function clientTelemetryFields(getClientInfo) {
         ...(client?.version ? { mcpClientVersion: client.version } : {}),
     };
 }
+// 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
+// reads) so the outcome event is self-diagnosing.
+function mcpErrorResultDetail(result) {
+    if (typeof result !== 'object' || result === null || !('content' in result)) {
+        return undefined;
+    }
+    const content = result.content;
+    if (!Array.isArray(content)) {
+        return undefined;
+    }
+    const text = content
+        .map((block) => typeof block === 'object' && block !== null && typeof block.text === 'string'
+        ? block.text
+        : '')
+        .join('\n');
+    return formatErrorDetail(text);
+}
 function instrumentMcpServer(server, telemetry) {
     return {
         registerTool(name, config, handler) {
@@ -451,6 +472,7 @@ function instrumentMcpServer(server, telemetry) {
                     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 errorDetail = isError ? mcpErrorResultDetail(result) : undefined;
                         await emitTelemetryEvent({
                             name: 'mcp_request_completed',
                             projectDir: telemetry.projectDir,
@@ -460,6 +482,7 @@ function instrumentMcpServer(server, telemetry) {
                                 outcome: isError ? 'error' : 'ok',
                                 durationMs: Math.max(0, performance.now() - startedAt),
                                 sampleRate: mcpTelemetrySampleRate(),
+                                ...(errorDetail ? { errorDetail } : {}),
                                 ...clientTelemetryFields(telemetry.getClientInfo),
                             },
                         });
@@ -483,6 +506,7 @@ function instrumentMcpServer(server, telemetry) {
                     }
                     if (telemetry.io && telemetry.projectDir && shouldEmitMcpTelemetry()) {
                         const errorClass = scrubErrorClass(error);
+                        const errorDetail = formatErrorDetail(error);
                         await emitTelemetryEvent({
                             name: 'mcp_request_completed',
                             projectDir: telemetry.projectDir,
@@ -491,6 +515,7 @@ function instrumentMcpServer(server, telemetry) {
                                 toolName: name,
                                 outcome: 'error',
                                 ...(errorClass ? { errorClass } : {}),
+                                ...(errorDetail ? { errorDetail } : {}),
                                 durationMs: Math.max(0, performance.now() - startedAt),
                                 sampleRate: mcpTelemetrySampleRate(),
                                 ...clientTelemetryFields(telemetry.getClientInfo),

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

@@ -1,5 +1,8 @@
-import { KtxQueryError, isNativeProgrammingFault } from '../../errors.js';
-import { localConnectionInfoFromConfig } from '../../context/connections/local-warehouse-descriptor.js';
+import { KtxExpectedError, KtxQueryError, isNativeProgrammingFault } from '../../errors.js';
+import { executeProjectReadOnlySql } from '../../context/connections/project-sql-executor.js';
+import { FEDERATED_CONNECTION_ID, federatedConnectionListing } from '../../context/connections/federation.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';
 import { createKtxDiscoverDataService } from '../../context/search/discover.js';
 import { sqlAnalysisDialectForDriver } from '../../context/sql-analysis/dialect.js';
@@ -8,75 +11,77 @@ import { createKtxDictionarySearchService } from '../../context/sl/dictionary-se
 import { readLocalSlSource } from '../../context/sl/local-sl.js';
 import { assertSafeConnectionId } from '../../context/sl/source-files.js';
 import { readLocalKnowledgePage, searchLocalKnowledgePages } from '../wiki/local-knowledge.js';
-async function cleanupConnector(connector) {
-    if (connector?.cleanup) {
-        await connector.cleanup();
-    }
-}
 async function executeValidatedReadOnlySql(project, options, input, onProgress) {
     await onProgress?.({ progress: 0, message: 'Validating SQL' });
-    const connectionId = assertSafeConnectionId(input.connectionId);
-    const connection = project.config.connections[connectionId];
-    if (!connection) {
-        throw new Error(`Connection "${connectionId}" is not configured in ktx.yaml`);
-    }
     if (!options.sqlAnalysis) {
         throw new Error('sql_execution requires parser-backed SQL validation.');
     }
-    const validation = await options.sqlAnalysis.validateReadOnly(input.sql, sqlAnalysisDialectForDriver(connection.driver));
-    if (!validation.ok) {
-        throw new Error(validation.error ?? 'SQL is not read-only.');
-    }
     const createConnector = options.localScan?.createConnector;
     if (!createConnector) {
         throw new Error('sql_execution requires a local scan connector factory.');
     }
-    let connector = null;
-    try {
-        connector = await createConnector(connectionId);
-        if (!connector.capabilities.readOnlySql || !connector.executeReadOnly) {
-            throw new Error(`Connection "${connectionId}" does not support read-only SQL execution.`);
-        }
-        await onProgress?.({ progress: 0.3, message: 'Executing' });
-        const result = await connector
-            .executeReadOnly({
+    const isFederated = input.connectionId === FEDERATED_CONNECTION_ID;
+    const connectionId = isFederated ? input.connectionId : assertSafeConnectionId(input.connectionId);
+    const connection = isFederated ? undefined : resolveConfiguredConnection(project.config, connectionId);
+    const dialect = sqlAnalysisDialectForDriver(isFederated ? 'duckdb' : connection.driver);
+    const validation = await options.sqlAnalysis.validateReadOnly(input.sql, dialect);
+    if (!validation.ok) {
+        // A read-only guard rejecting the agent's SQL is an expected outcome, not a
+        // ktx fault: classify it so reportException keeps it out of Error Tracking.
+        throw new KtxQueryError(validation.error ?? 'SQL is not read-only.');
+    }
+    await onProgress?.({ progress: 0.3, message: 'Executing' });
+    const result = await executeProjectReadOnlySql({
+        project,
+        input: {
             connectionId,
+            projectDir: project.projectDir,
+            connection,
             sql: input.sql,
             maxRows: input.maxRows,
-        }, { runId: 'mcp-sql-execution' })
-            .catch((error) => {
-            // A warehouse/driver rejection (e.g. the agent's SQL failed to compile)
-            // is a surfaced operational outcome, not a ktx fault: mark it expected
-            // while preserving the warehouse's own diagnostics. A native JS error
-            // (TypeError, etc.) signals a bug in connector code — let it propagate
-            // unchanged so Error Tracking still sees it.
-            if (isNativeProgrammingFault(error)) {
-                throw error;
-            }
-            throw new KtxQueryError(error instanceof Error ? error.message : String(error), { cause: error });
-        });
-        const response = {
-            headers: result.headers,
-            ...(result.headerTypes ? { headerTypes: result.headerTypes } : {}),
-            rows: result.rows,
-            rowCount: result.rowCount ?? result.rows.length,
-        };
-        await onProgress?.({ progress: 1, message: `Fetched ${response.rowCount} rows` });
-        return response;
-    }
-    finally {
-        await cleanupConnector(connector);
-    }
+        },
+        createConnector,
+        runId: 'mcp-sql-execution',
+    }).catch((error) => {
+        // A warehouse/driver rejection (e.g. the agent's SQL failed to compile) is a
+        // surfaced operational outcome, not a ktx fault: mark it expected while
+        // preserving the warehouse's own diagnostics. A native JS error (TypeError,
+        // etc.) signals a bug in connector code — let it propagate unchanged so Error
+        // Tracking still sees it.
+        if (isNativeProgrammingFault(error) || error instanceof KtxExpectedError) {
+            throw error;
+        }
+        throw new KtxQueryError(error instanceof Error ? error.message : String(error), { cause: error });
+    });
+    const response = {
+        headers: result.headers,
+        ...(result.headerTypes ? { headerTypes: result.headerTypes } : {}),
+        rows: result.rows,
+        rowCount: result.rowCount ?? result.rows.length,
+    };
+    await onProgress?.({ progress: 1, message: `Fetched ${response.rowCount} rows` });
+    return response;
 }
 export function createLocalProjectMcpContextPorts(project, options) {
     const embeddingService = options.embeddingService;
     const ports = {
         connections: {
             async list() {
-                return Object.entries(project.config.connections)
+                const configured = Object.entries(project.config.connections)
                     .map(([id, config]) => localConnectionInfoFromConfig(id, config))
                     .filter((connection) => connection !== null)
                     .sort((a, b) => a.id.localeCompare(b.id));
+                const federated = federatedConnectionListing(project.config.connections, project.projectDir);
+                if (federated) {
+                    configured.push({
+                        id: federated.id,
+                        name: federated.id,
+                        connectionType: 'DUCKDB',
+                        members: federated.members,
+                        hint: federated.hint,
+                    });
+                }
+                return configured;
             },
         },
         knowledge: {

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

@@ -68,6 +68,8 @@ interface KtxConnectionSummary {
     id: string;
     name: string;
     connectionType: string;
+    members?: string[];
+    hint?: string;
 }
 interface KtxConnectionsMcpPort {
     list(): Promise<KtxConnectionSummary[]>;