feat: npm-managed Python runtime for @kaelio/ktx (#7)

* docs: add npm managed python runtime design

* build: add bundled python runtime wheel builder

* build: make local embedding dependencies optional

* build: bundle python runtime wheel in cli artifacts

* build: track bundled python runtime release artifact

* test: verify bundled python runtime wheel

* docs: add plan for bundled python runtime wheel

* test: cover managed python runtime lifecycle

* feat: add managed python runtime installer

* feat: add runtime command runner

* feat: expose runtime management commands

* test: verify managed python runtime commands

* docs: add plan for managed python runtime installer

* feat: add managed python command helper

* feat: use managed runtime for sl query compute

* feat: route sl query managed runtime policy

* docs: add plan for managed runtime sl query integration

* feat: add managed runtime daemon metadata

* feat: manage python daemon lifecycle

* feat: add runtime daemon start stop commands

* fix: verify managed runtime daemon lifecycle

* docs: add plan for managed runtime daemon lifecycle

* feat: add managed local embeddings config marker

* feat: add managed local embeddings daemon helper

* feat: use managed runtime for local embedding setup

* feat: pass managed runtime policy through setup

* docs: add plan for managed local embeddings runtime

* feat: read CLI package metadata dynamically

* feat: assemble public kaelio ktx npm package

* feat: release one public kaelio ktx npm artifact

* test: cover public kaelio ktx package invocations

* chore: verify public kaelio ktx package artifacts

* docs: add plan for public kaelio ktx npm package

* test: verify managed runtime in public package smoke

* test: finalize managed runtime release smoke

* docs: add plan for managed runtime release smoke

* test: specify local embeddings release smoke

* feat: add local embeddings runtime smoke

* chore: register local embeddings smoke

* fix: verify local embeddings smoke

* fix: restore artifact smoke python env helper

* docs: add plan for managed local embeddings release smoke

* refactor: share managed runtime install policy parsing

* feat: use managed runtime for agent semantic queries

* feat: use managed runtime for MCP semantic compute

* docs: add plan for managed agent and MCP semantic runtime

* feat(cli): add managed daemon HTTP helpers

* feat(cli): route local adapters through managed daemon

* feat(cli): use managed daemon for ingest helpers

* feat(cli): pass managed daemon options to scan

* feat(context): pass MCP ingest pull config options

* feat(cli): pass managed daemon options to serve ingest

* test: verify managed local ingest daemon runtime

* docs: add plan for managed local ingest daemon runtime

* docs: align managed runtime examples

* docs: add plan for managed runtime docs cleanup

* test: cover published package runtime smoke commands

* test: validate published package smoke outputs

* docs: add plan for published package runtime smoke

* build: stamp public npm package version

* release: add npm public release policy

* release: add guarded npm publish script

* release: document public npm release handoff

* docs: add plan for public npm release handoff

* test: cover managed runtime prune in package smoke

* docs: document managed runtime prune

* docs: add plan for managed runtime prune smoke and docs

* chore: encode uv runtime prerequisite policy

* fix: clarify missing uv runtime error

* docs: document uv runtime prerequisite

* docs: add plan for uv runtime prerequisite contract

* refactor: limit release artifacts to public package runtime

* chore: align release policy with bundled runtime wheel

* docs: describe single public runtime artifact surface

* test: verify single public runtime artifact contract

* docs: add plan for single public runtime artifact cleanup

* fix: align local embeddings smoke with public version

* docs: add plan for local embeddings smoke public version

* release: soft-launch as @kaelio/ktx@0.1.0-rc.0 on next tag

Publish target moves to the pre-release version 0.1.0-rc.0 under the next
dist-tag so npm install @kaelio/ktx (which resolves to latest) does not
pick up the soft-launch build. Users opt in via @kaelio/ktx@next.

* Fix release script boundary checks

* Remove PostHog from public package bundle

packages/cli/src/commands/agent-commands.ts

@@ -2,6 +2,7 @@ import { Option, type Command } from '@commander-js/extra-typings';
 import type { KtxAgentArgs } from '../agent.js';
 import type { KtxCliCommandContext } from '../cli-program.js';
 import { parsePositiveIntegerOption, resolveCommandProjectDir } from '../cli-program.js';
+import { runtimeInstallPolicyFromFlags } from '../managed-python-command.js';
 
 async function runAgent(context: KtxCliCommandContext, args: KtxAgentArgs): Promise<void> {
   const runner = context.deps.agent ?? (await import('../agent.js')).runKtxAgent;
@@ -73,10 +74,19 @@ export function registerAgentCommands(program: Command, context: KtxCliCommandCo
     .requiredOption('--connection-id <id>', 'Connection id for execution')
     .requiredOption('--query-file <path>', 'JSON semantic-layer query file')
     .option('--execute', 'Execute the compiled query against the connection', false)
+    .option('--yes', 'Install the managed Python runtime without prompting when required', false)
+    .option('--no-input', 'Disable interactive managed runtime installation')
     .option('--max-rows <number>', 'Maximum rows to return when executing', parsePositiveIntegerOption)
     .action(
       async (
-        options: { connectionId: string; queryFile: string; execute: boolean; maxRows?: number },
+        options: {
+          connectionId: string;
+          queryFile: string;
+          execute: boolean;
+          maxRows?: number;
+          yes?: boolean;
+          input?: boolean;
+        },
         command,
       ) => {
         await runAgent(context, {
@@ -86,6 +96,8 @@ export function registerAgentCommands(program: Command, context: KtxCliCommandCo
           connectionId: options.connectionId,
           queryFile: options.queryFile,
           execute: options.execute,
+          cliVersion: context.packageInfo.version,
+          runtimeInstallPolicy: runtimeInstallPolicyFromFlags(options),
           ...(options.maxRows !== undefined ? { maxRows: options.maxRows } : {}),
         });
       },

packages/cli/src/commands/ingest-commands.ts

@@ -3,6 +3,7 @@ import { type Command, Option } from '@commander-js/extra-typings';
 import { type KtxCliCommandContext, type OutputModeOptions, resolveCommandProjectDir } from '../cli-program.js';
 import type { KtxCliDeps, KtxCliIo } from '../index.js';
 import type { KtxIngestArgs, KtxIngestOutputMode } from '../ingest.js';
+import { runtimeInstallPolicyFromFlags } from '../managed-python-command.js';
 import { profileMark } from '../startup-profile.js';
 
 profileMark('module:commands/ingest-commands');
@@ -75,6 +76,7 @@ export function registerIngestCommands(
     .addOption(new Option('--plain', 'Print plain text output').conflicts(['json', 'viz']))
     .addOption(new Option('--json', 'Print JSON output').conflicts(['plain', 'viz']))
     .addOption(new Option('--viz', 'Render memory-flow TUI output').conflicts(['plain', 'json']))
+    .option('--yes', 'Install the managed Python runtime without prompting when required', false)
     .option('--no-input', 'Disable interactive terminal input for visualization')
     .action(async (options, command) => {
       if (options.reportFile) {
@@ -89,6 +91,8 @@ export function registerIngestCommands(
           adapter: options.adapter,
           sourceDir: options.sourceDir ? resolve(options.sourceDir) : undefined,
           databaseIntrospectionUrl: options.databaseIntrospectionUrl || undefined,
+          cliVersion: context.packageInfo.version,
+          runtimeInstallPolicy: runtimeInstallPolicyFromFlags(options),
           ...(options.debugLlmRequestFile ? { debugLlmRequestFile: resolve(options.debugLlmRequestFile) } : {}),
           outputMode: outputMode(options),
           ...inputMode(options),

packages/cli/src/commands/runtime-commands.ts

@@ -0,0 +1,100 @@
+import { type Command, Option } from '@commander-js/extra-typings';
+import type { KtxCliCommandContext } from '../cli-program.js';
+import type { KtxRuntimeArgs } from '../runtime.js';
+
+type RuntimeFeature = Extract<KtxRuntimeArgs, { command: 'install' }>['feature'];
+
+function createRuntimeFeatureOption() {
+  return new Option('--feature <feature>', 'Runtime feature level')
+    .choices(['core', 'local-embeddings'])
+    .default('core');
+}
+
+async function runRuntimeArgs(context: KtxCliCommandContext, args: KtxRuntimeArgs): Promise<void> {
+  const runner = context.deps.runtime ?? (await import('../runtime.js')).runKtxRuntime;
+  context.setExitCode(await runner(args, context.io));
+}
+
+export function registerRuntimeCommands(program: Command, context: KtxCliCommandContext): void {
+  const runtime = program
+    .command('runtime')
+    .description('Install, inspect, and prune the KTX-managed Python runtime')
+    .showHelpAfterError();
+
+  runtime
+    .command('install')
+    .description('Install the bundled Python runtime wheel into the managed runtime')
+    .addOption(createRuntimeFeatureOption())
+    .option('--yes', 'Accept runtime installation without prompting', false)
+    .option('--force', 'Reinstall even when the runtime already looks ready', false)
+    .action(async (options: { feature: RuntimeFeature; yes?: boolean; force?: boolean }) => {
+      await runRuntimeArgs(context, {
+        command: 'install',
+        cliVersion: context.packageInfo.version,
+        feature: options.feature,
+        force: options.force === true,
+      });
+    });
+
+  runtime
+    .command('start')
+    .description('Start the KTX-managed Python HTTP daemon')
+    .addOption(createRuntimeFeatureOption())
+    .option('--force', 'Restart even when a matching daemon is already running', false)
+    .action(async (options: { feature: RuntimeFeature; force?: boolean }) => {
+      await runRuntimeArgs(context, {
+        command: 'start',
+        cliVersion: context.packageInfo.version,
+        feature: options.feature,
+        force: options.force === true,
+      });
+    });
+
+  runtime
+    .command('stop')
+    .description('Stop the KTX-managed Python HTTP daemon')
+    .action(async () => {
+      await runRuntimeArgs(context, {
+        command: 'stop',
+        cliVersion: context.packageInfo.version,
+      });
+    });
+
+  runtime
+    .command('status')
+    .description('Show managed Python runtime status')
+    .option('--json', 'Print JSON output', false)
+    .action(async (options: { json?: boolean }) => {
+      await runRuntimeArgs(context, {
+        command: 'status',
+        cliVersion: context.packageInfo.version,
+        json: options.json === true,
+      });
+    });
+
+  runtime
+    .command('doctor')
+    .description('Check managed Python runtime prerequisites and installation')
+    .option('--json', 'Print JSON output', false)
+    .action(async (options: { json?: boolean }) => {
+      await runRuntimeArgs(context, {
+        command: 'doctor',
+        cliVersion: context.packageInfo.version,
+        json: options.json === true,
+      });
+    });
+
+  runtime
+    .command('prune')
+    .description('Remove stale managed Python runtimes for older CLI versions')
+    .option('--dry-run', 'List stale runtimes without deleting them', false)
+    .option('--yes', 'Confirm deletion of stale runtime directories', false)
+    .action(async (options: { dryRun?: boolean; yes?: boolean }) => {
+      await runRuntimeArgs(context, {
+        command: 'prune',
+        cliVersion: context.packageInfo.version,
+        dryRun: options.dryRun === true,
+        yes: options.yes === true,
+      });
+    });
+}

packages/cli/src/commands/scan-commands.ts

@@ -1,5 +1,6 @@
 import { type Command, InvalidArgumentError, Option } from '@commander-js/extra-typings';
 import { type KtxCliCommandContext, parsePositiveIntegerOption, resolveCommandProjectDir } from '../cli-program.js';
+import { runtimeInstallPolicyFromFlags } from '../managed-python-command.js';
 import type { KtxScanArgs } from '../scan.js';
 import { profileMark } from '../startup-profile.js';
 
@@ -102,6 +103,8 @@ export function registerScanCommands(program: Command, context: KtxCliCommandCon
     )
     .option('--dry-run', 'Run without writing scan results', false)
     .option('--database-introspection-url <url>', 'Daemon URL for live-database introspection')
+    .option('--yes', 'Install the managed Python runtime without prompting when required', false)
+    .option('--no-input', 'Disable interactive managed runtime installation')
     .showHelpAfterError()
     .addHelpText(
       'after',
@@ -126,6 +129,8 @@ export function registerScanCommands(program: Command, context: KtxCliCommandCon
         detectRelationships: mode === 'relationships',
         dryRun: options.dryRun === true,
         databaseIntrospectionUrl: options.databaseIntrospectionUrl,
+        cliVersion: context.packageInfo.version,
+        runtimeInstallPolicy: runtimeInstallPolicyFromFlags(options),
       });
     });
 

packages/cli/src/commands/serve-commands.ts

@@ -1,5 +1,6 @@
 import { type Command, InvalidArgumentError } from '@commander-js/extra-typings';
 import { type KtxCliCommandContext, resolveCommandProjectDir } from '../cli-program.js';
+import { runtimeInstallPolicyFromFlags } from '../managed-python-command.js';
 import type { KtxServeArgs } from '../serve.js';
 import { profileMark } from '../startup-profile.js';
 
@@ -20,6 +21,8 @@ export function registerServeCommands(program: Command, context: KtxCliCommandCo
     .option('--user-id <id>', 'Local user id', 'local')
     .option('--semantic-compute', 'Enable semantic-layer compute', false)
     .option('--semantic-compute-url <url>', 'HTTP semantic-layer compute URL')
+    .option('--yes', 'Install the managed Python runtime without prompting when required', false)
+    .option('--no-input', 'Disable interactive managed runtime installation')
     .option('--database-introspection-url <url>', 'Daemon URL for live-database introspection')
     .option('--execute-queries', 'Allow semantic-layer query execution', false)
     .option('--memory-capture', 'Enable memory capture', false)
@@ -40,6 +43,8 @@ export function registerServeCommands(program: Command, context: KtxCliCommandCo
         executeQueries: options.executeQueries === true,
         memoryCapture: options.memoryCapture === true,
         memoryModel: options.memoryModel,
+        cliVersion: context.packageInfo.version,
+        runtimeInstallPolicy: runtimeInstallPolicyFromFlags(options),
       };
       const runner = context.deps.serveStdio ?? (await import('../serve.js')).runKtxServeStdio;
       context.setExitCode(await runner(args));

packages/cli/src/commands/setup-commands.ts

@@ -371,6 +371,7 @@ export function registerSetupCommands(program: Command, context: KtxCliCommandCo
       skipAgents: options.skipAgents === true,
       inputMode: options.input === false ? 'disabled' : 'auto',
       yes: options.yes === true,
+      cliVersion: context.packageInfo.version,
       ...(options.anthropicApiKeyEnv ? { anthropicApiKeyEnv: options.anthropicApiKeyEnv } : {}),
       ...(options.anthropicApiKeyFile ? { anthropicApiKeyFile: options.anthropicApiKeyFile } : {}),
       ...(options.anthropicModel ? { anthropicModel: options.anthropicModel } : {}),

packages/cli/src/commands/sl-commands.ts

@@ -6,6 +6,7 @@ import {
   resolveCommandProjectDir,
 } from '../cli-program.js';
 import { slQueryCommandSchema } from '../command-schemas.js';
+import { runtimeInstallPolicyFromFlags } from '../managed-python-command.js';
 import type { KtxSlArgs } from '../sl.js';
 import { profileMark } from '../startup-profile.js';
 
@@ -121,6 +122,8 @@ export function registerSlCommands(program: Command, context: KtxCliCommandConte
     .option('--include-empty', 'Include empty rows', false)
     .addOption(new Option('--format <format>', 'json or sql').choices(['json', 'sql']).default('json'))
     .option('--execute', 'Execute the compiled query', false)
+    .option('--yes', 'Install the managed Python runtime without prompting when required', false)
+    .option('--no-input', 'Disable interactive managed runtime installation')
     .option('--max-rows <n>', 'Maximum rows to return when executing', parsePositiveIntegerOption)
     .action(async (options, command) => {
       if (options.measure.length === 0) {
@@ -141,6 +144,8 @@ export function registerSlCommands(program: Command, context: KtxCliCommandConte
         },
         format: options.format,
         execute: options.execute === true,
+        cliVersion: context.packageInfo.version,
+        runtimeInstallPolicy: runtimeInstallPolicyFromFlags(options),
         ...(options.maxRows !== undefined ? { maxRows: options.maxRows } : {}),
       });
       await runSlArgs(context, args);