@melaya/runner 1.1.30 → 1.1.31

package/dist/cli.js

@@ -53,13 +53,25 @@ async function main() {
     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"));
+    const py = await findPython();
+    if (!py.ok) {
+        if (py.foundVersion) {
+            console.log(chalk.red(`  ✗ ${py.foundVersion} found, but Melaya needs Python 3.${PY_MIN_MINOR}–3.${PY_MAX_MINOR}`));
+            console.log(chalk.gray("    Python 3.13+ has no wheels yet for the assistant's Python deps (agentscope + native"));
+            console.log(chalk.gray("    extensions), so the runner's venv can't build and every assistant turn fails."));
+            console.log(chalk.gray("    Install a supported Python, 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"));
+        }
+        else {
+            console.log(chalk.red("  ✗ Python not found in PATH"));
+            console.log(chalk.gray("    Install Python 3.12 from https://python.org"));
+        }
         process.exit(1);
     }
-    console.log(chalk.green(`  ✓ Python: ${python}`));
+    const python = py.cmd;
+    console.log(chalk.green(`  ✓ Python: ${python} (3.${py.minor})`));
     // Detect local models
     const models = await detectModels();
     if (models.length === 0) {
@@ -81,17 +93,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/package.json

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