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/managed-python-command.ts

@@ -0,0 +1,135 @@
+import { cancel, confirm, isCancel } from '@clack/prompts';
+import { createPythonSemanticLayerComputePort, type KtxSemanticLayerComputePort } from '@ktx/context/daemon';
+import type { KtxCliIo } from './cli-runtime.js';
+import {
+  installManagedPythonRuntime,
+  readManagedPythonRuntimeStatus,
+  type InstalledKtxRuntimeManifest,
+  type KtxRuntimeFeature,
+  type ManagedPythonRuntimeInstallOptions,
+  type ManagedPythonRuntimeInstallResult,
+  type ManagedPythonRuntimeLayout,
+  type ManagedPythonRuntimeLayoutOptions,
+  type ManagedPythonRuntimeStatus,
+} from './managed-python-runtime.js';
+
+export type KtxManagedPythonInstallPolicy = 'prompt' | 'auto' | 'never';
+
+export function runtimeInstallPolicyFromFlags(options: {
+  yes?: boolean;
+  input?: boolean;
+}): KtxManagedPythonInstallPolicy {
+  if (options.yes === true && options.input === false) {
+    throw new Error('Choose only one runtime install mode: --yes or --no-input');
+  }
+  if (options.yes === true) {
+    return 'auto';
+  }
+  return options.input === false ? 'never' : 'prompt';
+}
+
+export interface ManagedPythonCommandRuntime {
+  layout: ManagedPythonRuntimeLayout;
+  manifest: InstalledKtxRuntimeManifest;
+}
+
+export interface ManagedPythonCommandDeps {
+  readStatus?: (options: ManagedPythonRuntimeLayoutOptions) => Promise<ManagedPythonRuntimeStatus>;
+  installRuntime?: (options: ManagedPythonRuntimeInstallOptions) => Promise<ManagedPythonRuntimeInstallResult>;
+  confirmInstall?: (message: string) => Promise<boolean>;
+}
+
+export interface ManagedPythonCommandOptions extends ManagedPythonCommandDeps {
+  cliVersion: string;
+  installPolicy: KtxManagedPythonInstallPolicy;
+  io: KtxCliIo;
+  feature?: KtxRuntimeFeature;
+}
+
+export interface ManagedPythonSemanticLayerComputeOptions extends ManagedPythonCommandOptions {
+  createPythonCompute?: typeof createPythonSemanticLayerComputePort;
+}
+
+export function managedRuntimeInstallCommand(feature: KtxRuntimeFeature): string {
+  return feature === 'local-embeddings'
+    ? 'ktx runtime install --feature local-embeddings --yes'
+    : 'ktx runtime install --yes';
+}
+
+function installPrompt(feature: KtxRuntimeFeature): string {
+  const label = feature === 'local-embeddings' ? 'local embeddings Python runtime' : 'core Python runtime';
+  return `KTX needs to install the ${label}. This downloads Python dependencies with uv. Continue?`;
+}
+
+function runtimeRequiredMessage(feature: KtxRuntimeFeature): string {
+  return `KTX Python runtime is required for this command. Run: ${managedRuntimeInstallCommand(feature)}`;
+}
+
+function hasFeature(manifest: InstalledKtxRuntimeManifest, feature: KtxRuntimeFeature): boolean {
+  return manifest.features.includes(feature);
+}
+
+async function defaultConfirmInstall(message: string): Promise<boolean> {
+  if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
+    return false;
+  }
+  const response = await confirm({ message, initialValue: true });
+  if (isCancel(response)) {
+    cancel('Runtime installation cancelled.');
+    return false;
+  }
+  return response === true;
+}
+
+export async function ensureManagedPythonCommandRuntime(
+  options: ManagedPythonCommandOptions,
+): Promise<ManagedPythonCommandRuntime> {
+  const feature = options.feature ?? 'core';
+  const readStatus = options.readStatus ?? readManagedPythonRuntimeStatus;
+  const installRuntime = options.installRuntime ?? installManagedPythonRuntime;
+  const status = await readStatus({ cliVersion: options.cliVersion });
+
+  if (status.kind === 'ready' && status.manifest && hasFeature(status.manifest, feature)) {
+    return { layout: status.layout, manifest: status.manifest };
+  }
+
+  if (options.installPolicy === 'never') {
+    throw new Error(runtimeRequiredMessage(feature));
+  }
+
+  if (options.installPolicy === 'prompt') {
+    const confirmInstall = options.confirmInstall ?? defaultConfirmInstall;
+    const confirmed = await confirmInstall(installPrompt(feature));
+    if (!confirmed) {
+      throw new Error(`KTX Python runtime installation was cancelled. Run: ${managedRuntimeInstallCommand(feature)}`);
+    }
+  }
+
+  options.io.stderr.write(`Installing KTX Python runtime (${feature}) with uv...\n`);
+  const installed = await installRuntime({
+    cliVersion: options.cliVersion,
+    features: [feature],
+    force: false,
+  });
+  options.io.stderr.write(`KTX Python runtime ready: ${installed.layout.versionDir}\n`);
+  return { layout: installed.layout, manifest: installed.manifest };
+}
+
+export async function createManagedPythonSemanticLayerComputePort(
+  options: ManagedPythonSemanticLayerComputeOptions,
+): Promise<KtxSemanticLayerComputePort> {
+  const runtime = await ensureManagedPythonCommandRuntime({
+    cliVersion: options.cliVersion,
+    installPolicy: options.installPolicy,
+    io: options.io,
+    feature: 'core',
+    ...(options.readStatus ? { readStatus: options.readStatus } : {}),
+    ...(options.installRuntime ? { installRuntime: options.installRuntime } : {}),
+    ...(options.confirmInstall ? { confirmInstall: options.confirmInstall } : {}),
+  });
+  const createPythonCompute = options.createPythonCompute ?? createPythonSemanticLayerComputePort;
+  return createPythonCompute({
+    command: runtime.manifest.python.daemonExecutable,
+    args: [],
+  });
+}