@kaelio/ktx 0.0.0 → 0.1.0-rc.0

package/dist/serve.d.ts

@@ -0,0 +1,51 @@
+import { type KtxSqlQueryExecutorPort } from '@ktx/context/connections';
+import { type KtxSemanticLayerComputePort } from '@ktx/context/daemon';
+import { type LocalIngestMcpOptions } from '@ktx/context/ingest';
+import { createDefaultKtxMcpServer, type KtxMcpContextPorts } from '@ktx/context/mcp';
+import { createLocalProjectMemoryCapture } from '@ktx/context/memory';
+import { type KtxLocalProject, loadKtxProject } from '@ktx/context/project';
+import type { LocalScanMcpOptions } from '@ktx/context/scan';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import type { KtxCliIo } from './cli-runtime.js';
+import { createKtxCliLocalIngestAdapters } from './local-adapters.js';
+import { createManagedPythonSemanticLayerComputePort, type KtxManagedPythonInstallPolicy } from './managed-python-command.js';
+export interface KtxServeArgs {
+    mcp: 'stdio';
+    projectDir: string;
+    userId: string;
+    semanticCompute: boolean;
+    semanticComputeUrl?: string;
+    databaseIntrospectionUrl?: string;
+    executeQueries: boolean;
+    memoryCapture: boolean;
+    memoryModel?: string;
+    cliVersion?: string;
+    runtimeInstallPolicy?: KtxManagedPythonInstallPolicy;
+}
+interface KtxServeIo {
+    stderr: {
+        write(chunk: string): void;
+    };
+}
+interface LocalProjectContextToolOptions {
+    semanticLayerCompute?: KtxSemanticLayerComputePort;
+    queryExecutor?: KtxSqlQueryExecutorPort;
+    localIngest?: LocalIngestMcpOptions;
+    localScan?: LocalScanMcpOptions;
+}
+interface KtxServeDeps {
+    loadProject?: typeof loadKtxProject;
+    createContextTools?: (project: KtxLocalProject, options?: LocalProjectContextToolOptions) => KtxMcpContextPorts;
+    createSemanticLayerCompute?: () => KtxSemanticLayerComputePort;
+    createManagedSemanticLayerCompute?: typeof createManagedPythonSemanticLayerComputePort;
+    managedRuntimeIo?: KtxCliIo;
+    createHttpSemanticLayerCompute?: (baseUrl: string) => KtxSemanticLayerComputePort;
+    createIngestAdapters?: typeof createKtxCliLocalIngestAdapters;
+    createQueryExecutor?: () => KtxSqlQueryExecutorPort;
+    createMemoryCapture?: typeof createLocalProjectMemoryCapture;
+    createServer?: typeof createDefaultKtxMcpServer;
+    createTransport?: () => StdioServerTransport;
+    stderr?: KtxServeIo['stderr'];
+}
+export declare function runKtxServeStdio(args: KtxServeArgs, deps?: KtxServeDeps): Promise<number>;
+export {};

package/dist/serve.js

@@ -0,0 +1,102 @@
+import { createLocalKtxLlmProviderFromConfig } from '@ktx/context';
+import { createDefaultLocalQueryExecutor } from '@ktx/context/connections';
+import { createHttpSemanticLayerComputePort, } from '@ktx/context/daemon';
+import { createDefaultKtxMcpServer, createLocalProjectMcpContextPorts, } from '@ktx/context/mcp';
+import { createLocalProjectMemoryCapture } from '@ktx/context/memory';
+import { loadKtxProject } from '@ktx/context/project';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createKtxCliLocalIngestAdapters } from './local-adapters.js';
+import { createKtxCliScanConnector } from './local-scan-connectors.js';
+import { createManagedPythonSemanticLayerComputePort, } from './managed-python-command.js';
+import { profileMark } from './startup-profile.js';
+profileMark('module:serve');
+function requiredManagedRuntimeCliVersion(args) {
+    if (!args.cliVersion) {
+        throw new Error('Managed Python semantic compute requires a CLI version.');
+    }
+    return args.cliVersion;
+}
+function managedDaemonOptionsForServe(args, deps) {
+    if (args.databaseIntrospectionUrl || !args.cliVersion) {
+        return undefined;
+    }
+    return {
+        cliVersion: args.cliVersion,
+        installPolicy: args.runtimeInstallPolicy ?? 'prompt',
+        io: deps.managedRuntimeIo ?? process,
+    };
+}
+async function createServeSemanticLayerCompute(args, deps) {
+    if (!args.semanticCompute) {
+        return undefined;
+    }
+    if (args.semanticComputeUrl) {
+        return (deps.createHttpSemanticLayerCompute ?? ((baseUrl) => createHttpSemanticLayerComputePort({ baseUrl })))(args.semanticComputeUrl);
+    }
+    if (deps.createSemanticLayerCompute) {
+        return deps.createSemanticLayerCompute();
+    }
+    const createManagedSemanticLayerCompute = deps.createManagedSemanticLayerCompute ?? createManagedPythonSemanticLayerComputePort;
+    return createManagedSemanticLayerCompute({
+        cliVersion: requiredManagedRuntimeCliVersion(args),
+        installPolicy: args.runtimeInstallPolicy ?? 'prompt',
+        io: deps.managedRuntimeIo ?? process,
+    });
+}
+export async function runKtxServeStdio(args, deps = {}) {
+    const loadProjectFn = deps.loadProject ?? loadKtxProject;
+    const createContextToolsFn = deps.createContextTools ?? createLocalProjectMcpContextPorts;
+    const createServerFn = deps.createServer ?? createDefaultKtxMcpServer;
+    const createTransportFn = deps.createTransport ?? (() => new StdioServerTransport());
+    const stderr = deps.stderr ?? process.stderr;
+    const project = await loadProjectFn({ projectDir: args.projectDir });
+    const semanticLayerCompute = await createServeSemanticLayerCompute(args, deps);
+    const queryExecutor = args.executeQueries
+        ? (deps.createQueryExecutor ?? createDefaultLocalQueryExecutor)()
+        : undefined;
+    const createIngestAdapters = deps.createIngestAdapters ?? createKtxCliLocalIngestAdapters;
+    const managedDaemon = managedDaemonOptionsForServe(args, deps);
+    const localAdapterOptions = {
+        ...(args.databaseIntrospectionUrl ? { databaseIntrospectionUrl: args.databaseIntrospectionUrl } : {}),
+        ...(managedDaemon ? { managedDaemon } : {}),
+    };
+    const localAdapters = createIngestAdapters(project, localAdapterOptions);
+    const llmProvider = args.memoryCapture
+        ? (createLocalKtxLlmProviderFromConfig(project.config.llm) ?? undefined)
+        : undefined;
+    const memoryCapture = args.memoryCapture
+        ? (deps.createMemoryCapture ?? createLocalProjectMemoryCapture)(project, {
+            llmProvider,
+            semanticLayerCompute,
+        })
+        : undefined;
+    const localIngest = {
+        adapters: localAdapters,
+        pullConfigOptions: localAdapterOptions,
+        ...(semanticLayerCompute ? { semanticLayerCompute } : {}),
+        ...(queryExecutor ? { queryExecutor } : {}),
+    };
+    const localScan = {
+        adapters: localAdapters,
+        databaseIntrospectionUrl: args.databaseIntrospectionUrl,
+        createConnector: (connectionId) => createKtxCliScanConnector(project, connectionId),
+    };
+    const contextToolOptions = {
+        localIngest,
+        localScan,
+        ...(semanticLayerCompute ? { semanticLayerCompute } : {}),
+        ...(queryExecutor ? { queryExecutor } : {}),
+    };
+    const contextTools = createContextToolsFn(project, contextToolOptions);
+    const server = createServerFn({
+        name: 'ktx',
+        version: '0.0.0-private',
+        userContext: { userId: args.userId },
+        contextTools,
+        memoryCapture,
+    });
+    const transport = createTransportFn();
+    await server.connect(transport);
+    stderr.write(`ktx MCP server running on stdio for ${project.projectDir}\n`);
+    return 0;
+}

package/dist/serve.test.d.ts

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

package/dist/serve.test.js

@@ -0,0 +1,437 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { initKtxProject } from '@ktx/context/project';
+import { describe, expect, it, vi } from 'vitest';
+import { runKtxServeStdio } from './serve.js';
+function makeManagedRuntimeIo() {
+    let stdout = '';
+    let stderr = '';
+    return {
+        io: {
+            stdout: { write: (chunk) => (stdout += chunk) },
+            stderr: { write: (chunk) => (stderr += chunk) },
+        },
+        stdout: () => stdout,
+        stderr: () => stderr,
+    };
+}
+describe('runKtxServeStdio', () => {
+    it('loads the project, creates local ports, and connects the server to stdio', async () => {
+        const connect = vi.fn().mockResolvedValue(undefined);
+        const project = {
+            projectDir: '/tmp/ktx-project',
+            config: {
+                connections: {},
+                llm: {
+                    provider: { backend: 'gateway' },
+                    models: { default: 'anthropic/claude-sonnet' },
+                },
+            },
+        };
+        const loadProject = vi.fn().mockResolvedValue(project);
+        const contextTools = { connections: { list: vi.fn() } };
+        const createContextTools = vi.fn().mockReturnValue(contextTools);
+        const createServer = vi.fn().mockReturnValue({ connect });
+        const createTransport = vi.fn().mockReturnValue({ kind: 'stdio' });
+        let stderr = '';
+        await expect(runKtxServeStdio({
+            mcp: 'stdio',
+            projectDir: '/tmp/ktx-project',
+            userId: 'agent',
+            semanticCompute: false,
+            semanticComputeUrl: undefined,
+            databaseIntrospectionUrl: undefined,
+            executeQueries: false,
+            memoryCapture: false,
+            memoryModel: undefined,
+        }, {
+            loadProject,
+            createContextTools,
+            createServer,
+            createTransport,
+            stderr: { write: (chunk) => (stderr += chunk) },
+        })).resolves.toBe(0);
+        expect(loadProject).toHaveBeenCalledWith({ projectDir: '/tmp/ktx-project' });
+        expect(createContextTools).toHaveBeenCalledWith(project, expect.objectContaining({
+            localIngest: expect.objectContaining({
+                adapters: expect.any(Array),
+            }),
+            localScan: expect.objectContaining({
+                adapters: expect.any(Array),
+            }),
+        }));
+        expect(createServer).toHaveBeenCalledWith({
+            name: 'ktx',
+            version: '0.0.0-private',
+            userContext: { userId: 'agent' },
+            contextTools,
+            memoryCapture: undefined,
+        });
+        expect(connect).toHaveBeenCalledWith({ kind: 'stdio' });
+        expect(stderr).toContain('ktx MCP server running on stdio for /tmp/ktx-project');
+    });
+    it('enables local ingest ports by default when serving stdio', async () => {
+        const project = { projectDir: '/tmp/ktx-project', config: { connections: {} } };
+        const connect = vi.fn().mockResolvedValue(undefined);
+        const createContextTools = vi.fn(() => ({ connections: { list: async () => [] } }));
+        await expect(runKtxServeStdio({
+            mcp: 'stdio',
+            projectDir: '/tmp/ktx-project',
+            userId: 'agent',
+            semanticCompute: false,
+            semanticComputeUrl: undefined,
+            databaseIntrospectionUrl: undefined,
+            executeQueries: false,
+            memoryCapture: false,
+            memoryModel: undefined,
+        }, {
+            loadProject: async () => project,
+            createContextTools,
+            createServer: vi.fn(() => ({ connect })),
+            createTransport: vi.fn(() => ({})),
+            stderr: { write: vi.fn() },
+        })).resolves.toBe(0);
+        expect(createContextTools).toHaveBeenCalledWith(project, expect.objectContaining({
+            localIngest: expect.objectContaining({
+                adapters: expect.any(Array),
+            }),
+            localScan: expect.objectContaining({
+                adapters: expect.any(Array),
+            }),
+        }));
+    });
+    it('passes daemon database introspection URL to MCP local ingest adapters', async () => {
+        const project = { projectDir: '/tmp/ktx-project', config: { connections: {} } };
+        const connect = vi.fn().mockResolvedValue(undefined);
+        const createContextTools = vi.fn(() => ({ connections: { list: async () => [] } }));
+        const createdAdapters = [];
+        const createIngestAdapters = vi.fn(() => createdAdapters);
+        await expect(runKtxServeStdio({
+            mcp: 'stdio',
+            projectDir: '/tmp/ktx-project',
+            userId: 'agent',
+            semanticCompute: false,
+            semanticComputeUrl: undefined,
+            databaseIntrospectionUrl: 'http://127.0.0.1:8765',
+            executeQueries: false,
+            memoryCapture: false,
+            memoryModel: undefined,
+        }, {
+            loadProject: async () => project,
+            createContextTools,
+            createIngestAdapters,
+            createServer: vi.fn(() => ({ connect })),
+            createTransport: vi.fn(() => ({})),
+            stderr: { write: vi.fn() },
+        })).resolves.toBe(0);
+        expect(createContextTools).toHaveBeenCalledWith(project, expect.objectContaining({
+            localIngest: expect.objectContaining({
+                adapters: expect.any(Array),
+                pullConfigOptions: {
+                    databaseIntrospectionUrl: 'http://127.0.0.1:8765',
+                },
+            }),
+            localScan: expect.objectContaining({
+                adapters: createdAdapters,
+                databaseIntrospectionUrl: 'http://127.0.0.1:8765',
+            }),
+        }));
+        expect(createIngestAdapters).toHaveBeenCalledWith(project, {
+            databaseIntrospectionUrl: 'http://127.0.0.1:8765',
+        });
+    });
+    it('passes managed daemon options to MCP local ingest adapters and pull-config options', async () => {
+        const project = { projectDir: '/tmp/ktx-project', config: { connections: {} } };
+        const adapters = [
+            { source: 'looker', skillNames: [], detect: async () => true, chunk: async () => ({ workUnits: [] }) },
+        ];
+        const createIngestAdapters = vi.fn(() => adapters);
+        const createContextTools = vi.fn(() => ({ connections: { list: async () => [] } }));
+        const managedRuntimeIo = makeManagedRuntimeIo();
+        await expect(runKtxServeStdio({
+            mcp: 'stdio',
+            projectDir: '/tmp/ktx-project',
+            userId: 'agent',
+            semanticCompute: false,
+            semanticComputeUrl: undefined,
+            databaseIntrospectionUrl: undefined,
+            executeQueries: false,
+            memoryCapture: false,
+            memoryModel: undefined,
+            cliVersion: '0.2.0',
+            runtimeInstallPolicy: 'auto',
+        }, {
+            loadProject: async () => project,
+            createContextTools,
+            createIngestAdapters,
+            managedRuntimeIo: managedRuntimeIo.io,
+            createServer: vi.fn(() => ({ connect: vi.fn(async () => undefined) })),
+            createTransport: vi.fn(() => ({})),
+            stderr: { write: vi.fn() },
+        })).resolves.toBe(0);
+        const expectedManagedDaemon = {
+            cliVersion: '0.2.0',
+            installPolicy: 'auto',
+            io: managedRuntimeIo.io,
+        };
+        expect(createIngestAdapters).toHaveBeenCalledWith(project, {
+            managedDaemon: expectedManagedDaemon,
+        });
+        expect(createContextTools).toHaveBeenCalledWith(project, expect.objectContaining({
+            localIngest: expect.objectContaining({
+                adapters,
+                pullConfigOptions: {
+                    managedDaemon: expectedManagedDaemon,
+                },
+            }),
+        }));
+    });
+    it('uses CLI-native local ingest adapters for standalone scan tools', async () => {
+        const project = { projectDir: '/tmp/ktx-project', config: { connections: {} } };
+        const createContextTools = vi.fn(() => ({}));
+        await runKtxServeStdio({
+            mcp: 'stdio',
+            projectDir: '/tmp/ktx-project',
+            userId: 'local',
+            semanticCompute: false,
+            executeQueries: false,
+            memoryCapture: false,
+        }, {
+            loadProject: vi.fn(async () => project),
+            createContextTools,
+            createServer: vi.fn(() => ({ connect: vi.fn(async () => undefined) })),
+            createTransport: vi.fn(() => ({})),
+            stderr: { write: vi.fn() },
+        });
+        expect(createContextTools).toHaveBeenCalledWith(project, expect.objectContaining({
+            localIngest: expect.objectContaining({ adapters: expect.any(Array) }),
+            localScan: expect.objectContaining({ adapters: expect.any(Array) }),
+        }));
+    });
+    it('passes semantic compute to local project ports when enabled', async () => {
+        const tempDir = await mkdtemp(join(tmpdir(), 'ktx-cli-serve-'));
+        try {
+            const project = await initKtxProject({ projectDir: tempDir, projectName: 'warehouse' });
+            const createContextTools = vi.fn(() => ({ connections: { list: async () => [] } }));
+            const semanticLayerCompute = { query: vi.fn(), validateSources: vi.fn(), generateSources: vi.fn() };
+            await expect(runKtxServeStdio({
+                mcp: 'stdio',
+                projectDir: project.projectDir,
+                userId: 'local',
+                semanticCompute: true,
+                semanticComputeUrl: undefined,
+                databaseIntrospectionUrl: undefined,
+                executeQueries: false,
+                memoryCapture: false,
+                memoryModel: undefined,
+            }, {
+                loadProject: async () => project,
+                createContextTools,
+                createSemanticLayerCompute: () => semanticLayerCompute,
+                createServer: vi.fn(() => ({ connect: vi.fn(async () => undefined) })),
+                createTransport: vi.fn(() => ({})),
+                stderr: { write: vi.fn() },
+            })).resolves.toBe(0);
+            expect(createContextTools).toHaveBeenCalledWith(project, expect.objectContaining({
+                semanticLayerCompute,
+                localIngest: expect.objectContaining({
+                    adapters: expect.any(Array),
+                    semanticLayerCompute,
+                }),
+                localScan: expect.objectContaining({
+                    adapters: expect.any(Array),
+                }),
+            }));
+        }
+        finally {
+            await rm(tempDir, { recursive: true, force: true });
+        }
+    });
+    it('uses managed semantic compute when MCP semantic compute has no explicit HTTP URL', async () => {
+        const project = { projectDir: '/tmp/ktx-project', config: { connections: {} } };
+        const semanticLayerCompute = { query: vi.fn(), validateSources: vi.fn(), generateSources: vi.fn() };
+        const createManagedSemanticLayerCompute = vi.fn(async () => semanticLayerCompute);
+        const createContextTools = vi.fn(() => ({ connections: { list: async () => [] } }));
+        const managedRuntimeIo = makeManagedRuntimeIo();
+        await expect(runKtxServeStdio({
+            mcp: 'stdio',
+            projectDir: '/tmp/ktx-project',
+            userId: 'agent',
+            semanticCompute: true,
+            semanticComputeUrl: undefined,
+            databaseIntrospectionUrl: undefined,
+            executeQueries: false,
+            memoryCapture: false,
+            memoryModel: undefined,
+            cliVersion: '0.2.0',
+            runtimeInstallPolicy: 'auto',
+        }, {
+            loadProject: async () => project,
+            createContextTools,
+            createManagedSemanticLayerCompute,
+            managedRuntimeIo: managedRuntimeIo.io,
+            createServer: vi.fn(() => ({ connect: vi.fn(async () => undefined) })),
+            createTransport: vi.fn(() => ({})),
+            stderr: { write: vi.fn() },
+        })).resolves.toBe(0);
+        expect(createManagedSemanticLayerCompute).toHaveBeenCalledWith({
+            cliVersion: '0.2.0',
+            installPolicy: 'auto',
+            io: managedRuntimeIo.io,
+        });
+        expect(createContextTools).toHaveBeenCalledWith(project, expect.objectContaining({
+            semanticLayerCompute,
+        }));
+    });
+    it('uses the HTTP semantic compute port when a daemon URL is provided', async () => {
+        const project = { projectDir: '/tmp/ktx-project', config: { connections: {} } };
+        const semanticLayerCompute = { query: vi.fn(), validateSources: vi.fn(), generateSources: vi.fn() };
+        const createHttpSemanticLayerCompute = vi.fn(() => semanticLayerCompute);
+        const createContextTools = vi.fn(() => ({ connections: { list: async () => [] } }));
+        await expect(runKtxServeStdio({
+            mcp: 'stdio',
+            projectDir: '/tmp/ktx-project',
+            userId: 'agent',
+            semanticCompute: true,
+            semanticComputeUrl: 'http://127.0.0.1:8765',
+            databaseIntrospectionUrl: undefined,
+            executeQueries: false,
+            memoryCapture: false,
+            memoryModel: undefined,
+        }, {
+            loadProject: async () => project,
+            createContextTools,
+            createHttpSemanticLayerCompute,
+            createServer: vi.fn(() => ({ connect: vi.fn(async () => undefined) })),
+            createTransport: vi.fn(() => ({})),
+            stderr: { write: vi.fn() },
+        })).resolves.toBe(0);
+        expect(createHttpSemanticLayerCompute).toHaveBeenCalledWith('http://127.0.0.1:8765');
+        expect(createContextTools).toHaveBeenCalledWith(project, expect.objectContaining({
+            semanticLayerCompute,
+        }));
+    });
+    it('passes a query executor to local project ports only when query execution is enabled', async () => {
+        const project = { projectDir: '/tmp/ktx-project', config: { connections: {} } };
+        const connect = vi.fn().mockResolvedValue(undefined);
+        const createContextTools = vi.fn(() => ({ connections: { list: async () => [] } }));
+        const semanticLayerCompute = { query: vi.fn(), validateSources: vi.fn(), generateSources: vi.fn() };
+        const queryExecutor = { execute: vi.fn() };
+        await expect(runKtxServeStdio({
+            mcp: 'stdio',
+            projectDir: '/tmp/ktx-project',
+            userId: 'agent',
+            semanticCompute: true,
+            semanticComputeUrl: undefined,
+            databaseIntrospectionUrl: undefined,
+            executeQueries: true,
+            memoryCapture: false,
+            memoryModel: undefined,
+        }, {
+            loadProject: async () => project,
+            createContextTools,
+            createSemanticLayerCompute: () => semanticLayerCompute,
+            createQueryExecutor: () => queryExecutor,
+            createServer: vi.fn(() => ({ connect })),
+            createTransport: vi.fn(() => ({})),
+            stderr: { write: vi.fn() },
+        })).resolves.toBe(0);
+        expect(createContextTools).toHaveBeenCalledWith(project, expect.objectContaining({
+            semanticLayerCompute,
+            queryExecutor,
+            localIngest: expect.objectContaining({
+                adapters: expect.any(Array),
+                semanticLayerCompute,
+                queryExecutor,
+            }),
+            localScan: expect.objectContaining({
+                adapters: expect.any(Array),
+            }),
+        }));
+    });
+    it('creates a local memory capture port when memory capture is enabled', async () => {
+        const project = {
+            projectDir: '/tmp/ktx-project',
+            config: {
+                connections: {},
+                llm: {
+                    provider: { backend: 'gateway' },
+                    models: { default: 'anthropic/claude-sonnet' },
+                },
+            },
+        };
+        const connect = vi.fn().mockResolvedValue(undefined);
+        const contextTools = { connections: { list: vi.fn() } };
+        const memoryCapture = { capture: vi.fn(), status: vi.fn() };
+        const createContextTools = vi.fn().mockReturnValue(contextTools);
+        const createMemoryCapture = vi.fn().mockReturnValue(memoryCapture);
+        const createServer = vi.fn().mockReturnValue({ connect });
+        await expect(runKtxServeStdio({
+            mcp: 'stdio',
+            projectDir: '/tmp/ktx-project',
+            userId: 'agent',
+            semanticCompute: false,
+            semanticComputeUrl: undefined,
+            databaseIntrospectionUrl: undefined,
+            executeQueries: false,
+            memoryCapture: true,
+            memoryModel: 'anthropic/claude-sonnet',
+        }, {
+            loadProject: async () => project,
+            createContextTools,
+            createMemoryCapture,
+            createServer,
+            createTransport: vi.fn(() => ({})),
+            stderr: { write: vi.fn() },
+        })).resolves.toBe(0);
+        expect(createMemoryCapture).toHaveBeenCalledWith(project, {
+            llmProvider: expect.objectContaining({ getModel: expect.any(Function) }),
+            semanticLayerCompute: undefined,
+        });
+        expect(createServer).toHaveBeenCalledWith({
+            name: 'ktx',
+            version: '0.0.0-private',
+            userContext: { userId: 'agent' },
+            contextTools,
+            memoryCapture,
+        });
+    });
+    it('reuses semantic compute for local memory capture when enabled', async () => {
+        const project = {
+            projectDir: '/tmp/ktx-project',
+            config: {
+                connections: {},
+                llm: {
+                    provider: { backend: 'gateway' },
+                    models: { default: 'openai/gpt' },
+                },
+            },
+        };
+        const semanticLayerCompute = { query: vi.fn(), validateSources: vi.fn(), generateSources: vi.fn() };
+        const createMemoryCapture = vi.fn().mockReturnValue({ capture: vi.fn(), status: vi.fn() });
+        await expect(runKtxServeStdio({
+            mcp: 'stdio',
+            projectDir: '/tmp/ktx-project',
+            userId: 'agent',
+            semanticCompute: true,
+            semanticComputeUrl: undefined,
+            databaseIntrospectionUrl: undefined,
+            executeQueries: false,
+            memoryCapture: true,
+            memoryModel: 'openai/gpt',
+        }, {
+            loadProject: async () => project,
+            createContextTools: vi.fn(() => ({ connections: { list: async () => [] } })),
+            createSemanticLayerCompute: () => semanticLayerCompute,
+            createMemoryCapture,
+            createServer: vi.fn(() => ({ connect: vi.fn(async () => undefined) })),
+            createTransport: vi.fn(() => ({})),
+            stderr: { write: vi.fn() },
+        })).resolves.toBe(0);
+        expect(createMemoryCapture).toHaveBeenCalledWith(project, {
+            llmProvider: expect.objectContaining({ getModel: expect.any(Function) }),
+            semanticLayerCompute,
+        });
+    });
+});

package/dist/setup-agents.d.ts

@@ -0,0 +1,86 @@
+import type { KtxCliIo } from './cli-runtime.js';
+export type KtxAgentTarget = 'claude-code' | 'codex' | 'cursor' | 'opencode' | 'universal';
+export type KtxAgentScope = 'project' | 'global';
+export type KtxAgentInstallMode = 'cli' | 'mcp' | 'both';
+export interface KtxSetupAgentsArgs {
+    projectDir: string;
+    inputMode: 'auto' | 'disabled';
+    yes: boolean;
+    agents: boolean;
+    target?: KtxAgentTarget;
+    scope: KtxAgentScope;
+    mode: KtxAgentInstallMode;
+    skipAgents: boolean;
+}
+export type KtxSetupAgentsResult = {
+    status: 'ready';
+    projectDir: string;
+    installs: Array<{
+        target: KtxAgentTarget;
+        scope: KtxAgentScope;
+        mode: KtxAgentInstallMode;
+    }>;
+} | {
+    status: 'skipped';
+    projectDir: string;
+} | {
+    status: 'back';
+    projectDir: string;
+} | {
+    status: 'missing-input';
+    projectDir: string;
+} | {
+    status: 'failed';
+    projectDir: string;
+};
+export interface KtxAgentInstallManifest {
+    version: 1;
+    projectDir: string;
+    installedAt: string;
+    installs: Array<{
+        target: KtxAgentTarget;
+        scope: KtxAgentScope;
+        mode: KtxAgentInstallMode;
+    }>;
+    entries: Array<{
+        kind: 'file';
+        path: string;
+    } | {
+        kind: 'json-key';
+        path: string;
+        jsonPath: string[];
+    }>;
+}
+type InstallEntry = KtxAgentInstallManifest['entries'][number];
+export declare function agentInstallManifestPath(projectDir: string): string;
+export declare function plannedKtxAgentFiles(input: {
+    projectDir: string;
+    target: KtxAgentTarget;
+    scope: KtxAgentScope;
+    mode: KtxAgentInstallMode;
+}): InstallEntry[];
+export declare function readKtxAgentInstallManifest(projectDir: string): Promise<KtxAgentInstallManifest | null>;
+export declare function removeKtxAgentInstall(projectDir: string, io: KtxCliIo): Promise<number>;
+export interface KtxSetupAgentsPromptAdapter {
+    select(options: {
+        message: string;
+        options: Array<{
+            value: string;
+            label: string;
+        }>;
+    }): Promise<string>;
+    multiselect(options: {
+        message: string;
+        options: Array<{
+            value: string;
+            label: string;
+        }>;
+        required?: boolean;
+    }): Promise<string[]>;
+    cancel(message: string): void;
+}
+export interface KtxSetupAgentsDeps {
+    prompts?: KtxSetupAgentsPromptAdapter;
+}
+export declare function runKtxSetupAgentsStep(args: KtxSetupAgentsArgs, io: KtxCliIo, deps?: KtxSetupAgentsDeps): Promise<KtxSetupAgentsResult>;
+export {};