@melaya/runner 1.1.30 → 1.1.32

package/dist/cli.js

@@ -52,14 +52,33 @@ async function main() {
         .parse(process.argv);
     const opts = program.opts();
     console.log(BANNER);
-    // Detect Python
-    const python = await findPython();
-    if (!python) {
-        console.log(chalk.red("  ✗ Python not found in PATH"));
-        console.log(chalk.gray("    Install Python 3.11+ from https://python.org"));
-        process.exit(1);
+    // Detect Python. Fast path: a supported host interpreter (3.10–3.12). If the
+    // host only has an unsupported/newer Python (Homebrew now ships 3.13/3.14 as
+    // `python3`) — or none at all — we PROVISION a managed CPython 3.12 via uv, so
+    // the runner needs zero Python setup on the box. `venv` can't do this (it only
+    // wraps an existing interpreter); uv downloads a standalone one.
+    let python;
+    const py = await findPython();
+    if (py.ok) {
+        python = py.cmd;
+        console.log(chalk.green(`  ✓ Python: ${python} (3.${py.minor})`));
+    }
+    else {
+        console.log(chalk.yellow(`  ⚠ No supported host Python (need 3.${PY_MIN_MINOR}–3.${PY_MAX_MINOR}` +
+            `${py.foundVersion ? `; host has ${py.foundVersion}` : ""}) — provisioning one automatically`));
+        const { provisionPython } = await import("./uvBootstrap.js");
+        const provisioned = await provisionPython(`3.${PY_MAX_MINOR}`, (m) => console.log(chalk.gray(`    ${m}`)));
+        if (!provisioned) {
+            console.log(chalk.red(`  ✗ Could not auto-provision Python 3.${PY_MAX_MINOR}`));
+            console.log(chalk.gray("    Install a supported Python manually, then restart the runner:"));
+            console.log(chalk.gray("      macOS:   brew install python@3.12"));
+            console.log(chalk.gray("      Linux:   sudo apt install python3.12 python3.12-venv    (or: pyenv install 3.12)"));
+            console.log(chalk.gray("      Windows: winget install Python.Python.3.12"));
+            process.exit(1);
+        }
+        python = provisioned;
+        console.log(chalk.green(`  ✓ Python: ${python} (auto-provisioned 3.${PY_MAX_MINOR})`));
     }
-    console.log(chalk.green(`  ✓ Python: ${python}`));
     // Detect local models
     const models = await detectModels();
     if (models.length === 0) {
@@ -81,17 +100,67 @@ async function main() {
         verbose: opts.verbose,
     });
 }
-async function findPython() {
+// Supported CPython range for the runner's venv. agentscope and its native
+// deps (tiktoken, numpy, pydantic-core, curl_cffi via scrapling, sentence-
+// transformers, …) only ship wheels for 3.10–3.12. Building the venv from a
+// 3.13 interpreter — which is now Homebrew's default `python3` — leaves those
+// deps unbuilt, so `import agentscope` fails the probe and every assistant /
+// pipeline turn dies with "agentscope import probe failed". So we must NOT
+// grab the first `python3` on PATH: we rank interpreters and pick a supported
+// minor, only reporting the unsupported one (with install guidance) if that's
+// all that exists. Bump PY_MAX_MINOR once the dep set is validated on a newer
+// CPython.
+const PY_MIN_MINOR = 10;
+const PY_MAX_MINOR = 12;
+async function probePyVersion(cmd) {
     const { execSync } = await import("child_process");
-    for (const cmd of ["python3", "python"]) {
-        try {
-            const version = execSync(`${cmd} --version`, { encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] }).trim();
-            if (version.includes("Python 3."))
-                return cmd;
+    try {
+        const out = execSync(`"${cmd}" --version`, { encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] }).trim();
+        const m = out.match(/Python (\d+)\.(\d+)/);
+        if (!m)
+            return null;
+        return { major: Number(m[1]), minor: Number(m[2]) };
+    }
+    catch {
+        return null;
+    }
+}
+async function findPython() {
+    const candidates = [];
+    // 1. Explicit supported-minor binaries first, newest supported first. Homebrew
+    //    (`brew install python@3.12`) and pyenv both expose these names on PATH,
+    //    so this catches a supported interpreter even when bare `python3` is 3.13.
+    for (let m = PY_MAX_MINOR; m >= PY_MIN_MINOR; m--)
+        candidates.push(`python3.${m}`);
+    // 2. Common absolute install locations, in case PATH points `python3` at 3.13
+    //    but a supported keg is installed and simply not linked onto PATH.
+    for (let m = PY_MAX_MINOR; m >= PY_MIN_MINOR; m--) {
+        if (process.platform === "darwin") {
+            candidates.push(`/opt/homebrew/opt/python@3.${m}/bin/python3.${m}`, // Apple-silicon brew keg
+            `/usr/local/opt/python@3.${m}/bin/python3.${m}`, // Intel brew keg
+            `/opt/homebrew/bin/python3.${m}`, `/usr/local/bin/python3.${m}`);
         }
-        catch { /* not found */ }
+        else if (process.platform === "linux") {
+            candidates.push(`/usr/bin/python3.${m}`, `/usr/local/bin/python3.${m}`);
+        }
+    }
+    // 3. Generic names last — accepted only if they resolve into the supported range.
+    candidates.push("python3", "python");
+    let fallback; // a real 3.x that exists but is out of range
+    const seen = new Set();
+    for (const cmd of candidates) {
+        if (seen.has(cmd))
+            continue;
+        seen.add(cmd);
+        const v = await probePyVersion(cmd);
+        if (!v || v.major !== 3)
+            continue;
+        if (v.minor >= PY_MIN_MINOR && v.minor <= PY_MAX_MINOR)
+            return { ok: true, cmd, minor: v.minor };
+        if (!fallback)
+            fallback = `Python ${v.major}.${v.minor}`;
     }
-    return null;
+    return { ok: false, foundVersion: fallback };
 }
 // `melaya-runner copilot login` — GitHub Copilot device-flow sign-in, cached
 // locally. Handled before the runner arg-parse so it needs no --token.

package/dist/pythonEnv.js

@@ -10,7 +10,7 @@
  * shared-bundle version. Re-bootstraps when the bundle version changes.
  */
 import { spawn } from "child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "fs";
 import { createHash } from "crypto";
 import { join } from "path";
 import { homedir, platform } from "os";
@@ -19,6 +19,29 @@ const CACHE_DIR = join(homedir(), ".melaya-runner");
 const VENV_DIR = join(CACHE_DIR, "venv");
 const VENV_MARK = join(CACHE_DIR, "venv-version.txt");
 const AGENTSCOPE = join(CACHE_DIR, "agentscope");
+// Supported CPython range for the venv — MUST match cli.ts's findPython(). A
+// venv is a thin wrapper frozen to the interpreter that created it, so one
+// built from an unsupported minor (e.g. a pre-fix runner that grabbed
+// Homebrew's python3.13) can never install agentscope's deps and its import
+// probe always fails. We detect that from pyvenv.cfg and rebuild automatically.
+const PY_SUPPORTED_MIN = 10;
+const PY_SUPPORTED_MAX = 12;
+// The minor version a venv was built from, read from its pyvenv.cfg
+// (`version = 3.12.4`). Returns null if the file is missing/unparseable.
+function venvMinorVersion() {
+    try {
+        const cfg = readFileSync(join(VENV_DIR, "pyvenv.cfg"), "utf-8");
+        const m = cfg.match(/version(?:_info)?\s*=\s*3\.(\d+)/i);
+        return m ? Number(m[1]) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function venvVersionSupported() {
+    const minor = venvMinorVersion();
+    return minor !== null && minor >= PY_SUPPORTED_MIN && minor <= PY_SUPPORTED_MAX;
+}
 // Explicit dependency list. The shared-bundle endpoint ships only
 // `*.py` files — no pyproject.toml — so `pip install -e
 // ~/.melaya-runner/agentscope` does NOT work (pip can't find a project
@@ -243,6 +266,11 @@ function venvIsValid(expectedVersion) {
         return false;
     if (!existsSync(VENV_MARK))
         return false;
+    // A venv built from an unsupported Python is never "valid", regardless of the
+    // marker — this forces the rebuild path (which recreates it from a supported
+    // interpreter) instead of self-healing a doomed venv.
+    if (!venvVersionSupported())
+        return false;
     try {
         const cached = readFileSync(VENV_MARK, "utf-8").trim();
         return cached === venvMarkerValue(expectedVersion);
@@ -376,6 +404,28 @@ export async function ensurePythonEnv(systemPython, expectedVersion, onProgress
         };
     }
     mkdirSync(CACHE_DIR, { recursive: true });
+    // Step 0: heal a venv left behind by a runner that built it from an
+    // unsupported interpreter (the classic case: a pre-fix runner grabbed
+    // Homebrew's python3.13, so agentscope's deps never installed and the import
+    // probe fails forever). A venv's Python is frozen at creation, so the only
+    // fix is to delete and recreate it from `systemPython` — which the CLI now
+    // guarantees is a supported 3.10–3.12. Fully automatic: no "delete the venv
+    // and restart" by hand.
+    if (existsSync(venvPython()) && !venvVersionSupported()) {
+        const minor = venvMinorVersion();
+        onProgress(`existing venv is Python ${minor === null ? "unknown" : `3.${minor}`} ` +
+            `(unsupported — need 3.${PY_SUPPORTED_MIN}–3.${PY_SUPPORTED_MAX}); rebuilding it`);
+        try {
+            rmSync(VENV_DIR, { recursive: true, force: true });
+        }
+        catch (e) {
+            return {
+                ok: false,
+                pythonPath: systemPython,
+                reason: `could not remove the stale venv at ${VENV_DIR} (${e?.message}). Delete it manually and restart the runner.`,
+            };
+        }
+    }
     // Step 1: create the venv if missing.
     if (!existsSync(venvPython())) {
         onProgress(`creating venv at ${VENV_DIR} (one-time, ~5s)`);
@@ -439,19 +489,22 @@ export async function ensurePythonEnv(systemPython, expectedVersion, onProgress
     // identical whether the venv is fresh or already valid.
     await ensureNltkData(onProgress);
     await _resolveAndCacheCertBundle(onProgress);
-    writeFileSync(VENV_MARK, venvMarkerValue(expectedVersion), "utf-8");
     // sanity: confirm shortuuid + agentscope (via PYTHONPATH) resolve now.
     // Probe must mirror the spawn env so PYTHONPATH=CACHE_DIR points at
     // the cached agentscope source — without this the probe ImportError's
-    // even though the real spawn would work.
+    // even though the real spawn would work. The marker is written ONLY after
+    // this passes, so a half-built venv is never cached as valid: the next
+    // launch re-enters this rebuild path and self-heals instead of returning a
+    // broken venv as ok.
     const probe = await runProc(venvPython(), ["-c", "import shortuuid, agentscope, anthropic, openai"], onProgress, { PYTHONPATH: CACHE_DIR });
     if (probe !== 0) {
         return {
             ok: false,
             pythonPath: systemPython,
-            reason: "venv created but agentscope import probe failed. Delete ~/.melaya-runner/venv and restart the runner.",
+            reason: `agentscope import probe failed on the ${venvMinorVersion() === null ? "" : `Python 3.${venvMinorVersion()} `}venv — the deps above did not import. See the pip lines above for the cause; the venv will be rebuilt on next launch.`,
         };
     }
+    writeFileSync(VENV_MARK, venvMarkerValue(expectedVersion), "utf-8");
     onProgress(`✓ venv ready (python=${venvPython()})`);
     return { ok: true, pythonPath: venvPython() };
 }

package/dist/uvBootstrap.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Zero-setup Python provisioning.
+ *
+ * `python -m venv` does NOT install a Python — it creates a thin environment
+ * that symlinks back to an existing interpreter, frozen to that interpreter's
+ * version. So when the host has no supported Python (e.g. Homebrew now ships
+ * 3.13/3.14 as `python3`, which has no wheels for agentscope's native deps),
+ * the runner can't build a working venv no matter what.
+ *
+ * This module removes the requirement for a host Python entirely: it uses
+ * `uv` (a single static binary) to download a *managed, standalone* CPython of
+ * the supported version and returns its interpreter path. The existing venv
+ * pipeline then builds from that. `uv` itself is bootstrapped from its official
+ * GitHub release if it isn't already installed — no `brew install`, no manual
+ * steps. All failures degrade to `null` so the caller can fall back to a clear
+ * "install Python 3.12" message.
+ */
+type Log = (m: string) => void;
+export declare function localUvPath(): string;
+/**
+ * Provision a supported CPython with NO host Python required. Downloads a
+ * managed standalone CPython of `version` via uv (bootstrapping uv itself if
+ * needed) and returns its interpreter path — which the venv pipeline builds
+ * from. Returns null if provisioning isn't possible (offline, unsupported
+ * platform, tar missing), so the caller can show manual-install guidance.
+ */
+export declare function provisionPython(version: string, onLine: Log): Promise<string | null>;
+export {};

package/dist/uvBootstrap.js

@@ -0,0 +1,213 @@
+/**
+ * Zero-setup Python provisioning.
+ *
+ * `python -m venv` does NOT install a Python — it creates a thin environment
+ * that symlinks back to an existing interpreter, frozen to that interpreter's
+ * version. So when the host has no supported Python (e.g. Homebrew now ships
+ * 3.13/3.14 as `python3`, which has no wheels for agentscope's native deps),
+ * the runner can't build a working venv no matter what.
+ *
+ * This module removes the requirement for a host Python entirely: it uses
+ * `uv` (a single static binary) to download a *managed, standalone* CPython of
+ * the supported version and returns its interpreter path. The existing venv
+ * pipeline then builds from that. `uv` itself is bootstrapped from its official
+ * GitHub release if it isn't already installed — no `brew install`, no manual
+ * steps. All failures degrade to `null` so the caller can fall back to a clear
+ * "install Python 3.12" message.
+ */
+import { existsSync, mkdirSync, writeFileSync, chmodSync, rmSync, readdirSync, statSync, copyFileSync } from "fs";
+import { join } from "path";
+import { homedir, platform, arch } from "os";
+import { spawn, execSync } from "child_process";
+const CACHE_DIR = join(homedir(), ".melaya-runner");
+const BIN_DIR = join(CACHE_DIR, "bin");
+const isWin = platform() === "win32";
+function uvBinName() { return isWin ? "uv.exe" : "uv"; }
+export function localUvPath() { return join(BIN_DIR, uvBinName()); }
+// Release asset for this platform/arch, from github.com/astral-sh/uv/releases.
+function assetName() {
+    const p = platform(), a = arch();
+    if (p === "darwin")
+        return a === "arm64" ? "uv-aarch64-apple-darwin.tar.gz" : "uv-x86_64-apple-darwin.tar.gz";
+    if (p === "linux") {
+        if (a === "arm64")
+            return "uv-aarch64-unknown-linux-gnu.tar.gz";
+        if (a === "x64")
+            return "uv-x86_64-unknown-linux-gnu.tar.gz";
+        return null; // unusual arch — fall back to manual install guidance
+    }
+    if (p === "win32")
+        return a === "arm64" ? "uv-aarch64-pc-windows-msvc.zip" : "uv-x86_64-pc-windows-msvc.zip";
+    return null;
+}
+function tryExec(cmd) {
+    try {
+        return execSync(cmd, { encoding: "utf-8", timeout: 8000, stdio: ["pipe", "pipe", "pipe"] }).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+function findOnPath(bin) {
+    const out = tryExec(isWin ? `where ${bin}` : `command -v ${bin}`);
+    if (!out)
+        return null;
+    const first = out.split(/\r?\n/)[0].trim();
+    return first || null;
+}
+// Inactivity-bounded child runner (mirrors pythonEnv.runProc): a managed-CPython
+// download legitimately takes a while but streams progress, so we bound silence.
+function run(cmd, args, onLine, inactivityMs = 5 * 60_000) {
+    return new Promise((resolve) => {
+        const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"], env: process.env });
+        let done = false;
+        let timer;
+        const finish = (c) => { if (done)
+            return; done = true; if (timer)
+            clearTimeout(timer); resolve(c); };
+        const bump = () => {
+            if (timer)
+                clearTimeout(timer);
+            timer = setTimeout(() => { try {
+                child.kill("SIGKILL");
+            }
+            catch { /* gone */ } onLine(`(no output for ${Math.round(inactivityMs / 60000)}m — killed ${cmd})`); finish(1); }, inactivityMs);
+        };
+        const chew = (b) => { bump(); for (const ln of b.toString().split("\n")) {
+            const t = ln.trimEnd();
+            if (t)
+                onLine(t);
+        } };
+        child.stdout?.on("data", chew);
+        child.stderr?.on("data", chew);
+        child.on("exit", (c) => finish(c ?? 1));
+        child.on("error", () => finish(1));
+        bump();
+    });
+}
+function capture(cmd, args) {
+    return new Promise((resolve) => {
+        let out = "";
+        const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"], env: process.env });
+        child.stdout?.on("data", (b) => { out += b.toString(); });
+        child.on("exit", () => resolve(out.trim()));
+        child.on("error", () => resolve(""));
+    });
+}
+function findBinaryRecursive(dir, name) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return null;
+    }
+    for (const e of entries) {
+        const full = join(dir, e);
+        let st;
+        try {
+            st = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory()) {
+            const found = findBinaryRecursive(full, name);
+            if (found)
+                return found;
+        }
+        else if (e === name)
+            return full;
+    }
+    return null;
+}
+// Download + extract the uv binary from its latest GitHub release. The
+// `/releases/latest/download/<asset>` path redirects to the newest asset, so we
+// track upstream without pinning a possibly-nonexistent tag. tar handles the
+// .tar.gz on macOS/Linux and (via bsdtar) the .zip on Windows.
+async function downloadUv(onLine) {
+    const asset = assetName();
+    if (!asset) {
+        onLine(`no uv build available for ${platform()}/${arch()}`);
+        return null;
+    }
+    const url = `https://github.com/astral-sh/uv/releases/latest/download/${asset}`;
+    mkdirSync(BIN_DIR, { recursive: true });
+    const tmp = join(BIN_DIR, "_dl");
+    try {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+    catch { /* fresh */ }
+    mkdirSync(tmp, { recursive: true });
+    const archivePath = join(tmp, asset);
+    onLine(`downloading uv (${asset})`);
+    try {
+        const res = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(120_000) });
+        if (!res.ok) {
+            onLine(`uv download failed: HTTP ${res.status}`);
+            return null;
+        }
+        writeFileSync(archivePath, Buffer.from(await res.arrayBuffer()));
+    }
+    catch (e) {
+        onLine(`uv download error: ${e?.message}`);
+        return null;
+    }
+    onLine("extracting uv");
+    const code = await run("tar", ["-xf", archivePath, "-C", tmp], onLine);
+    if (code !== 0) {
+        onLine("tar extraction of uv failed (is `tar` available?)");
+        return null;
+    }
+    const found = findBinaryRecursive(tmp, uvBinName());
+    if (!found) {
+        onLine("uv binary not found inside the downloaded archive");
+        return null;
+    }
+    const dest = localUvPath();
+    try {
+        copyFileSync(found, dest);
+        if (!isWin)
+            chmodSync(dest, 0o755);
+    }
+    catch (e) {
+        onLine(`could not install uv to ${dest}: ${e?.message}`);
+        return null;
+    }
+    try {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+    catch { /* best-effort cleanup */ }
+    return dest;
+}
+async function ensureUv(onLine) {
+    if (existsSync(localUvPath()))
+        return localUvPath(); // previously downloaded
+    const onPath = findOnPath(uvBinName());
+    if (onPath)
+        return onPath; // operator already has uv
+    return downloadUv(onLine); // bootstrap it
+}
+/**
+ * Provision a supported CPython with NO host Python required. Downloads a
+ * managed standalone CPython of `version` via uv (bootstrapping uv itself if
+ * needed) and returns its interpreter path — which the venv pipeline builds
+ * from. Returns null if provisioning isn't possible (offline, unsupported
+ * platform, tar missing), so the caller can show manual-install guidance.
+ */
+export async function provisionPython(version, onLine) {
+    const uv = await ensureUv(onLine);
+    if (!uv)
+        return null;
+    onLine(`installing a managed Python ${version} (one-time; ~30-60s)`);
+    const code = await run(uv, ["python", "install", version], onLine);
+    if (code !== 0) {
+        onLine(`uv python install ${version} failed`);
+        return null;
+    }
+    const path = await capture(uv, ["python", "find", version]);
+    if (path && existsSync(path))
+        return path;
+    onLine(`uv could not resolve a Python ${version} interpreter path after install`);
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@melaya/runner",
-  "version": "1.1.30",
+  "version": "1.1.32",
   "description": "Run Melaya AI pipelines locally with your own LM Studio or Ollama models",
   "license": "UNLICENSED",
   "private": false,