@openlucaskaka/kagent 0.1.7

package/npm/lib/python-runner.js

@@ -0,0 +1,892 @@
+"use strict";
+
+const childProcess = require("child_process");
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+
+const { kagentCachePath, resolveKagentHome } = require("./kagent-home");
+
+const TEMP_RUNTIME_STALE_MS = 24 * 60 * 60 * 1000;
+const PYTHON_ENTRYPOINTS = Object.freeze({
+  kagent: "import sys; sys.argv = sys.argv[1:]; from kagent.cli import main; raise SystemExit(main())",
+  "kagent-serve": "import sys; sys.argv = sys.argv[1:]; from kagent.service import main; raise SystemExit(main())"
+});
+const SECURE_FILESYSTEM_HELPER = String.raw`
+import ctypes
+import errno
+import os
+import re
+import secrets
+import stat
+import sys
+
+
+DIRECTORY_FLAGS = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW
+
+
+def fail(message):
+    raise RuntimeError(message)
+
+
+def path_parts(target):
+    if not os.path.isabs(target):
+        fail("managed path must be absolute")
+    normalized = os.path.normpath(target)
+    parts = [part for part in normalized.split(os.sep) if part]
+    if not parts:
+        fail("refusing managed filesystem root")
+    return parts
+
+
+def open_directory(target, create_missing):
+    parts = path_parts(target)
+    current_fd = os.open(os.sep, DIRECTORY_FLAGS)
+    try:
+        for part in parts:
+            try:
+                next_fd = os.open(part, DIRECTORY_FLAGS, dir_fd=current_fd)
+            except FileNotFoundError:
+                if not create_missing:
+                    raise
+                try:
+                    os.mkdir(part, 0o700, dir_fd=current_fd)
+                except FileExistsError:
+                    pass
+                next_fd = os.open(part, DIRECTORY_FLAGS, dir_fd=current_fd)
+            except OSError as error:
+                if error.errno in (errno.ELOOP, errno.ENOTDIR):
+                    fail(f"refusing symbolic link or non-directory in managed path: {target}")
+                raise
+            os.close(current_fd)
+            current_fd = next_fd
+        return current_fd
+    except BaseException:
+        os.close(current_fd)
+        raise
+
+
+def ensure_directory(target):
+    directory_fd = open_directory(target, True)
+    try:
+        if not stat.S_ISDIR(os.fstat(directory_fd).st_mode):
+            fail(f"managed path is not a directory: {target}")
+        os.fchmod(directory_fd, 0o700)
+    finally:
+        os.close(directory_fd)
+
+
+def write_file(target):
+    parent, name = os.path.split(os.path.normpath(target))
+    if not name or name in (".", ".."):
+        fail(f"managed path is not a file: {target}")
+    parent_fd = open_directory(parent, False)
+    file_fd = None
+    try:
+        try:
+            file_fd = os.open(
+                name,
+                os.O_WRONLY | os.O_CREAT | os.O_TRUNC | os.O_NOFOLLOW,
+                0o600,
+                dir_fd=parent_fd,
+            )
+        except OSError as error:
+            if error.errno in (errno.ELOOP, errno.ENOTDIR):
+                fail(f"refusing symbolic link in managed path: {target}")
+            raise
+        if not stat.S_ISREG(os.fstat(file_fd).st_mode):
+            fail(f"managed path is not a file: {target}")
+        os.fchmod(file_fd, 0o600)
+        body = sys.stdin.buffer.read()
+        offset = 0
+        while offset < len(body):
+            offset += os.write(file_fd, body[offset:])
+        os.fchmod(file_fd, 0o600)
+    finally:
+        if file_fd is not None:
+            os.close(file_fd)
+        os.close(parent_fd)
+
+
+def managed_parent(target):
+    parent, name = os.path.split(os.path.normpath(target))
+    if not name or name in (".", ".."):
+        fail(f"managed path has no valid name: {target}")
+    return open_directory(parent, False), name
+
+
+def directory_stat(parent_fd, name, target):
+    try:
+        value = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
+    except FileNotFoundError:
+        return None
+    if stat.S_ISLNK(value.st_mode):
+        fail(f"refusing symbolic link in managed path: {target}")
+    if not stat.S_ISDIR(value.st_mode):
+        fail(f"managed path is not a directory: {target}")
+    return value
+
+
+def validate_directory(target):
+    directory_fd = open_directory(target, False)
+    try:
+        if not stat.S_ISDIR(os.fstat(directory_fd).st_mode):
+            fail(f"managed path is not a directory: {target}")
+    finally:
+        os.close(directory_fd)
+
+
+def create_temp_directory(final_target):
+    parent_fd, final_name = managed_parent(final_target)
+    try:
+        for _attempt in range(100):
+            name = f"t{secrets.token_hex(31)}{secrets.choice('0123456789abcdef')}"
+            try:
+                os.mkdir(name, 0o700, dir_fd=parent_fd)
+            except FileExistsError:
+                continue
+            directory_fd = os.open(name, DIRECTORY_FLAGS, dir_fd=parent_fd)
+            try:
+                os.fchmod(directory_fd, 0o700)
+            finally:
+                os.close(directory_fd)
+            return os.path.join(os.path.dirname(os.path.normpath(final_target)), name)
+        fail(f"unable to allocate temporary runtime directory for {final_target}")
+    finally:
+        os.close(parent_fd)
+
+
+def remove_directory_contents(directory_fd):
+    try:
+        names = os.listdir(directory_fd)
+    except FileNotFoundError:
+        return
+    for name in names:
+        try:
+            value = os.stat(name, dir_fd=directory_fd, follow_symlinks=False)
+        except FileNotFoundError:
+            continue
+        if stat.S_ISDIR(value.st_mode):
+            try:
+                child_fd = os.open(name, DIRECTORY_FLAGS, dir_fd=directory_fd)
+            except FileNotFoundError:
+                continue
+            except OSError as error:
+                if error.errno in (errno.ELOOP, errno.ENOTDIR):
+                    fail(f"temporary runtime directory changed type: {name}")
+                raise
+            try:
+                remove_directory_contents(child_fd)
+            finally:
+                os.close(child_fd)
+            try:
+                os.rmdir(name, dir_fd=directory_fd)
+            except FileNotFoundError:
+                continue
+        else:
+            try:
+                os.unlink(name, dir_fd=directory_fd)
+            except FileNotFoundError:
+                continue
+            except IsADirectoryError:
+                fail(f"temporary runtime entry changed type: {name}")
+
+
+def remove_tree_entry(parent_fd, name, target):
+    try:
+        directory_fd = os.open(name, DIRECTORY_FLAGS, dir_fd=parent_fd)
+    except FileNotFoundError:
+        return
+    except OSError as error:
+        if error.errno in (errno.ELOOP, errno.ENOTDIR):
+            fail(f"refusing symbolic link or non-directory temporary runtime: {target}")
+        raise
+    try:
+        remove_directory_contents(directory_fd)
+    finally:
+        os.close(directory_fd)
+    try:
+        os.rmdir(name, dir_fd=parent_fd)
+    except FileNotFoundError:
+        return
+
+
+def remove_tree(target):
+    parent_fd, name = managed_parent(target)
+    try:
+        remove_tree_entry(parent_fd, name, target)
+    finally:
+        os.close(parent_fd)
+
+
+def cleanup_temp_directories(parent_target, stale_before_ms):
+    parent_fd = open_directory(parent_target, False)
+    try:
+        for name in os.listdir(parent_fd):
+            if re.fullmatch(r"t[0-9a-f]{63}", name) is None:
+                continue
+            target = os.path.join(parent_target, name)
+            try:
+                value = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
+            except FileNotFoundError:
+                continue
+            if stat.S_ISLNK(value.st_mode):
+                fail(f"refusing symbolic link temporary runtime: {target}")
+            if not stat.S_ISDIR(value.st_mode):
+                fail(f"temporary runtime is not a directory: {target}")
+            if value.st_mtime * 1000 >= stale_before_ms:
+                continue
+            remove_tree_entry(parent_fd, name, target)
+    finally:
+        os.close(parent_fd)
+
+
+def rename_no_replace(parent_fd, source_name, target_name, platform_name):
+    libc = ctypes.CDLL(None, use_errno=True)
+    source = os.fsencode(source_name)
+    target = os.fsencode(target_name)
+    if platform_name == "darwin":
+        rename = libc.renameatx_np
+        rename.argtypes = [ctypes.c_int, ctypes.c_char_p, ctypes.c_int, ctypes.c_char_p, ctypes.c_uint]
+        rename.restype = ctypes.c_int
+        result = rename(parent_fd, source, parent_fd, target, 0x00000004)
+    elif platform_name.startswith("linux") and hasattr(libc, "renameat2"):
+        rename = libc.renameat2
+        rename.argtypes = [ctypes.c_int, ctypes.c_char_p, ctypes.c_int, ctypes.c_char_p, ctypes.c_uint]
+        rename.restype = ctypes.c_int
+        result = rename(parent_fd, source, parent_fd, target, 1)
+    else:
+        fail(f"unsupported atomic publish platform: {platform_name}")
+    if result == 0:
+        return True
+    error_number = ctypes.get_errno()
+    if error_number in (errno.EEXIST, errno.ENOTEMPTY):
+        return False
+    raise OSError(error_number, os.strerror(error_number))
+
+
+def publish_directory(temp_target, final_target, platform_name):
+    temp_parent = os.path.dirname(os.path.normpath(temp_target))
+    final_parent = os.path.dirname(os.path.normpath(final_target))
+    if temp_parent != final_parent:
+        fail("temporary and final runtime directories must share a parent")
+    parent_fd = open_directory(final_parent, False)
+    try:
+        temp_name = os.path.basename(temp_target)
+        final_name = os.path.basename(final_target)
+        directory_stat(parent_fd, temp_name, temp_target)
+        if rename_no_replace(parent_fd, temp_name, final_name, platform_name):
+            return "published"
+        directory_stat(parent_fd, final_name, final_target)
+        return "exists"
+    finally:
+        os.close(parent_fd)
+
+
+try:
+    operation, target = sys.argv[1:3]
+    if operation == "ensure-directory":
+        ensure_directory(target)
+    elif operation == "write-file":
+        write_file(target)
+    elif operation == "validate-directory":
+        validate_directory(target)
+    elif operation == "create-temp-directory":
+        sys.stdout.write(create_temp_directory(target))
+    elif operation == "remove-tree":
+        remove_tree(target)
+    elif operation == "cleanup-temp-directories":
+        cleanup_temp_directories(target, int(sys.argv[3]))
+    elif operation == "publish-directory":
+        platform_name = sys.argv[4] if len(sys.argv) > 4 and sys.argv[4] else sys.platform
+        sys.stdout.write(publish_directory(target, sys.argv[3], platform_name))
+    else:
+        fail(f"unsupported secure filesystem operation: {operation}")
+except BaseException as error:
+    sys.stderr.write(f"{error}\n")
+    raise SystemExit(1)
+`;
+
+function packageRoot() {
+  return path.resolve(__dirname, "..", "..");
+}
+
+function readPackageVersion(root) {
+  const packageJsonPath = path.join(root, "package.json");
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+  return packageJson.version;
+}
+
+function maybePrintNodeHandledOutput(commandName, args, version) {
+  if (commandName !== "kagent") {
+    return false;
+  }
+  const versionOutput = versionOutputTarget(args);
+  if (versionOutput === null) {
+    return false;
+  }
+  const body = `${JSON.stringify({ version }, null, 2)}\n`;
+  if (versionOutput) {
+    fs.writeFileSync(versionOutput, body, { encoding: "utf8" });
+  } else {
+    process.stdout.write(body);
+  }
+  return true;
+}
+
+function versionOutputTarget(args) {
+  if (args.length === 1 && args[0] === "--version") {
+    return "";
+  }
+  if (args.length === 3 && args[0] === "--version" && args[1] === "--output") {
+    return args[2];
+  }
+  if (args.length === 3 && args[0] === "--output" && args[2] === "--version") {
+    return args[1];
+  }
+  return null;
+}
+
+function cacheRoot(env = process.env) {
+  if (env.KAGENT_NODE_VENV) {
+    return path.resolve(env.KAGENT_NODE_VENV);
+  }
+  return kagentCachePath("npm-python", env);
+}
+
+function metadataCacheRoot(env = process.env) {
+  return path.dirname(kagentCachePath("npm-python", env));
+}
+
+function updateStatePath(env = process.env) {
+  return path.join(metadataCacheRoot(env), "npm-self-update.json");
+}
+
+function rejectSymlinks(targetPath) {
+  const resolved = path.resolve(targetPath);
+  const parsed = path.parse(resolved);
+  const parts = resolved.slice(parsed.root.length).split(path.sep).filter(Boolean);
+  let current = parsed.root;
+  for (const part of parts) {
+    current = path.join(current, part);
+    let stat;
+    try {
+      stat = fs.lstatSync(current);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return;
+      }
+      throw error;
+    }
+    if (stat.isSymbolicLink()) {
+      throw new Error(`refusing symbolic link in managed path: ${current}`);
+    }
+  }
+}
+
+function ensurePrivateDirectory(directory) {
+  const resolved = path.resolve(directory);
+  runSecureFilesystemOperation("ensure-directory", resolved);
+  return directory;
+}
+
+function ensureCacheRoot(env = process.env) {
+  if (env.KAGENT_NODE_VENV) {
+    return ensurePrivateDirectory(path.resolve(env.KAGENT_NODE_VENV));
+  }
+  const home = ensurePrivateDirectory(resolveKagentHome(env));
+  const cache = ensurePrivateDirectory(path.join(home, "cache"));
+  return ensurePrivateDirectory(path.join(cache, "npm-python"));
+}
+
+function ensureMetadataCacheRoot(env = process.env) {
+  const home = ensurePrivateDirectory(resolveKagentHome(env));
+  return ensurePrivateDirectory(path.join(home, "cache"));
+}
+
+function writePrivateFile(filePath, body) {
+  runSecureFilesystemOperation("write-file", path.resolve(filePath), body);
+}
+
+function assertSupportedPlatform(platform = process.platform) {
+  if (platform !== "darwin" && platform !== "linux") {
+    throw new Error(`kagent npm Python runtime supports only macOS and Linux, not ${platform}`);
+  }
+}
+
+function runSecureFilesystemOperation(operation, targetPath, body = "", extraArgs = []) {
+  assertSupportedPlatform();
+  const python = findPython();
+  const result = childProcess.spawnSync(
+    python,
+    ["-c", SECURE_FILESYSTEM_HELPER, operation, targetPath].concat(extraArgs),
+    {
+      encoding: "utf8",
+      env: process.env,
+      input: body,
+      stdio: ["pipe", "pipe", "pipe"]
+    }
+  );
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    const detail = String(result.stderr || result.stdout || "").trim();
+    const suffix = detail ? `: ${detail.slice(-4000)}` : "";
+    throw new Error(
+      `secure filesystem ${operation} failed for ${targetPath}${suffix}`
+    );
+  }
+  return String(result.stdout || "").trim();
+}
+
+function privateFileStat(filePath) {
+  let stat;
+  try {
+    stat = fs.lstatSync(filePath);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+  if (stat.isSymbolicLink()) {
+    throw new Error(`refusing symbolic link in managed path: ${filePath}`);
+  }
+  if (!stat.isFile()) {
+    throw new Error(`managed path is not a file: ${filePath}`);
+  }
+  return stat;
+}
+
+function validatePrivateDirectory(directory) {
+  runSecureFilesystemOperation("validate-directory", path.resolve(directory));
+}
+
+function createTempRuntime(finalDirectory) {
+  return runSecureFilesystemOperation("create-temp-directory", path.resolve(finalDirectory));
+}
+
+function removeTempRuntime(directory) {
+  runSecureFilesystemOperation("remove-tree", path.resolve(directory));
+}
+
+function cleanupStaleTempRuntimes(parentDirectory, staleMs = TEMP_RUNTIME_STALE_MS) {
+  runSecureFilesystemOperation(
+    "cleanup-temp-directories",
+    path.resolve(parentDirectory),
+    "",
+    [String(Date.now() - staleMs)]
+  );
+}
+
+function publishRuntime(tempDirectory, finalDirectory, platformOverride = "") {
+  return runSecureFilesystemOperation(
+    "publish-directory",
+    path.resolve(tempDirectory),
+    "",
+    [path.resolve(finalDirectory), platformOverride]
+  );
+}
+
+function candidatePythons() {
+  const configured = process.env.KAGENT_PYTHON ? [process.env.KAGENT_PYTHON] : [];
+  return configured.concat(["python3", "python"]);
+}
+
+function commandWorks(command, args) {
+  const result = childProcess.spawnSync(command, args, {
+    encoding: "utf8",
+    stdio: "ignore"
+  });
+  return result.status === 0;
+}
+
+function findPython() {
+  for (const command of candidatePythons()) {
+    if (commandWorks(command, ["-c", "import sys; raise SystemExit(0 if sys.version_info >= (3, 9) else 1)"])) {
+      return command;
+    }
+  }
+  throw new Error("kagent requires Python 3.9+. Install python3 or set KAGENT_PYTHON.");
+}
+
+function runChecked(command, args, options) {
+  const result = childProcess.spawnSync(command, args, {
+    cwd: options.cwd,
+    env: process.env,
+    encoding: "utf8",
+    stdio: options.stdio || "inherit"
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    const detail = [result.stdout, result.stderr]
+      .filter((value) => typeof value === "string" && value.trim())
+      .join("\n")
+      .trim();
+    const suffix = detail ? `\n${detail.slice(-4000)}` : "";
+    throw new Error(
+      `${command} ${args.join(" ")} failed with exit code ${result.status}${suffix}`
+    );
+  }
+}
+
+function readUpdateState(env = process.env) {
+  const statePath = updateStatePath(env);
+  rejectSymlinks(statePath);
+  if (!privateFileStat(statePath)) {
+    return null;
+  }
+  try {
+    const state = JSON.parse(fs.readFileSync(statePath, "utf8"));
+    return state && typeof state === "object" ? state : null;
+  } catch (_error) {
+    return null;
+  }
+}
+
+function writeUpdateState(state, env = process.env) {
+  const statePath = path.join(ensureMetadataCacheRoot(env), "npm-self-update.json");
+  writePrivateFile(statePath, `${JSON.stringify(state, null, 2)}\n`);
+}
+
+function venvPythonPath(venvDir) {
+  if (process.platform === "win32") {
+    return path.join(venvDir, "Scripts", "python.exe");
+  }
+  return path.join(venvDir, "bin", "python");
+}
+
+function markerPath(venvDir) {
+  return path.join(venvDir, ".kagent-node-install.json");
+}
+
+function installMarker(version, dependencyFingerprint, pythonIdentityHash) {
+  return {
+    schema: 1,
+    dependencyHash: dependencyFingerprint,
+    pythonIdentityHash,
+    createdFromVersion: version
+  };
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function projectTable(pyproject) {
+  const match = pyproject.match(/^\s*\[project\]\s*(?:#.*)?$/m);
+  if (!match) {
+    throw new Error("pyproject.toml does not declare [project]");
+  }
+  const bodyStart = match.index + match[0].length;
+  const remaining = pyproject.slice(bodyStart);
+  const nextTable = remaining.search(/^\s*\[/m);
+  return nextTable === -1 ? remaining : remaining.slice(0, nextTable);
+}
+
+function tomlString(value) {
+  if (value.startsWith('"')) {
+    return JSON.parse(value);
+  }
+  return value.slice(1, -1);
+}
+
+function projectString(project, key) {
+  const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = project.match(
+    new RegExp(`^\\s*${escapedKey}\\s*=\\s*("(?:\\\\.|[^"\\\\])*"|'[^']*')\\s*(?:#.*)?$`, "m")
+  );
+  if (!match) {
+    throw new Error(`pyproject.toml [project] does not declare ${key}`);
+  }
+  return tomlString(match[1]);
+}
+
+function projectStringArray(project, key) {
+  const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const assignment = new RegExp(`^\\s*${escapedKey}\\s*=\\s*\\[`, "m").exec(project);
+  if (!assignment) {
+    throw new Error(`pyproject.toml [project] does not declare ${key}`);
+  }
+  const values = [];
+  let index = assignment.index + assignment[0].length;
+  while (index < project.length) {
+    const character = project[index];
+    if (character === "]") {
+      return values;
+    }
+    if (character === "#") {
+      while (index < project.length && project[index] !== "\n") index += 1;
+      continue;
+    }
+    if (character === '"' || character === "'") {
+      const quote = character;
+      const start = index;
+      index += 1;
+      while (index < project.length) {
+        if (quote === '"' && project[index] === "\\") {
+          index += 2;
+          continue;
+        }
+        if (project[index] === quote) {
+          index += 1;
+          values.push(tomlString(project.slice(start, index)));
+          break;
+        }
+        index += 1;
+      }
+      if (project[index - 1] !== quote) {
+        throw new Error(`unterminated string in [project].${key}`);
+      }
+      continue;
+    }
+    index += 1;
+  }
+  throw new Error(`unterminated array in [project].${key}`);
+}
+
+function dependencyHash(root) {
+  const pyproject = fs.readFileSync(path.join(root, "pyproject.toml"), "utf8");
+  const project = projectTable(pyproject);
+  return sha256(JSON.stringify({
+    requiresPython: projectString(project, "requires-python"),
+    dependencies: projectStringArray(project, "dependencies")
+  }));
+}
+
+function readMarker(venvDir) {
+  const pathToMarker = markerPath(venvDir);
+  if (!privateFileStat(pathToMarker)) {
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(pathToMarker, "utf8"));
+  } catch (_error) {
+    return null;
+  }
+}
+
+function markerMatches(actual, expected) {
+  return Boolean(actual) &&
+    actual.schema === expected.schema &&
+    actual.dependencyHash === expected.dependencyHash &&
+    actual.pythonIdentityHash === expected.pythonIdentityHash;
+}
+
+function writeMarker(venvDir, marker) {
+  writePrivateFile(markerPath(venvDir), `${JSON.stringify(marker, null, 2)}\n`);
+}
+
+function pythonRuntimeIdentity(python) {
+  const result = childProcess.spawnSync(
+    python,
+    ["-c", "import json, os, platform, sys, sysconfig; print(json.dumps({'implementation': sys.implementation.name, 'major': sys.version_info[0], 'minor': sys.version_info[1], 'cacheTag': sys.implementation.cache_tag, 'soabi': sysconfig.get_config_var('SOABI'), 'machine': platform.machine(), 'executable': os.path.realpath(sys.executable), 'prefix': os.path.realpath(sys.prefix), 'basePrefix': os.path.realpath(sys.base_prefix), 'execPrefix': os.path.realpath(sys.exec_prefix), 'baseExecPrefix': os.path.realpath(sys.base_exec_prefix)}))"],
+    { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }
+  );
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    throw new Error(`failed to identify Python runtime: ${String(result.stderr || "").trim()}`);
+  }
+  const identity = JSON.parse(result.stdout);
+  if (!/^[A-Za-z0-9_-]+$/.test(identity.implementation) ||
+      identity.implementation.length > 24 ||
+      !Number.isInteger(identity.major) || !Number.isInteger(identity.minor) ||
+      identity.major < 0 || identity.minor < 0) {
+    throw new Error("Python runtime returned an invalid identity");
+  }
+  return identity;
+}
+
+function safeRuntimeComponent(value, label, maxLength) {
+  if (typeof value !== "string" || value.length === 0 || value.length > maxLength ||
+      !/^[A-Za-z0-9_.-]+$/.test(value)) {
+    throw new Error(`invalid ${label} runtime component`);
+  }
+  return value;
+}
+
+function runtimeCacheDirectory(cache, identity, platform, arch, dependencyFingerprint) {
+  const implementation = safeRuntimeComponent(identity.implementation, "implementation", 24);
+  const hostPlatform = safeRuntimeComponent(platform, "platform", 24);
+  const hostArch = safeRuntimeComponent(arch, "architecture", 32);
+  const identityFingerprint = sha256(JSON.stringify(identity));
+  const abi = `${implementation}-${identity.major}.${identity.minor}-${identityFingerprint}`;
+  return path.join(cache, abi, `${hostPlatform}-${hostArch}`, dependencyFingerprint);
+}
+
+function runtimeState(venvDir, expectedMarker, pythonWorks = commandWorks) {
+  let stat;
+  try {
+    stat = fs.lstatSync(venvDir);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return "missing";
+    }
+    throw error;
+  }
+  if (stat.isSymbolicLink()) {
+    throw new Error(`refusing symbolic link in managed path: ${venvDir}`);
+  }
+  if (!stat.isDirectory()) {
+    throw new Error(`invalid cached Python runtime: ${venvDir}`);
+  }
+  validatePrivateDirectory(venvDir);
+  const marker = readMarker(venvDir);
+  const pythonPath = venvPythonPath(venvDir);
+  if (!markerMatches(marker, expectedMarker) ||
+      !fs.existsSync(pythonPath) || !pythonWorks(pythonPath, ["-c", "import kagent"])) {
+    throw new Error(`invalid cached Python runtime: ${venvDir}`);
+  }
+  return "valid";
+}
+
+function ensureVenv(root, version, options = {}) {
+  const platform = options.platform || process.platform;
+  assertSupportedPlatform(platform);
+  const python = options.python || findPython();
+  const identity = options.pythonIdentity || pythonRuntimeIdentity(python);
+  const dependencyFingerprint = dependencyHash(root);
+  const pythonIdentityHash = sha256(JSON.stringify(identity));
+  const cache = options.cacheRoot || ensureCacheRoot();
+  const arch = options.arch || process.arch;
+  const venvDir = runtimeCacheDirectory(cache, identity, platform, arch, dependencyFingerprint);
+  const ensureDirectory = options.ensurePrivateDirectory || ensurePrivateDirectory;
+  const checkedRun = options.runChecked || runChecked;
+  const markerWriter = options.writeMarker || writeMarker;
+  const pythonWorks = options.runtimePythonWorks || commandWorks;
+  const expectedMarker = installMarker(version, dependencyFingerprint, pythonIdentityHash);
+  ensureDirectory(path.dirname(venvDir));
+  if (runtimeState(venvDir, expectedMarker, pythonWorks) === "valid") {
+    return venvDir;
+  }
+
+  cleanupStaleTempRuntimes(path.dirname(venvDir), options.tempRuntimeStaleMs);
+  if (runtimeState(venvDir, expectedMarker, pythonWorks) === "valid") {
+    return venvDir;
+  }
+  const tempDir = createTempRuntime(venvDir);
+  try {
+    process.stderr.write(`kagent: preparing Python runtime in ${tempDir}\n`);
+    checkedRun(python, ["-m", "venv", tempDir], { cwd: root });
+    const tempPython = venvPythonPath(tempDir);
+    process.stderr.write("kagent: preparing Python runtime\n");
+    checkedRun(
+      tempPython,
+      ["-m", "pip", "install", "--disable-pip-version-check", "--quiet", root],
+      { cwd: root, stdio: "pipe" }
+    );
+    markerWriter(tempDir, expectedMarker);
+    if (runtimeState(tempDir, expectedMarker, pythonWorks) !== "valid") {
+      throw new Error(`failed to prepare Python runtime: ${tempDir}`);
+    }
+    const publishResult = publishRuntime(tempDir, venvDir);
+    if (publishResult !== "published" && publishResult !== "exists") {
+      throw new Error(`invalid Python runtime publish result: ${publishResult}`);
+    }
+    if (runtimeState(venvDir, expectedMarker, pythonWorks) !== "valid") {
+      throw new Error(`invalid cached Python runtime: ${venvDir}`);
+    }
+    return venvDir;
+  } finally {
+    removeTempRuntime(tempDir);
+  }
+}
+
+function pythonEnvironment(root, env = process.env) {
+  const source = path.join(root, "src");
+  return Object.assign({}, env, {
+    PYTHONPATH: env.PYTHONPATH ? `${source}${path.delimiter}${env.PYTHONPATH}` : source
+  });
+}
+
+function pythonEntrypointArgs(commandName, args) {
+  const code = PYTHON_ENTRYPOINTS[commandName];
+  if (!code) {
+    throw new Error(`unsupported Python entrypoint: ${commandName}`);
+  }
+  return ["-c", code, commandName].concat(args || []);
+}
+
+function spawnEntrypoint(venvDir, root, commandName, args) {
+  const command = venvPythonPath(venvDir);
+  const result = childProcess.spawnSync(command, pythonEntrypointArgs(commandName, args), {
+    env: pythonEnvironment(root),
+    stdio: "inherit"
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+function ensurePythonRuntime() {
+  const root = packageRoot();
+  const version = readPackageVersion(root);
+  const venvDir = ensureVenv(root, version);
+  return {
+    root,
+    version,
+    venvDir,
+    pythonPath: venvPythonPath(venvDir)
+  };
+}
+
+function spawnPythonModule(moduleName, args, options) {
+  const runtime = ensurePythonRuntime();
+  const provided = options || {};
+  const spawnOptions = Object.assign(
+    { cwd: runtime.root, stdio: ["pipe", "pipe", "pipe"] },
+    provided
+  );
+  spawnOptions.env = pythonEnvironment(
+    runtime.root,
+    Object.assign({}, process.env, provided.env || {})
+  );
+  return childProcess.spawn(
+    runtime.pythonPath,
+    ["-m", moduleName].concat(args || []),
+    spawnOptions
+  );
+}
+
+function runPythonEntrypoint(commandName, args) {
+  try {
+    const root = packageRoot();
+    const version = readPackageVersion(root);
+    if (maybePrintNodeHandledOutput(commandName, args, version)) {
+      return;
+    }
+    const venvDir = ensureVenv(root, version);
+    spawnEntrypoint(venvDir, root, commandName, args);
+  } catch (error) {
+    process.stderr.write(`kagent failed to start: ${error.message}\n`);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  ensurePythonRuntime,
+  runPythonEntrypoint,
+  spawnPythonModule,
+  _internals: {
+    cacheRoot,
+    dependencyHash,
+    ensureCacheRoot,
+    ensurePrivateDirectory,
+    ensureVenv,
+    metadataCacheRoot,
+    maybePrintNodeHandledOutput,
+    pythonEnvironment,
+    pythonEntrypointArgs,
+    pythonRuntimeIdentity,
+    publishRuntime,
+    readUpdateState,
+    spawnEntrypoint,
+    writeUpdateState
+  }
+};