lagora-cli 1.1.0

package/dist/scripts/sdk-runtime-JE6H2PB2.js

@@ -0,0 +1,992 @@
+import {
+  sdkPackageIndex
+} from "./chunk-2KTLCUFI.js";
+import {
+  loweringWorkerEnv
+} from "./chunk-RIR5KGHC.js";
+import {
+  SDK_PREPARE_SOURCE_PATHS,
+  readSdkPrepareCacheState,
+  sdkPrepareCacheEnv,
+  sdkPrepareCacheStateMatches,
+  sdkPrepareCacheStatePath,
+  sdkPrepareSourceFingerprint,
+  writeSdkPrepareCacheState
+} from "./chunk-UQ6I6VTY.js";
+import {
+  configuredGithubToken,
+  gitEnv
+} from "./chunk-2EAJVB5D.js";
+
+// lib/server/sdk-runtime.ts
+import { execFile as execFile2 } from "node:child_process";
+import { access as access2, appendFile, mkdir as mkdir4, readFile as readFile4, readdir, realpath, rename, writeFile as writeFile3 } from "node:fs/promises";
+import path6 from "node:path";
+import { promisify as promisify2 } from "node:util";
+
+// lib/server/sdk-runtime-progress.ts
+import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
+import path2 from "node:path";
+
+// lib/server/sdk-runtime-state.ts
+import { createHash } from "node:crypto";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+var DEFAULT_REPO_URL = "https://github.com/Hyper-Accel/hyperaccel-sdk.git";
+var DEFAULT_BRANCH = "main";
+var LEGACY_PREPARE_COMMAND = "git config url.https://github.com/.insteadOf git@github.com: && git submodule update --init --recursive && uv sync --group cpu";
+var PREPARE_COMMAND_WITHOUT_LLVM_PATHS = [
+  "git config url.https://github.com/.insteadOf git@github.com:",
+  "git submodule update --init --recursive",
+  "CMAKE_BUILD_PARALLEL_LEVEL=${CMAKE_BUILD_PARALLEL_LEVEL:-1} uv sync --frozen --inexact --package legato --no-default-groups --group cpu --group build --no-install-project",
+  "CMAKE_BUILD_PARALLEL_LEVEL=${CMAKE_BUILD_PARALLEL_LEVEL:-1} uv sync --frozen --inexact --package legato --no-default-groups --group cpu --group build --no-build-isolation",
+  "HART_BUILD_TYPE=release CMAKE_BUILD_PARALLEL_LEVEL=${CMAKE_BUILD_PARALLEL_LEVEL:-1} uv sync --frozen --inexact --package hart --no-default-groups --group cpu --group build --no-install-project",
+  "HART_BUILD_TYPE=release CMAKE_BUILD_PARALLEL_LEVEL=${CMAKE_BUILD_PARALLEL_LEVEL:-1} uv sync --frozen --inexact --package hart --no-default-groups --group cpu --group build --no-build-isolation",
+  ".venv/bin/python -c 'import legato; import hart'"
+].join(" && ");
+var SDK_INDEX_INSTALL = [
+  // Two version lines, not one. legato carries its own release number and the
+  // support packages share theirs; pinning legato to the shared one meant a
+  // released legato was never installed. AGORA_LEGATO_PACKAGE_VERSION is the
+  // version a reader picks in Settings, because "which Legato?" is the question
+  // this site exists to answer -- the rest is plumbing and resolves itself.
+  'LEGATO_V="${AGORA_LEGATO_PACKAGE_VERSION:-$(python3 /app/scripts/resolve-sdk-package-version.py --index-url "$AGORA_SDK_INDEX_URL" --package legato --independent)}"',
+  // The support packages' shared line, pinnable exactly the way legato's is. A
+  // reported failure happened against a pair, so reproducing it needs both
+  // halves nameable; pinning only legato left this side floating on whatever
+  // nightly the job resolved that day. Unset still resolves the newest shared
+  // nightly, which is what every unpinned prepare keeps doing.
+  'SDK_V="${AGORA_SDK_PACKAGE_VERSION:-$(python3 /app/scripts/resolve-sdk-package-version.py --index-url "$AGORA_SDK_INDEX_URL")}"',
+  '[ -n "$LEGATO_V" ] && [ -n "$SDK_V" ]',
+  `printf '\\n[agora] installing legato %s with SDK support packages %s\\n' "$LEGATO_V" "$SDK_V"`,
+  'uv pip install --prerelease=allow --extra-index-url https://download.pytorch.org/whl/cpu "torch==2.10.0+cpu" "legato===$LEGATO_V" "halogger===$SDK_V" "numpy<2.0.0" "PyYAML==6.0.3" "pybind11>=3.0.0" loguru "fairscale==0.4.13" "llama-models==0.3.0" "transformers>=4.57.1" "accelerate>=0.30.0" ipython',
+  // hapti is deliberately absent, as it is from the SDK team's own image. It is
+  // the on-hardware profiler, its profiles are blocked in the UI, and its wheel
+  // cannot find libha_hapti.so in this layout. The profile gate looks for hapti's
+  // artifacts on disk, so leaving it out reports "unavailable" rather than
+  // failing the whole prepare on a package no run can use.
+  'uv pip install --prerelease=allow --no-deps "torch_ha===$SDK_V" "hart===$SDK_V"'
+].join(" && ");
+var SDK_SOURCE_BUILD = [
+  "git submodule update --init --recursive",
+  "uv lock",
+  "CMAKE_BUILD_PARALLEL_LEVEL=${CMAKE_BUILD_PARALLEL_LEVEL:-1} uv sync --frozen --inexact --package legato --no-default-groups --group cpu --group build --no-install-project",
+  "CMAKE_BUILD_PARALLEL_LEVEL=${CMAKE_BUILD_PARALLEL_LEVEL:-1} uv sync --frozen --inexact --package legato --no-default-groups --group cpu --group build --no-build-isolation",
+  "HART_BUILD_TYPE=release CMAKE_BUILD_PARALLEL_LEVEL=${CMAKE_BUILD_PARALLEL_LEVEL:-1} uv sync --frozen --inexact --package hart --no-default-groups --group cpu --group build --no-install-project",
+  "HART_BUILD_TYPE=release CMAKE_BUILD_PARALLEL_LEVEL=${CMAKE_BUILD_PARALLEL_LEVEL:-1} uv sync --frozen --inexact --package hart --no-default-groups --group cpu --group build --no-build-isolation",
+  "HART_BUILD_TYPE=release CMAKE_BUILD_PARALLEL_LEVEL=${CMAKE_BUILD_PARALLEL_LEVEL:-1} uv sync --frozen --inexact --package torch_ha --no-default-groups --group cpu --group build --no-install-project",
+  "HART_BUILD_TYPE=release CMAKE_BUILD_PARALLEL_LEVEL=${CMAKE_BUILD_PARALLEL_LEVEL:-1} uv sync --frozen --inexact --package torch_ha --no-default-groups --group cpu --group build --no-build-isolation",
+  // hapti builds libhapti_tool.so, which the profile gate looks for before it
+  // will let a run ask for a trace.
+  "HART_BUILD_TYPE=release CMAKE_BUILD_PARALLEL_LEVEL=${CMAKE_BUILD_PARALLEL_LEVEL:-1} uv sync --frozen --inexact --package hapti --no-default-groups --group cpu --group build --no-install-project",
+  "HART_BUILD_TYPE=release CMAKE_BUILD_PARALLEL_LEVEL=${CMAKE_BUILD_PARALLEL_LEVEL:-1} uv sync --frozen --inexact --package hapti --no-default-groups --group cpu --group build --no-build-isolation"
+].join(" && ");
+var PREPARE_PRELUDE = [
+  // --global is load-bearing: two private submodules are declared with git@ URLs,
+  // and a submodule fetch runs its own git, which never reads the superproject's
+  // local config. Set locally, the rewrite is ignored and the fetch needs an
+  // authorised SSH key that prepared environments do not have.
+  "git config --global url.https://github.com/.insteadOf git@github.com:",
+  // UV_DEFAULT_INDEX empty means "unset" to uv, which is how the SDK repo's own
+  // workflows switch between the internal index and plain PyPI.
+  "export PATH=/usr/lib/llvm-20/bin:$PATH CC=${CC:-clang-20} CXX=${CXX:-clang++-20} CMAKE_PREFIX_PATH=${CMAKE_PREFIX_PATH:-/usr/lib/llvm-20} LLVM_DIR=${LLVM_DIR:-/usr/lib/llvm-20/lib/cmake/llvm} MLIR_DIR=${MLIR_DIR:-/usr/lib/llvm-20/lib/cmake/mlir} OpenMP_ROOT=${OpenMP_ROOT:-/usr/lib/llvm-20} UV_CACHE_DIR=${UV_CACHE_DIR:-$(dirname $PWD)/.agora/cache/uv} CCACHE_DIR=${CCACHE_DIR:-$(dirname $PWD)/.agora/cache/ccache} CCACHE_BASEDIR=${CCACHE_BASEDIR:-$PWD} UV_LINK_MODE=${UV_LINK_MODE:-copy} UV_LOCK_TIMEOUT=${UV_LOCK_TIMEOUT:-900} UV_DEFAULT_INDEX=${AGORA_SDK_INDEX_URL:-} UV_INSECURE_HOST=${AGORA_SDK_INDEX_HOST:-}",
+  // --allow-existing reuses a venv a previous prepare left behind. Without it uv
+  // warns that a future release will require --clear to touch an existing venv,
+  // which would turn a uv upgrade in the image into a failing prepare.
+  "uv venv --python 3.10 --allow-existing",
+  // uv downloads its own CPython, so libpython lives under UV_PYTHON_INSTALL_DIR
+  // rather than a system library directory. torch_ha's CMake runs the gtest binary
+  // it has just built to enumerate test cases, and that binary links libpython --
+  // the loader cannot find it otherwise, and the build stops there. Resolved at
+  // this point rather than in the export block above because the venv that names
+  // the interpreter does not exist until uv creates it.
+  `export LD_LIBRARY_PATH="$(.venv/bin/python -c 'import sysconfig; print(sysconfig.get_config_var("LIBDIR") or "")')\${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"`
+];
+var PREPARE_EPILOGUE = [
+  // torch must be imported before torch_ha: torch autoloads the torch_ha device
+  // backend, and importing torch_ha first re-enters a half-initialised torch.
+  // hapti is not verified: it needs real hardware, its profiles are blocked in
+  // the UI, and the profile gate decides its availability from disk on its own.
+  ".venv/bin/python -c 'import torch; import torch_ha; import legato; import hart'",
+  // Which versions actually landed -- the wheel path resolves them from the index,
+  // so the log is the only place that records what this runtime really contains.
+  //
+  // Reports what is installed rather than asserting a fixed list. Naming packages
+  // directly made this step fail the whole prepare on a fresh root once hapti was
+  // dropped from the install, and the two lists have no reason to stay in step:
+  // the source build installs one set, the index install another.
+  `.venv/bin/python -c 'import importlib.metadata as m; d={(x.metadata["Name"] or "").lower().replace("-","_"): x.version for x in m.distributions()}; print("[agora] installed: " + ", ".join(f"{k}=={d[k]}" for k in ["legato","hart","torch_ha","hapti","torch"] if k in d))'`
+];
+var DEFAULT_PREPARE_COMMAND = [
+  ...PREPARE_PRELUDE,
+  `( [ -n "\${AGORA_SDK_INDEX_URL:-}" ] && ${SDK_INDEX_INSTALL} ) || ( printf '\\n[agora] package index install unavailable; building from source\\n' && ${SDK_SOURCE_BUILD} )`,
+  ...PREPARE_EPILOGUE
+].join(" && ");
+var PACKAGE_PREPARE_COMMAND = [
+  ...PREPARE_PRELUDE.filter((part) => !part.startsWith("git config")),
+  SDK_INDEX_INSTALL,
+  ...PREPARE_EPILOGUE
+].join(" && ");
+async function readSdkRuntimeSettings(overrides = {}) {
+  const defaults = defaultSdkRuntimeSettings();
+  let settings = defaults;
+  try {
+    const raw = await readFile(settingsPath(), "utf8");
+    settings = parseStoredSettings(JSON.parse(raw), defaults);
+  } catch {
+    settings = defaults;
+  }
+  return applyOverrides(settings, overrides);
+}
+async function writeSdkRuntimeSettings(input) {
+  const runtimeRoot = path.resolve(normalizeRequired(input.runtimeRoot, defaultRuntimeRoot()));
+  const repoUrl = normalizeRequired(input.repoUrl, DEFAULT_REPO_URL);
+  const branch = normalizeRequired(input.branch, DEFAULT_BRANCH);
+  const preparedRoot = preparedRuntimeRoot(runtimeRoot, repoUrl, branch);
+  const settings = {
+    repoUrl,
+    branch,
+    runtimeRoot,
+    preparedRoot,
+    // Both the interpreter and the extra PYTHONPATH live inside the branch/commit-specific prepared
+    // worktree, so they are derived from preparedRoot and never user-configurable. A stored absolute
+    // path would point at a stale .venv / legato_aten_lib whenever the selected branch or commit changes.
+    pythonPath: defaultPythonPath(preparedRoot),
+    prepareCommand: normalizePrepareCommand(input.prepareCommand, defaultPrepareCommand()),
+    extraPythonPaths: defaultExtraPythonPaths(preparedRoot),
+    autoPrepareOnStart: input.autoPrepareOnStart,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await mkdir(settingsRoot(), { recursive: true });
+  await writeFile(settingsPath(), `${JSON.stringify(settings, null, 2)}
+`);
+  return settings;
+}
+async function readSdkRuntimeStatus(overrides = {}) {
+  const settings = await readSdkRuntimeSettings(overrides);
+  try {
+    const raw = await readFile(statusPath(settings.preparedRoot), "utf8");
+    const status = parseStoredStatus(JSON.parse(raw), settings);
+    if (!statusMatchesSettings(status, settings)) {
+      return notPreparedStatus(settings, "SDK runtime settings changed. Prepare the selected branch before lowering.");
+    }
+    if (status.status === "ready" && !await pathExists(status.pythonPath)) {
+      return notPreparedStatus(settings, `SDK runtime Python runtime is missing: ${status.pythonPath}`);
+    }
+    return status;
+  } catch {
+    return notPreparedStatus(settings, "SDK source worktree has not been prepared yet.");
+  }
+}
+async function writeSdkRuntimeStatus(settings, input, statusRoot = settings.preparedRoot) {
+  const status = {
+    ...input,
+    repoUrl: settings.repoUrl,
+    branch: settings.branch,
+    runtimeRoot: settings.runtimeRoot,
+    preparedRoot: settings.preparedRoot,
+    pythonPath: settings.pythonPath
+  };
+  await mkdir(statusRoot, { recursive: true });
+  await writeFile(statusPath(statusRoot), `${JSON.stringify(status, null, 2)}
+`);
+  return status;
+}
+function sdkRuntimeExtraPythonPath(settings) {
+  return settings.extraPythonPaths.split(path.delimiter).map((item) => item.trim()).filter(Boolean).join(path.delimiter);
+}
+function sdkRuntimeSettingsWithPreparedRoot(settings, preparedRoot) {
+  const resolvedPreparedRoot = path.resolve(preparedRoot);
+  return {
+    ...settings,
+    preparedRoot: resolvedPreparedRoot,
+    pythonPath: defaultPythonPath(resolvedPreparedRoot),
+    extraPythonPaths: defaultExtraPythonPaths(resolvedPreparedRoot)
+  };
+}
+function installLogPath(runtimeRoot) {
+  return path.join(runtimeRoot, "install.log");
+}
+function defaultSdkRuntimeSettings() {
+  const runtimeRoot = defaultRuntimeRoot();
+  const repoUrl = process.env.AGORA_SDK_REPO_URL ?? DEFAULT_REPO_URL;
+  const branch = process.env.AGORA_SDK_BRANCH ?? DEFAULT_BRANCH;
+  const preparedRoot = preparedRuntimeRoot(runtimeRoot, repoUrl, branch);
+  return {
+    repoUrl,
+    branch,
+    runtimeRoot,
+    preparedRoot,
+    pythonPath: defaultPythonPath(preparedRoot),
+    prepareCommand: process.env.AGORA_SDK_PREPARE_COMMAND ?? defaultPrepareCommand(),
+    extraPythonPaths: defaultExtraPythonPaths(preparedRoot),
+    autoPrepareOnStart: readBoolean(process.env.AGORA_SDK_PREPARE_ON_START) ?? true
+  };
+}
+async function pathExists(candidate) {
+  try {
+    await access(candidate);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function defaultRuntimeRoot() {
+  const configuredRoot = process.env.AGORA_SDK_RUNTIME_ROOT ?? process.env.AGORA_SDK_ROOT;
+  return configuredRoot ? path.resolve(configuredRoot) : path.join(
+    /*turbopackIgnore: true*/
+    process.cwd(),
+    ".local-data",
+    "sdk-source"
+  );
+}
+function defaultPrepareCommand() {
+  return DEFAULT_PREPARE_COMMAND;
+}
+function parseStoredSettings(value, defaults) {
+  if (!isRecord(value)) return defaults;
+  const runtimeRoot = path.resolve(readString(value, "runtimeRoot", defaults.runtimeRoot));
+  const repoUrl = readString(value, "repoUrl", defaults.repoUrl);
+  const branch = readString(value, "branch", defaults.branch);
+  const preparedRoot = path.resolve(readString(value, "preparedRoot", preparedRuntimeRoot(runtimeRoot, repoUrl, branch)));
+  return {
+    repoUrl,
+    branch,
+    runtimeRoot,
+    preparedRoot,
+    pythonPath: defaultPythonPath(preparedRoot),
+    prepareCommand: normalizePrepareCommand(readString(value, "prepareCommand", defaults.prepareCommand), defaults.prepareCommand),
+    extraPythonPaths: defaultExtraPythonPaths(preparedRoot),
+    autoPrepareOnStart: readBooleanValue(value.autoPrepareOnStart) ?? defaults.autoPrepareOnStart,
+    updatedAt: readOptionalString(value, "updatedAt")
+  };
+}
+function parseStoredStatus(value, settings) {
+  if (!isRecord(value)) return notPreparedStatus(settings);
+  const status = value.status === "preparing" || value.status === "ready" || value.status === "failed" ? value.status : "not_prepared";
+  return {
+    status,
+    repoUrl: readString(value, "repoUrl", settings.repoUrl),
+    branch: readString(value, "branch", settings.branch),
+    runtimeRoot: readString(value, "runtimeRoot", settings.runtimeRoot),
+    preparedRoot: path.resolve(readString(value, "preparedRoot", settings.preparedRoot)),
+    pythonPath: readString(value, "pythonPath", settings.pythonPath),
+    commitSha: readOptionalString(value, "commitSha"),
+    startedAt: readOptionalString(value, "startedAt"),
+    completedAt: readOptionalString(value, "completedAt"),
+    message: readOptionalString(value, "message")
+  };
+}
+function settingsRoot() {
+  return process.env.AGORA_SETTINGS_DIR ? path.resolve(process.env.AGORA_SETTINGS_DIR) : path.join(
+    /*turbopackIgnore: true*/
+    process.cwd(),
+    ".local-data",
+    "settings"
+  );
+}
+function settingsPath() {
+  return path.join(settingsRoot(), "sdk-runtime.json");
+}
+function statusPath(runtimeRoot) {
+  return path.join(runtimeRoot, "runtime.json");
+}
+function applyOverrides(settings, overrides) {
+  const repoUrl = normalizeRequired(overrides.repoUrl ?? settings.repoUrl, settings.repoUrl);
+  const branch = normalizeRequired(overrides.branch ?? settings.branch, settings.branch);
+  const runtimeRoot = path.resolve(normalizeRequired(overrides.runtimeRoot ?? settings.runtimeRoot, settings.runtimeRoot));
+  const defaultPreparedRoot = preparedRuntimeRoot(runtimeRoot, repoUrl, branch);
+  const preparedRoot = path.resolve(normalizeRequired(overrides.preparedRoot ?? defaultPreparedRoot, defaultPreparedRoot));
+  return {
+    ...settings,
+    repoUrl,
+    branch,
+    runtimeRoot,
+    preparedRoot,
+    pythonPath: defaultPythonPath(preparedRoot),
+    prepareCommand: normalizePrepareCommand(overrides.prepareCommand ?? settings.prepareCommand, settings.prepareCommand),
+    extraPythonPaths: defaultExtraPythonPaths(preparedRoot)
+  };
+}
+function notPreparedStatus(settings, message) {
+  return {
+    status: "not_prepared",
+    repoUrl: settings.repoUrl,
+    branch: settings.branch,
+    runtimeRoot: settings.runtimeRoot,
+    preparedRoot: settings.preparedRoot,
+    pythonPath: settings.pythonPath,
+    message
+  };
+}
+function statusMatchesSettings(status, settings) {
+  const preparedRoot = path.resolve(status.preparedRoot);
+  const sameRef = status.branch === settings.branch || status.commitSha === settings.branch;
+  return status.repoUrl === settings.repoUrl && sameRef && path.resolve(status.runtimeRoot) === settings.runtimeRoot && (preparedRoot === settings.preparedRoot && status.pythonPath === settings.pythonPath || isRuntimeRootChild(settings.runtimeRoot, preparedRoot) && status.pythonPath === defaultPythonPath(preparedRoot));
+}
+function isRuntimeRootChild(runtimeRoot, preparedRoot) {
+  const relative = path.relative(runtimeRoot, preparedRoot);
+  return Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+function preparedRuntimeRoot(runtimeRoot, repoUrl, branch) {
+  return path.join(runtimeRoot, runtimeKey(repoUrl, branch));
+}
+function runtimeKey(repoUrl, branch) {
+  const branchSlug = branch.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "ref";
+  const repoHash2 = createHash("sha256").update(repoUrl).digest("hex").slice(0, 10);
+  return `${branchSlug}-${repoHash2}`;
+}
+function defaultPythonPath(preparedRoot) {
+  return path.join(preparedRoot, ".venv", "bin", "python");
+}
+function defaultExtraPythonPaths(preparedRoot) {
+  return path.join(preparedRoot, "legato_aten_lib");
+}
+function normalizeRequired(value, fallback) {
+  const normalized = value.trim();
+  return normalized ? normalized : fallback;
+}
+function normalizePrepareCommand(value, fallback) {
+  const normalized = normalizeRequired(value, fallback);
+  if (normalized === LEGACY_PREPARE_COMMAND || normalized === PREPARE_COMMAND_WITHOUT_LLVM_PATHS || /(?:clang-14|llvm-14|MLIR_DIR=\$\{MLIR_DIR:-\/usr\/lib\/llvm-14)/.test(normalized) || /llvm-20|clang-20|uv sync --frozen --package (?:legato|hart)/.test(normalized) && (!normalized.includes("--inexact") || !normalized.includes("PATH=/usr/lib/llvm-20/bin:$PATH") || !normalized.includes("OpenMP_ROOT=${OpenMP_ROOT:-/usr/lib/llvm-20}") || !normalized.includes("UV_CACHE_DIR=${UV_CACHE_DIR:-$(dirname $PWD)/.agora/cache/uv}") || !normalized.includes("CCACHE_DIR=${CCACHE_DIR:-$(dirname $PWD)/.agora/cache/ccache}") || !normalized.includes("UV_LINK_MODE=${UV_LINK_MODE:-copy}") || !normalized.includes("uv lock") || !normalized.includes("uv sync --frozen --inexact --package legato --no-default-groups --group cpu --group build --no-install-project") || !normalized.includes("uv sync --frozen --inexact --package legato --no-default-groups --group cpu --group build --no-build-isolation") || !normalized.includes("--package torch_ha") || !normalized.includes("--package hapti") || !normalized.includes('sysconfig.get_config_var("LIBDIR")') || !normalized.includes("AGORA_SDK_INDEX_URL") || !normalized.includes("legato===$LEGATO_V") || !normalized.includes("AGORA_SDK_PACKAGE_VERSION") || !normalized.includes("import legato; import hart'") || !normalized.includes("m.distributions()") || !normalized.includes("git config --global url.https://github.com/.insteadOf"))) {
+    return DEFAULT_PREPARE_COMMAND;
+  }
+  return normalized;
+}
+function readString(record, key, fallback) {
+  const value = record[key];
+  return typeof value === "string" && value.trim() ? value.trim() : fallback;
+}
+function readOptionalString(record, key) {
+  const value = record[key];
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function readBoolean(value) {
+  if (value === "1" || value === "true") return true;
+  if (value === "0" || value === "false") return false;
+  return void 0;
+}
+function readBooleanValue(value) {
+  return typeof value === "boolean" ? value : void 0;
+}
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+// lib/server/sdk-runtime-progress.ts
+async function createSdkPrepareRun(settings, startedAt) {
+  const runId = `${compactUtc(startedAt)}-${process.pid}`;
+  const runDir = path2.join(sdkPrepareRunsRoot(settings), runId);
+  const run = {
+    runId,
+    runDir,
+    progressPath: path2.join(runDir, "events.jsonl"),
+    liveLogPath: path2.join(runDir, "combined.log"),
+    resultPath: path2.join(runDir, "result.json"),
+    startedAt
+  };
+  await mkdir2(runDir, { recursive: true });
+  await writeFile2(path2.join(runDir, "manifest.json"), `${JSON.stringify({
+    runId,
+    repoUrl: settings.repoUrl,
+    branch: settings.branch,
+    runtimeRoot: settings.runtimeRoot,
+    preparedRoot: settings.preparedRoot,
+    prepareCommand: settings.prepareCommand,
+    startedAt
+  }, null, 2)}
+`);
+  await writeFile2(sdkPrepareCurrentPath(settings), `${JSON.stringify(run, null, 2)}
+`);
+  return run;
+}
+function sdkPrepareRunsRoot(settings) {
+  return path2.join(settings.runtimeRoot, ".agora", "sdk-prepare-runs", path2.basename(settings.preparedRoot));
+}
+function sdkPrepareCurrentPath(settings) {
+  return path2.join(sdkPrepareRunsRoot(settings), "current.json");
+}
+function compactUtc(value) {
+  return value.replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+}
+
+// lib/server/sdk-runtime-lock.ts
+import { mkdir as mkdir3, open, readFile as readFile3, rm, stat } from "node:fs/promises";
+import path3 from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { randomUUID } from "node:crypto";
+var DEFAULT_LOCK_STALE_MS = 144e5;
+var DEFAULT_LOCK_WAIT_MS = 144e5;
+var POLL_INTERVAL_MS = 1e3;
+async function withSdkPrepareLock(settings, callback) {
+  const lock = await acquireSdkPrepareLock(settings);
+  try {
+    return await callback();
+  } finally {
+    await lock.release();
+  }
+}
+async function acquireSdkPrepareLock(settings) {
+  const lockPath = sdkPrepareLockPath(settings);
+  const owner = `${process.pid}-${randomUUID()}`;
+  const started = Date.now();
+  while (Date.now() - started < lockWaitMs()) {
+    const handle = await tryCreateLock(lockPath, owner);
+    if (handle) return lockHandle(lockPath, owner, handle);
+    await removeStaleLock(lockPath);
+    await delay(POLL_INTERVAL_MS);
+  }
+  throw new Error(`Timed out waiting for SDK prepare lock: ${lockPath}`);
+}
+function sdkPrepareLockPath(settings) {
+  return path3.join(settings.runtimeRoot, ".agora", "sdk-prepare.lock");
+}
+async function tryCreateLock(lockPath, owner) {
+  try {
+    const handle = await open(lockPath, "wx");
+    await handle.writeFile(`${JSON.stringify({ owner, pid: process.pid, createdAt: (/* @__PURE__ */ new Date()).toISOString() })}
+`);
+    return handle;
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      await mkdir3(path3.dirname(lockPath), { recursive: true });
+      return await tryCreateLock(lockPath, owner);
+    }
+    if (isNodeError(error) && error.code === "EEXIST") return void 0;
+    throw error;
+  }
+}
+async function removeStaleLock(lockPath) {
+  try {
+    const details = await stat(lockPath);
+    if (Date.now() - details.mtimeMs <= lockStaleMs()) return;
+    await rm(lockPath, { force: true });
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") return;
+    throw error;
+  }
+}
+function lockHandle(lockPath, owner, handle) {
+  return {
+    release: async () => {
+      await handle.close();
+      try {
+        const current = JSON.parse(await readFile3(lockPath, "utf8"));
+        if (isRecord2(current) && current.owner === owner) await rm(lockPath, { force: true });
+      } catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") return;
+        throw error;
+      }
+    }
+  };
+}
+function lockStaleMs() {
+  return readPositiveInt(process.env.AGORA_SDK_PREPARE_LOCK_STALE_MS, DEFAULT_LOCK_STALE_MS);
+}
+function lockWaitMs() {
+  return readPositiveInt(process.env.AGORA_SDK_PREPARE_LOCK_WAIT_MS, DEFAULT_LOCK_WAIT_MS);
+}
+function readPositiveInt(value, fallback) {
+  if (!value) return fallback;
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+function isNodeError(error) {
+  return error instanceof Error && "code" in error;
+}
+function isRecord2(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+// lib/server/sdk-runtime-smoke.ts
+import { fileURLToPath as packageFilePath } from "node:url";
+import { execFile } from "node:child_process";
+import path4 from "node:path";
+import { promisify } from "node:util";
+var execFileAsync = promisify(execFile);
+var DEFAULT_SMOKE_STAGES = "MLIR,CORE_IR";
+var DEFAULT_SMOKE_TIMEOUT_MS = 12e4;
+async function runPreparedRuntimeSmoke(settings) {
+  const scriptPath = process.env.AGORA_SDK_PREPARE_SMOKE_SCRIPT ?? path4.join(
+    /*turbopackIgnore: true*/
+    packageFilePath(new URL(".", import.meta.url)),
+    "sdk-runtime-smoke.py"
+  );
+  const outputRoot = path4.join(settings.preparedRoot, ".agora", "smoke");
+  const stages = process.env.AGORA_SDK_PREPARE_SMOKE_STAGES ?? DEFAULT_SMOKE_STAGES;
+  return await execFileAsync(settings.pythonPath, [scriptPath, "--repo-root", settings.preparedRoot, "--output-root", outputRoot, "--stages", stages], {
+    cwd: settings.preparedRoot,
+    env: loweringWorkerEnv(settings, { ...process.env, ...sdkPrepareCacheEnv(settings) }),
+    timeout: readPositiveInt2(process.env.AGORA_SDK_PREPARE_SMOKE_TIMEOUT_MS, DEFAULT_SMOKE_TIMEOUT_MS),
+    maxBuffer: 8 * 1024 * 1024
+  });
+}
+function readPositiveInt2(value, fallback) {
+  if (!value) return fallback;
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+// lib/server/sdk-runtime-source-root.ts
+import { createHash as createHash2 } from "node:crypto";
+import path5 from "node:path";
+var FINGERPRINT_SLICE_LENGTH = 12;
+var REPO_HASH_LENGTH = 10;
+function sdkRuntimeSettingsForSourceFingerprint(settings, sourceFingerprint) {
+  return sdkRuntimeSettingsWithPreparedRoot(
+    settings,
+    path5.join(settings.runtimeRoot, sourceRuntimeKey(settings.repoUrl, settings.branch, sourceFingerprint))
+  );
+}
+function sdkRuntimeSettingsForPackageVersion(settings, pin) {
+  const versions = typeof pin === "string" ? { legatoVersion: pin } : pin;
+  return sdkRuntimeSettingsWithPreparedRoot(
+    settings,
+    path5.join(settings.runtimeRoot, packageRuntimeKey(versions, settings.repoUrl))
+  );
+}
+function packageRuntimeKey(pin, repoUrl) {
+  const legato = pin.legatoVersion?.trim();
+  const sdk = pin.sdkVersion?.trim();
+  if (!sdk) return `pkg-${versionSlug(legato ?? "")}-${repoHash(repoUrl)}`;
+  const legatoSegment = legato ? versionSlug(legato) : "latest";
+  return `pkg-${legatoSegment}-sdk-${versionSlug(sdk)}-${repoHash(repoUrl)}`;
+}
+function versionSlug(version) {
+  return version.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "version";
+}
+function sourceRuntimeKey(repoUrl, ref, sourceFingerprint) {
+  return `${refSlug(ref)}-${sourceFingerprint.slice(0, FINGERPRINT_SLICE_LENGTH)}-${repoHash(repoUrl)}`;
+}
+function refSlug(ref) {
+  return ref.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "ref";
+}
+function repoHash(repoUrl) {
+  return createHash2("sha256").update(repoUrl).digest("hex").slice(0, REPO_HASH_LENGTH);
+}
+
+// lib/server/sdk-runtime.ts
+var execFileAsync2 = promisify2(execFile2);
+function prepareVersionPin(options) {
+  return {
+    legatoVersion: trimmedVersion(options.legatoVersion ?? options.packageVersion),
+    sdkVersion: trimmedVersion(options.sdkVersion)
+  };
+}
+function trimmedVersion(value) {
+  const text = value?.trim();
+  return text ? text : void 0;
+}
+function isVersionPinned(pin) {
+  return Boolean(pin.legatoVersion ?? pin.sdkVersion);
+}
+function describeVersionPin(pin) {
+  return `legato ${pin.legatoVersion ?? "latest"} with SDK support packages ${pin.sdkVersion ?? "latest"}`;
+}
+function prepareVersionEnv(pin) {
+  return {
+    ...pin.legatoVersion ? { AGORA_LEGATO_PACKAGE_VERSION: pin.legatoVersion } : {},
+    ...pin.sdkVersion ? { AGORA_SDK_PACKAGE_VERSION: pin.sdkVersion } : {}
+  };
+}
+async function prepareSdkRuntime(overrides = {}, options = {}) {
+  const refSettings = await readSdkRuntimeSettings(overrides);
+  return await withSdkPrepareLock(refSettings, async () => await prepareSdkRuntimeUnlocked(refSettings, options));
+}
+async function prepareSdkRuntimeUnlocked(refSettings, options = {}) {
+  await mkdir4(path6.dirname(refSettings.preparedRoot), { recursive: true });
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const prepareRun = await createSdkPrepareRun(refSettings, startedAt);
+  await writeSdkRuntimeStatus(refSettings, { status: "preparing", startedAt, message: "Resolving SDK source ref." });
+  let activeSettings = refSettings;
+  try {
+    const token = await configuredGithubToken();
+    const logParts = prepareLogHeader(refSettings, startedAt);
+    const pin = prepareVersionPin(options);
+    const pinned = isVersionPinned(pin);
+    const fromIndex = pinned && Boolean(sdkPackageIndex());
+    let commitSha;
+    let sourceFingerprint = "";
+    if (!fromIndex) {
+      await verifyGitAccess(refSettings, token);
+      logParts.push("gitAccess: ok");
+      await syncRepository(refSettings, token);
+      commitSha = await gitOutput(refSettings.preparedRoot, ["rev-parse", "HEAD"], token);
+      sourceFingerprint = await prepareSourceFingerprint(refSettings, token);
+    }
+    activeSettings = pinned ? sdkRuntimeSettingsForPackageVersion(refSettings, pin) : sdkRuntimeSettingsForSourceFingerprint(refSettings, sourceFingerprint);
+    if (fromIndex) {
+      if (activeSettings.prepareCommand === DEFAULT_PREPARE_COMMAND) {
+        activeSettings = { ...activeSettings, prepareCommand: PACKAGE_PREPARE_COMMAND };
+      }
+      await mkdir4(activeSettings.preparedRoot, { recursive: true });
+    }
+    logParts.push(
+      fromIndex ? `legatoVersion: ${pin.legatoVersion ?? "latest"}` : `commitSha: ${commitSha}`,
+      ...fromIndex ? [`sdkVersion: ${pin.sdkVersion ?? "latest"}`] : [],
+      fromIndex ? "source: package index (no checkout)" : `sourceFingerprint: ${sourceFingerprint}`,
+      `sourcePreparedRoot: ${activeSettings.preparedRoot}`,
+      ""
+    );
+    await writeSdkRuntimeStatus(activeSettings, { status: "preparing", startedAt, commitSha, message: fromIndex ? "Installing published SDK packages." : "Preparing SDK source runtime." }, refSettings.preparedRoot);
+    if (process.env.AGORA_SDK_PREPARE_BACKEND === "kubernetes-job") {
+      if (!options.force && !pinned && await preparedRuntimeMarkedReady(activeSettings, commitSha ?? "", sourceFingerprint)) {
+        const completedAt2 = (/* @__PURE__ */ new Date()).toISOString();
+        await writeSdkPrepareCacheState(activeSettings, commitSha ?? "", sourceFingerprint, completedAt2);
+        logParts.push(
+          "cache:",
+          `hit: ${sdkPrepareCacheStatePath(activeSettings)}`,
+          `preparedRoot: ${activeSettings.preparedRoot}`,
+          "prepare job skipped; existing prepared-runtime marker reused (no smoke run in web pod).",
+          `completedAt: ${completedAt2}`
+        );
+        await writeInstallLog(activeSettings, refSettings, logParts.join("\n"));
+        const status2 = await writePreparedStatus(activeSettings, refSettings, { status: "ready", startedAt, completedAt: completedAt2, commitSha, message: "SDK source runtime reused from prepared marker." });
+        return { settings: activeSettings, status: status2, logPath: installLogPath(activeSettings.preparedRoot) };
+      }
+      return await prepareSdkRuntimeWithKubernetesJob(activeSettings, refSettings, startedAt, prepareRun, logParts, pin);
+    }
+    if (!fromIndex && activeSettings.preparedRoot !== refSettings.preparedRoot) {
+      await syncRepository(activeSettings, token);
+    }
+    if (!options.force && !pinned && await canReusePreparedRuntime(activeSettings, commitSha ?? "", sourceFingerprint, token)) {
+      const completedAt2 = (/* @__PURE__ */ new Date()).toISOString();
+      await writeSdkPrepareCacheState(activeSettings, commitSha ?? "", sourceFingerprint, completedAt2);
+      logParts.push(
+        "cache:",
+        `hit: ${sdkPrepareCacheStatePath(activeSettings)}`,
+        `preparedRoot: ${activeSettings.preparedRoot}`,
+        "prepare command skipped; existing SDK runtime smoke passed.",
+        `completedAt: ${completedAt2}`
+      );
+      await writeInstallLog(activeSettings, refSettings, logParts.join("\n"));
+      const status2 = await writePreparedStatus(activeSettings, refSettings, { status: "ready", startedAt, completedAt: completedAt2, commitSha, message: "SDK source runtime reused from cache." });
+      return { settings: activeSettings, status: status2, logPath: installLogPath(activeSettings.preparedRoot) };
+    }
+    const install = await execFileAsync2("sh", ["-lc", activeSettings.prepareCommand], {
+      cwd: activeSettings.preparedRoot,
+      env: { ...prepareEnv(activeSettings, token), ...prepareVersionEnv(pin) },
+      // A cold prepared root builds legato (~23 min), hart and torch_ha (~11 min)
+      // from source, and `uv lock` alone is allowed 15 min, so observed cold runs
+      // pass an hour. Kept below the 4h orphan window in sdk-runtime-inventory.
+      timeout: readPositiveInt3(process.env.AGORA_SDK_PREPARE_TIMEOUT_MS, 108e5),
+      maxBuffer: 32 * 1024 * 1024
+    });
+    await probePreparedRuntime(activeSettings, token);
+    const smoke = await runPreparedRuntimeSmoke(activeSettings);
+    const completedAt = (/* @__PURE__ */ new Date()).toISOString();
+    await writeSdkPrepareCacheState(activeSettings, commitSha ?? "", sourceFingerprint, completedAt);
+    logParts.push(
+      "stdout:",
+      install.stdout || "<empty>",
+      "",
+      "stderr:",
+      install.stderr || "<empty>",
+      "",
+      "smokeStdout:",
+      smoke.stdout || "<empty>",
+      "",
+      "smokeStderr:",
+      smoke.stderr || "<empty>",
+      `completedAt: ${completedAt}`
+    );
+    await writeInstallLog(activeSettings, refSettings, logParts.join("\n"));
+    const status = await writePreparedStatus(activeSettings, refSettings, { status: "ready", startedAt, completedAt, commitSha, message: fromIndex ? `Installed ${describeVersionPin(pin)} from the package index.` : "SDK source runtime is ready." });
+    return { settings: activeSettings, status, logPath: installLogPath(activeSettings.preparedRoot) };
+  } catch (error) {
+    const status = await recordPrepareFailure(activeSettings, refSettings, startedAt, error);
+    return { settings: activeSettings, status, logPath: installLogPath(activeSettings.preparedRoot) };
+  }
+}
+async function prepareSdkRuntimeWithKubernetesJob(settings, refSettings, startedAt, prepareRun, logParts, pin) {
+  const { runSdkPrepareJob } = await import("./sdk-runtime-kubernetes-job-KOWL4ITV.js");
+  logParts.push(`prepareRunId: ${prepareRun.runId}`, `prepareRunDir: ${prepareRun.runDir}`);
+  logParts.push("backend: kubernetes-job", "");
+  const result = await runSdkPrepareJob(settings, prepareRun, refSettings.preparedRoot, pin);
+  const completedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const liveLog = await readOptionalTail(prepareRun.liveLogPath, 32e3);
+  logParts.push(
+    "jobLogs:",
+    result.logs || "<pod log empty; prepare command output is captured in prepare-live.log>",
+    "",
+    "prepareLiveLog:",
+    liveLog || "<empty>",
+    `completedAt: ${completedAt}`
+  );
+  await writeInstallLog(settings, refSettings, logParts.join("\n"));
+  if (!result.succeeded) {
+    await appendPrepareRunFailureLog(prepareRun, result.logs || result.message || "SDK prepare job failed.");
+    await ensurePrepareRunFailureResult(prepareRun, completedAt, result.message ?? "SDK prepare job failed.");
+    const status2 = await writePreparedStatus(settings, refSettings, {
+      status: "failed",
+      startedAt,
+      completedAt,
+      message: firstLogLine(result.logs) ?? result.message ?? "SDK prepare job failed."
+    });
+    return { settings, status: status2, logPath: installLogPath(settings.preparedRoot) };
+  }
+  const prepareResult = await readPrepareRunResult(prepareRun.resultPath);
+  const prepareFailure = prepareResult?.status === "failed" || sdkPrepareLogLooksFailed(liveLog);
+  if (prepareFailure) {
+    const message = prepareResult?.message ?? firstPrepareLogFailure(liveLog) ?? "SDK prepare command failed.";
+    await ensurePrepareRunFailureResult(prepareRun, completedAt, message);
+    const status2 = await writePreparedStatus(settings, refSettings, {
+      status: "failed",
+      startedAt,
+      completedAt,
+      message
+    });
+    return { settings, status: status2, logPath: installLogPath(settings.preparedRoot) };
+  }
+  const commitSha = await gitOutput(settings.preparedRoot, ["rev-parse", "HEAD"], void 0);
+  try {
+    await probePreparedRuntime(settings, void 0);
+    await runPreparedRuntimeSmoke(settings);
+  } catch (error) {
+    const message = `SDK runtime smoke probe failed after prepare command completed. ${prepareFailureMessage(error)}`;
+    await appendPrepareRunFailureLog(prepareRun, message);
+    await ensurePrepareRunFailureResult(prepareRun, completedAt, message);
+    const status2 = await writePreparedStatus(settings, refSettings, {
+      status: "failed",
+      startedAt,
+      completedAt,
+      commitSha,
+      message
+    });
+    return { settings, status: status2, logPath: installLogPath(settings.preparedRoot) };
+  }
+  const status = await writePreparedStatus(settings, refSettings, {
+    status: "ready",
+    startedAt,
+    completedAt,
+    commitSha,
+    message: "SDK source runtime is ready."
+  });
+  return { settings, status, logPath: installLogPath(settings.preparedRoot) };
+}
+async function pathExists2(candidate) {
+  try {
+    await access2(candidate);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function preparedRuntimeMarkedReady(settings, commitSha, sourceFingerprint) {
+  const state = await readSdkPrepareCacheState(settings);
+  if (!sdkPrepareCacheStateMatches(settings, state, commitSha, sourceFingerprint)) return false;
+  return pathExists2(settings.pythonPath);
+}
+async function canReusePreparedRuntime(settings, commitSha, sourceFingerprint, token) {
+  const state = await readSdkPrepareCacheState(settings);
+  if (!sdkPrepareCacheStateMatches(settings, state, commitSha, sourceFingerprint)) return false;
+  try {
+    await probePreparedRuntime(settings, token);
+    await runPreparedRuntimeSmoke(settings);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function writePreparedStatus(settings, refSettings, input) {
+  const status = await writeSdkRuntimeStatus(settings, input);
+  if (settings.preparedRoot !== refSettings.preparedRoot) {
+    await writeSdkRuntimeStatus(settings, input, refSettings.preparedRoot);
+  }
+  return status;
+}
+async function writeInstallLog(settings, refSettings, text) {
+  await writeFile3(installLogPath(settings.preparedRoot), text);
+  if (settings.preparedRoot !== refSettings.preparedRoot) {
+    await writeFile3(installLogPath(refSettings.preparedRoot), text);
+  }
+}
+async function probePreparedRuntime(settings, token) {
+  await execFileAsync2(settings.pythonPath, ["-c", "import legato; import hart"], {
+    cwd: settings.preparedRoot,
+    env: prepareEnv(settings, token),
+    timeout: 6e4,
+    maxBuffer: 2 * 1024 * 1024
+  });
+}
+async function prepareSourceFingerprint(settings, token) {
+  const treeListing = await gitOutput(settings.preparedRoot, ["ls-tree", "HEAD", "--", ...SDK_PREPARE_SOURCE_PATHS], token);
+  return sdkPrepareSourceFingerprint(treeListing);
+}
+function prepareEnv(settings, token) {
+  return { ...gitEnv(token), ...sdkPrepareCacheEnv(settings) };
+}
+async function appendPrepareRunFailureLog(prepareRun, details) {
+  const trimmed = details.trim();
+  if (!trimmed) return;
+  await appendFile(prepareRun.liveLogPath, `
+
+===== SDK prepare failure diagnostics =====
+${trimmed}
+`);
+}
+async function ensurePrepareRunFailureResult(prepareRun, completedAt, message) {
+  const fallback = { status: "failed", completedAt, message };
+  try {
+    const parsed = JSON.parse(await readFile4(prepareRun.resultPath, "utf8"));
+    if (isRecord3(parsed) && typeof parsed.message === "string" && parsed.message.trim()) return;
+    const exitCode = isRecord3(parsed) && typeof parsed.exitCode === "number" ? parsed.exitCode : void 0;
+    await writeFile3(prepareRun.resultPath, `${JSON.stringify({ ...fallback, exitCode })}
+`);
+  } catch {
+    await writeFile3(prepareRun.resultPath, `${JSON.stringify(fallback)}
+`);
+  }
+}
+async function readPrepareRunResult(resultPath) {
+  try {
+    const parsed = JSON.parse(await readFile4(resultPath, "utf8"));
+    if (!isRecord3(parsed)) return void 0;
+    return {
+      status: typeof parsed.status === "string" ? parsed.status : void 0,
+      message: typeof parsed.message === "string" ? parsed.message : void 0
+    };
+  } catch {
+    return void 0;
+  }
+}
+async function verifyGitAccess(settings, token) {
+  await execFileAsync2("git", ["ls-remote", settings.repoUrl, settings.branch], {
+    env: gitEnv(token),
+    timeout: 6e4,
+    maxBuffer: 2 * 1024 * 1024
+  });
+}
+async function syncRepository(settings, token) {
+  await mkdir4(settings.preparedRoot, { recursive: true });
+  if (!await hasManagedGitWorktree(settings.preparedRoot, settings.repoUrl)) {
+    await prepareCloneTarget(settings.preparedRoot);
+    await execFileAsync2("git", ["clone", "--no-checkout", settings.repoUrl, settings.preparedRoot], {
+      env: gitEnv(token),
+      timeout: readPositiveInt3(process.env.AGORA_SDK_CLONE_TIMEOUT_MS, 6e5),
+      maxBuffer: 8 * 1024 * 1024
+    });
+  }
+  await execFileAsync2("git", ["-C", settings.preparedRoot, "remote", "set-url", "origin", settings.repoUrl], { env: gitEnv(token), timeout: 3e4 });
+  await execFileAsync2("git", ["-C", settings.preparedRoot, "reset", "--hard"], {
+    env: gitEnv(token),
+    timeout: 6e4,
+    maxBuffer: 2 * 1024 * 1024
+  });
+  await execFileAsync2("git", ["-C", settings.preparedRoot, "clean", "-ffd", "-e", ".venv/"], {
+    env: gitEnv(token),
+    timeout: 6e4,
+    maxBuffer: 2 * 1024 * 1024
+  });
+  await execFileAsync2("git", ["-C", settings.preparedRoot, "fetch", "origin", settings.branch], {
+    env: gitEnv(token),
+    timeout: readPositiveInt3(process.env.AGORA_SDK_FETCH_TIMEOUT_MS, 6e5),
+    maxBuffer: 8 * 1024 * 1024
+  });
+  await execFileAsync2("git", ["-C", settings.preparedRoot, "checkout", "--force", "--detach", "FETCH_HEAD"], {
+    env: gitEnv(token),
+    timeout: 6e4,
+    maxBuffer: 2 * 1024 * 1024
+  });
+  await execFileAsync2("git", ["-C", settings.preparedRoot, "reset", "--hard", "FETCH_HEAD"], {
+    env: gitEnv(token),
+    timeout: 6e4,
+    maxBuffer: 2 * 1024 * 1024
+  });
+}
+async function hasManagedGitWorktree(worktree, repoUrl) {
+  try {
+    const topLevel = await gitOutput(worktree, ["rev-parse", "--show-toplevel"], void 0);
+    if (await realpath(topLevel) !== await realpath(worktree)) return false;
+    const remoteUrl = await gitOutput(worktree, ["remote", "get-url", "origin"], void 0);
+    return normalizeGitRemote(remoteUrl) === normalizeGitRemote(repoUrl);
+  } catch {
+    return false;
+  }
+}
+async function prepareCloneTarget(worktree) {
+  const entries = await readdir(worktree);
+  if (entries.length === 0) return;
+  const backupPath = `${worktree}.pre-sdk-clone-${Date.now()}-${process.pid}`;
+  await rename(worktree, backupPath);
+  await mkdir4(worktree, { recursive: true });
+}
+async function gitOutput(worktree, args, token) {
+  const output = await execFileAsync2("git", ["-C", worktree, ...args], { env: gitEnv(token), timeout: 3e4 });
+  return output.stdout.trim();
+}
+async function recordPrepareFailure(settings, refSettings, startedAt, error) {
+  const failure = error;
+  const completedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const logText = [
+    ...prepareLogHeader(settings, startedAt),
+    `completedAt: ${completedAt}`,
+    "",
+    "stdout:",
+    failure.stdout || "<empty>",
+    "",
+    "stderr:",
+    sanitizeFailureText([failure.stderr, failure.message].filter(Boolean).join("\n") || "<empty>")
+  ].join("\n");
+  await mkdir4(settings.preparedRoot, { recursive: true });
+  await writeInstallLog(settings, refSettings, logText);
+  return await writePreparedStatus(settings, refSettings, {
+    status: "failed",
+    startedAt,
+    completedAt,
+    message: prepareFailureMessage(failure)
+  });
+}
+function prepareLogHeader(settings, startedAt) {
+  return [
+    `repoUrl: ${settings.repoUrl}`,
+    `branch: ${settings.branch}`,
+    `runtimeRoot: ${settings.runtimeRoot}`,
+    `preparedRoot: ${settings.preparedRoot}`,
+    `prepareCommand: ${settings.prepareCommand}`,
+    `startedAt: ${startedAt}`,
+    ""
+  ];
+}
+async function readOptionalTail(filePath, maxChars) {
+  try {
+    const text = await readFile4(filePath, "utf8");
+    return text.length > maxChars ? text.slice(-maxChars) : text;
+  } catch {
+    return "";
+  }
+}
+function readPositiveInt3(value, fallback) {
+  if (!value) return fallback;
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+function sanitizeFailureText(message) {
+  return message.replace(/(AUTHORIZATION: basic )[A-Za-z0-9+/=]+/gi, "$1[redacted]");
+}
+function prepareFailureMessage(failure) {
+  const text = sanitizeFailureText([failure.stderr, failure.message].filter(Boolean).join("\n"));
+  return firstLogLine(text) ?? "SDK source runtime preparation failed.";
+}
+function sdkPrepareLogLooksFailed(text) {
+  return /(?:× Failed to build|Failed to build `|Prepare command failed with exit|returned non-zero exit status|CMake Error|error: invalid linker name)/.test(text);
+}
+function firstPrepareLogFailure(text) {
+  return text.split("\n").map((line) => line.trim()).find((line) => sdkPrepareLogLooksFailed(line));
+}
+function firstLogLine(text) {
+  return text.split("\n").map((line) => line.trim()).find(Boolean);
+}
+function isRecord3(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeGitRemote(remote) {
+  return remote.trim().replace(/\.git$/, "");
+}
+export {
+  prepareSdkRuntime,
+  readSdkRuntimeSettings,
+  readSdkRuntimeStatus,
+  sdkRuntimeExtraPythonPath,
+  writeSdkRuntimeSettings
+};