@melaya/runner 1.0.24 → 1.0.27

package/dist/connection.js

@@ -104,6 +104,58 @@ export async function connect(opts) {
             }
             // Ensure shared modules are cached
             await ensureSharedModules(opts.serverUrl, payload.sharedVersion);
+            // Ensure the dedicated venv at ~/.melaya-runner/venv/ has
+            // agentscope + its transitive deps installed. Without this, the
+            // operator's system python3 typically doesn't have shortuuid /
+            // anthropic / openai / opentelemetry / etc. pre-installed and
+            // every pipeline run crashes during `import agentscope` with a
+            // ModuleNotFoundError. The venv is created lazily on first run
+            // and reused until sharedVersion changes.
+            const { ensurePythonEnv } = await import("./pythonEnv.js");
+            const envResult = await ensurePythonEnv(opts.pythonPath, payload.sharedVersion, (msg) => {
+                console.log(chalk.gray(`  [venv] ${msg}`));
+                // Surface bootstrap progress to the FE so the launching
+                // animation reflects the real state instead of staying on a
+                // generic spinner during the 1-2 min first-time install.
+                socket.emit("runner:event", {
+                    runId: payload.runId,
+                    payload: {
+                        event_type: "pipeline_phase",
+                        run_id: payload.runId,
+                        project: payload.project,
+                        step: 1,
+                        total: 5,
+                        label: `venv: ${msg}`,
+                        status: "started",
+                    },
+                });
+            });
+            if (!envResult.ok) {
+                console.log(chalk.red(`  ✗ python venv bootstrap failed: ${envResult.reason}`));
+                socket.emit("runner:event", {
+                    runId: payload.runId,
+                    payload: {
+                        event_type: "agent_message",
+                        run_id: payload.runId,
+                        project: payload.project,
+                        replyId: `venv-${payload.runId}`,
+                        replyName: "Runner",
+                        replyRole: "system",
+                        msg: {
+                            id: `venv-${payload.runId}`,
+                            name: "Runner",
+                            role: "system",
+                            content: [{ type: "text", text: `Python env bootstrap failed: ${envResult.reason}` }],
+                            metadata: {},
+                            timestamp: new Date().toISOString(),
+                        },
+                    },
+                });
+                socket.emit("runner:runComplete", { runId: payload.runId, status: "failed" });
+                return;
+            }
+            // Replace the system python with the venv python for THIS spawn.
+            const pipelinePython = envResult.pythonPath;
             // Register run in DB + set active project for event relay
             setActiveProject(payload.project);
             socket.emit("runner:registerRun", {
@@ -116,6 +168,58 @@ export async function connect(opts) {
             mkdirSync(runDir, { recursive: true });
             writeFileSync(join(runDir, "main.py"), payload.mainPyContent, "utf-8");
             writeFileSync(join(runDir, "config.json"), payload.configJson, "utf-8");
+            // Local-model preflight: ensure LM Studio / Ollama have the
+            // pipeline's model loaded BEFORE we spawn the Python subprocess.
+            // Without this, the subprocess hangs on its first chat completion
+            // call (LM Studio JIT-loads transparently, can take 60-120s with
+            // zero progress feedback). Pipeline run d5ead8b8655b47fa hit this
+            // — only the `format openai` span landed, no `chat …` span ever
+            // arrived because LM Studio was still loading the qwen weights.
+            const { preflightModel } = await import("./modelLoader.js");
+            const onPreflightProgress = (msg) => {
+                console.log(chalk.gray(`  [model] ${msg}`));
+                // Surface to the FE via a pipeline_phase event so the launching
+                // animation reflects "Loading qwen3-vl-8b…" instead of staying
+                // on a generic spinner.
+                socket.emit("runner:event", {
+                    runId: payload.runId,
+                    payload: {
+                        event_type: "pipeline_phase",
+                        run_id: payload.runId,
+                        project: payload.project,
+                        step: 1,
+                        total: 5,
+                        label: msg,
+                        status: "started",
+                    },
+                });
+            };
+            const preflight = await preflightModel(payload.configJson, onPreflightProgress);
+            if (!preflight.ok) {
+                const detail = `${preflight.reason ?? "unknown"}${preflight.hint ? ` — ${preflight.hint}` : ""}`;
+                console.log(chalk.red(`  ✗ model preflight failed: ${detail}`));
+                socket.emit("runner:event", {
+                    runId: payload.runId,
+                    payload: {
+                        event_type: "agent_message",
+                        run_id: payload.runId,
+                        project: payload.project,
+                        replyId: `preflight-${payload.runId}`,
+                        replyName: "Runner",
+                        replyRole: "system",
+                        msg: {
+                            id: `preflight-${payload.runId}`,
+                            name: "Runner",
+                            role: "system",
+                            content: [{ type: "text", text: `Model preflight failed: ${detail}` }],
+                            metadata: {},
+                            timestamp: new Date().toISOString(),
+                        },
+                    },
+                });
+                socket.emit("runner:runComplete", { runId: payload.runId, status: "failed" });
+                return;
+            }
             // Build env vars for the subprocess
             const relayUrl = `http://127.0.0.1:${relay.port}/events/relay/${relay.nonce}`;
             const sharedDir = getSharedDir();
@@ -147,26 +251,67 @@ export async function connect(opts) {
                     }
                     : {}),
             };
-            // Spawn Python subprocess
-            const proc = spawn(opts.pythonPath, ["-u", join(runDir, "main.py")], {
+            // Spawn Python subprocess (uses the bootstrapped venv python).
+            const proc = spawn(pipelinePython, ["-u", join(runDir, "main.py")], {
                 cwd: runDir,
                 env,
                 stdio: ["ignore", "pipe", "pipe"],
             });
             activeProcesses.set(payload.runId, proc);
+            // Ring buffer of recent stderr — surfaced to the FE on non-zero
+            // exit so the operator sees the actual Python traceback in the
+            // chat panel instead of a silent "failed" with no context.
+            // Capped at 60 lines so a noisy traceback can't OOM us.
+            const stderrTail = [];
+            const STDERR_TAIL_MAX = 60;
             proc.stdout?.on("data", (data) => {
                 const line = data.toString().trim();
                 if (line && opts.verbose)
                     console.log(chalk.gray(`  [stdout] ${line}`));
             });
             proc.stderr?.on("data", (data) => {
-                const line = data.toString().trim();
-                if (line)
-                    console.log(chalk.yellow(`  [stderr] ${line}`));
+                const text = data.toString();
+                for (const ln of text.split("\n")) {
+                    const t = ln.trimEnd();
+                    if (!t)
+                        continue;
+                    console.log(chalk.yellow(`  [stderr] ${t}`));
+                    stderrTail.push(t);
+                    if (stderrTail.length > STDERR_TAIL_MAX)
+                        stderrTail.shift();
+                }
             });
             proc.on("exit", (code) => {
                 activeProcesses.delete(payload.runId);
                 const status = code === 0 ? "done" : "failed";
+                // On non-zero exit, relay the captured stderr tail to the FE
+                // as a system agent_message so the operator sees the actual
+                // failure reason. Without this, a Python crash before
+                // agentscope.init() runs (bad import, missing dep, syntax
+                // error in generated main.py) shows up only as a silent
+                // run_status:failed and the user has no clue what happened.
+                if (status === "failed" && stderrTail.length > 0) {
+                    const tail = stderrTail.slice(-15).join("\n");
+                    socket.emit("runner:event", {
+                        run_id: payload.runId,
+                        event_type: "agent_message",
+                        project: payload.project,
+                        replyId: `runner-exit-${payload.runId}`,
+                        replyName: "Runner",
+                        replyRole: "system",
+                        msg: {
+                            id: `runner-exit-${payload.runId}`,
+                            name: "Runner",
+                            role: "system",
+                            content: [{
+                                    type: "text",
+                                    text: `Pipeline exited with code ${code}. Last stderr:\n\`\`\`\n${tail}\n\`\`\``,
+                                }],
+                            metadata: { exitCode: code },
+                            timestamp: new Date().toISOString(),
+                        },
+                    });
+                }
                 // Emit run_status FIRST (before runComplete deletes from ownedRunIds)
                 socket.emit("runner:event", {
                     run_id: payload.runId,

package/dist/modelLoader.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Local-runner preflight: ensure the LLM model the pipeline is about to
+ * call is actually loaded in LM Studio / pulled in Ollama before we spawn
+ * the Python subprocess.
+ *
+ * Why this exists:
+ *   - LM Studio's OpenAI-compat `/v1/chat/completions` will JIT-load a
+ *     downloaded model on first request, but the request blocks for the
+ *     entire load (60-120s for 8B-class quantised models). The pipeline
+ *     subprocess sees no progress, the FE sees a stalled "Launching
+ *     pipeline" spinner, the agent's first ChatResponse never arrives.
+ *     Run d5ead8b8655b47fa hit this exactly: 1 `format openai` span, no
+ *     `chat ...` span, no messages.
+ *   - Ollama works similarly — first call to a model that isn't pulled
+ *     will fail with "model not found"; downloads have to be explicit.
+ *
+ * What we do:
+ *   1. Read the model name + provider from the pipeline's config.json.
+ *   2. For lmstudio: GET /api/v0/models to see {id, state} for every
+ *      model. If state="loaded" we're good. If state="not-loaded" we
+ *      POST a tiny chat completion to force the JIT load while
+ *      surfacing progress to the operator's stderr + emitting a
+ *      socket event so the FE can show "Loading qwen/qwen3-vl-8b…".
+ *      If model isn't in the list at all → fail fast with a clear
+ *      "open LM Studio and download <name>" message.
+ *   3. For ollama: GET /api/tags. If model not present → fail fast with
+ *      `ollama pull <name>` instruction. If present, ollama auto-loads.
+ */
+export interface ModelPreflightResult {
+    ok: boolean;
+    reason?: string;
+    hint?: string;
+    loaded?: boolean;
+}
+export declare function preflightLmStudio(modelName: string, onProgress?: (msg: string) => void): Promise<ModelPreflightResult>;
+export declare function preflightOllama(modelName: string, onProgress?: (msg: string) => void): Promise<ModelPreflightResult>;
+/**
+ * Top-level preflight — resolves the provider/model from the pipeline
+ * config and dispatches to the right helper. Returns immediately for
+ * non-local providers (cloud-spawn shouldn't reach the runner anyway).
+ */
+export declare function preflightModel(configJson: string, onProgress?: (msg: string) => void): Promise<ModelPreflightResult>;

package/dist/modelLoader.js

@@ -0,0 +1,225 @@
+/**
+ * Local-runner preflight: ensure the LLM model the pipeline is about to
+ * call is actually loaded in LM Studio / pulled in Ollama before we spawn
+ * the Python subprocess.
+ *
+ * Why this exists:
+ *   - LM Studio's OpenAI-compat `/v1/chat/completions` will JIT-load a
+ *     downloaded model on first request, but the request blocks for the
+ *     entire load (60-120s for 8B-class quantised models). The pipeline
+ *     subprocess sees no progress, the FE sees a stalled "Launching
+ *     pipeline" spinner, the agent's first ChatResponse never arrives.
+ *     Run d5ead8b8655b47fa hit this exactly: 1 `format openai` span, no
+ *     `chat ...` span, no messages.
+ *   - Ollama works similarly — first call to a model that isn't pulled
+ *     will fail with "model not found"; downloads have to be explicit.
+ *
+ * What we do:
+ *   1. Read the model name + provider from the pipeline's config.json.
+ *   2. For lmstudio: GET /api/v0/models to see {id, state} for every
+ *      model. If state="loaded" we're good. If state="not-loaded" we
+ *      POST a tiny chat completion to force the JIT load while
+ *      surfacing progress to the operator's stderr + emitting a
+ *      socket event so the FE can show "Loading qwen/qwen3-vl-8b…".
+ *      If model isn't in the list at all → fail fast with a clear
+ *      "open LM Studio and download <name>" message.
+ *   3. For ollama: GET /api/tags. If model not present → fail fast with
+ *      `ollama pull <name>` instruction. If present, ollama auto-loads.
+ */
+import chalk from "chalk";
+const LMSTUDIO_BASE = process.env.LMSTUDIO_BASE_URL || "http://127.0.0.1:1234";
+const OLLAMA_BASE = process.env.OLLAMA_BASE_URL || "http://127.0.0.1:11434";
+// JIT-load timeout. 8B-class quantised models on M-series Macs typically
+// load in 30-60s; bigger models or slow disks can take longer. We give
+// 180s total before declaring the load stuck. Below this the runner
+// simply prints progress.
+const LMSTUDIO_LOAD_TIMEOUT_MS = 180_000;
+async function fetchWithTimeout(url, init = {}) {
+    const { timeoutMs = 5_000, ...rest } = init;
+    return fetch(url, { ...rest, signal: AbortSignal.timeout(timeoutMs) });
+}
+async function listLmStudioModels() {
+    try {
+        // /api/v0/models returns an array WITH `state` (loaded/not-loaded).
+        // /v1/models returns OpenAI-shape without state. We prefer v0 for
+        // the state field; fall back to v1 if v0 returns 404 on older
+        // LM Studio versions.
+        const r = await fetchWithTimeout(`${LMSTUDIO_BASE}/api/v0/models`, { timeoutMs: 3_000 });
+        if (r.ok) {
+            const j = await r.json();
+            const arr = Array.isArray(j) ? j : (j.data ?? []);
+            return arr;
+        }
+        if (r.status === 404) {
+            const r2 = await fetchWithTimeout(`${LMSTUDIO_BASE}/v1/models`, { timeoutMs: 3_000 });
+            if (!r2.ok)
+                return null;
+            const j = await r2.json();
+            // No state field — treat as state-unknown so we fall through to
+            // a JIT-load attempt below.
+            return (j.data ?? []).map((m) => ({ id: m.id }));
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+async function jitLoadLmStudioModel(modelId, onProgress) {
+    // POST a 1-token chat completion; LM Studio JIT-loads the model and
+    // blocks until it's resident. We use a small max_tokens so the actual
+    // generation cost is negligible — what we care about is the load
+    // happening before the real pipeline call.
+    const start = Date.now();
+    const tick = setInterval(() => {
+        const elapsed = ((Date.now() - start) / 1000).toFixed(0);
+        onProgress(`still loading ${modelId} (${elapsed}s elapsed)…`);
+    }, 10_000);
+    try {
+        const r = await fetchWithTimeout(`${LMSTUDIO_BASE}/v1/chat/completions`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                model: modelId,
+                messages: [{ role: "user", content: "." }],
+                max_tokens: 1,
+                stream: false,
+            }),
+            timeoutMs: LMSTUDIO_LOAD_TIMEOUT_MS,
+        });
+        if (!r.ok) {
+            const body = await r.text().catch(() => "");
+            onProgress(`LM Studio rejected load: HTTP ${r.status} ${body.slice(0, 200)}`);
+            return false;
+        }
+        return true;
+    }
+    catch (e) {
+        onProgress(`load timed out / failed: ${e.message}`);
+        return false;
+    }
+    finally {
+        clearInterval(tick);
+    }
+}
+export async function preflightLmStudio(modelName, onProgress = () => { }) {
+    const models = await listLmStudioModels();
+    if (models === null) {
+        return {
+            ok: false,
+            reason: "lmstudio_unreachable",
+            hint: `Could not reach LM Studio at ${LMSTUDIO_BASE}. Start LM Studio and enable the local server (Developer tab → Start Server).`,
+        };
+    }
+    // Match by exact id first, then by suffix (LM Studio model ids include
+    // the publisher prefix; users sometimes type just the leaf name).
+    const exact = models.find((m) => m.id === modelName);
+    const suffix = exact ? null : models.find((m) => m.id.endsWith(`/${modelName}`) || m.id.endsWith(`:${modelName}`));
+    const match = exact ?? suffix;
+    if (!match) {
+        const available = models.map((m) => m.id).slice(0, 6).join(", ");
+        return {
+            ok: false,
+            reason: "model_not_downloaded",
+            hint: `Model "${modelName}" not found in LM Studio. Open LM Studio → Search → download it. Available: ${available || "(none)"}`,
+        };
+    }
+    const state = (match.state ?? "unknown");
+    if (state === "loaded") {
+        onProgress(`✓ ${match.id} already loaded in LM Studio`);
+        return { ok: true, loaded: true };
+    }
+    onProgress(`Loading ${match.id} into LM Studio (this can take 30-120s for first load)…`);
+    const loaded = await jitLoadLmStudioModel(match.id, onProgress);
+    if (!loaded) {
+        return {
+            ok: false,
+            reason: "load_failed",
+            hint: `LM Studio could not load "${match.id}". Check available RAM and the LM Studio server log.`,
+        };
+    }
+    onProgress(`✓ ${match.id} loaded`);
+    return { ok: true, loaded: true };
+}
+export async function preflightOllama(modelName, onProgress = () => { }) {
+    try {
+        const r = await fetchWithTimeout(`${OLLAMA_BASE}/api/tags`, { timeoutMs: 3_000 });
+        if (!r.ok) {
+            return {
+                ok: false,
+                reason: "ollama_unreachable",
+                hint: `Could not reach Ollama at ${OLLAMA_BASE}. Start the Ollama daemon.`,
+            };
+        }
+        const j = await r.json();
+        const tags = (j.models ?? []).map((m) => m.name);
+        if (!tags.includes(modelName)) {
+            return {
+                ok: false,
+                reason: "model_not_pulled",
+                hint: `Model "${modelName}" not pulled in Ollama. Run: ollama pull ${modelName}`,
+            };
+        }
+        onProgress(`✓ ${modelName} present in Ollama`);
+        return { ok: true, loaded: true };
+    }
+    catch (e) {
+        return { ok: false, reason: "ollama_error", hint: e.message };
+    }
+}
+/**
+ * Top-level preflight — resolves the provider/model from the pipeline
+ * config and dispatches to the right helper. Returns immediately for
+ * non-local providers (cloud-spawn shouldn't reach the runner anyway).
+ */
+export async function preflightModel(configJson, onProgress = (m) => console.log(chalk.gray(`  [model] ${m}`))) {
+    let cfg;
+    try {
+        cfg = JSON.parse(configJson);
+    }
+    catch {
+        return { ok: true }; /* let main.py error naturally */
+    }
+    // Pipeline-level + per-step / per-agent providers — match the same
+    // walk as builder_server.py:2716-2725 so we honour the agent that
+    // overrides the top-level pick.
+    const providers = new Set();
+    const models = new Set();
+    const top = String(cfg.model_provider ?? cfg.model?.provider ?? "").toLowerCase();
+    if (top)
+        providers.add(top);
+    const topModel = String(cfg.model_name ?? cfg.model?.name ?? "");
+    if (topModel)
+        models.add(topModel);
+    for (const step of (cfg.steps ?? [])) {
+        const a = step?.agent ?? {};
+        const p = String(a?.model?.provider ?? "").toLowerCase();
+        const n = String(a?.model?.name ?? "");
+        if (p)
+            providers.add(p);
+        if (n)
+            models.add(n);
+    }
+    for (const a of (cfg.agents ?? [])) {
+        const p = String(a?.model_provider ?? a?.model?.provider ?? "").toLowerCase();
+        const n = String(a?.model_name ?? a?.model?.name ?? "");
+        if (p)
+            providers.add(p);
+        if (n)
+            models.add(n);
+    }
+    // Run preflight for every distinct (provider, model) combo this
+    // pipeline will exercise. One bad agent = whole run fails fast.
+    const tasks = [];
+    for (const m of models) {
+        if (providers.has("lmstudio"))
+            tasks.push(preflightLmStudio(m, onProgress));
+        if (providers.has("ollama"))
+            tasks.push(preflightOllama(m, onProgress));
+    }
+    if (tasks.length === 0)
+        return { ok: true };
+    const results = await Promise.all(tasks);
+    const failed = results.find((r) => !r.ok);
+    return failed ?? { ok: true, loaded: true };
+}

package/dist/pythonEnv.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Manage a dedicated Python venv at ~/.melaya-runner/venv/ so pipelines
+ * don't depend on whatever's globally installed in the operator's
+ * `python3`. Without this, every fresh runner install hits import errors
+ * (`ModuleNotFoundError: No module named 'shortuuid'`, etc.) on the
+ * first pipeline run because agentscope and its 23 transitive deps are
+ * not present in the operator's system Python.
+ *
+ * Idempotent: re-uses the venv if a marker file matches the current
+ * shared-bundle version. Re-bootstraps when the bundle version changes.
+ */
+export declare function venvPython(): string;
+export declare function ensurePythonEnv(systemPython: string, expectedVersion: string, onProgress?: (msg: string) => void): Promise<{
+    ok: boolean;
+    pythonPath: string;
+    reason?: string;
+}>;

package/dist/pythonEnv.js

@@ -0,0 +1,112 @@
+/**
+ * Manage a dedicated Python venv at ~/.melaya-runner/venv/ so pipelines
+ * don't depend on whatever's globally installed in the operator's
+ * `python3`. Without this, every fresh runner install hits import errors
+ * (`ModuleNotFoundError: No module named 'shortuuid'`, etc.) on the
+ * first pipeline run because agentscope and its 23 transitive deps are
+ * not present in the operator's system Python.
+ *
+ * Idempotent: re-uses the venv if a marker file matches the current
+ * shared-bundle version. Re-bootstraps when the bundle version changes.
+ */
+import { spawn } from "child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import { homedir, platform } from "os";
+import chalk from "chalk";
+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");
+// Extra deps the cached `shared/tools/*.py` import that aren't in
+// agentscope's pyproject. Keep this list narrow — full tool-specific
+// SDKs (linkedin_api, twilio, stripe, etc.) install lazily on first
+// use via tool-specific scripts. The minimum to GET A PIPELINE RUNNING
+// is agentscope + aiohttp + requests + redis (used by some tools).
+const EXTRA_DEPS = ["aiohttp", "requests", "python-dotenv"];
+export function venvPython() {
+    return platform() === "win32"
+        ? join(VENV_DIR, "Scripts", "python.exe")
+        : join(VENV_DIR, "bin", "python");
+}
+function venvIsValid(expectedVersion) {
+    if (!existsSync(venvPython()))
+        return false;
+    if (!existsSync(VENV_MARK))
+        return false;
+    try {
+        const cached = readFileSync(VENV_MARK, "utf-8").trim();
+        return cached === expectedVersion;
+    }
+    catch {
+        return false;
+    }
+}
+function runProc(cmd, args, onLine) {
+    return new Promise((resolve) => {
+        const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+        const chew = (b) => {
+            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", (code) => resolve(code ?? 1));
+        child.on("error", () => resolve(1));
+    });
+}
+export async function ensurePythonEnv(systemPython, expectedVersion, onProgress = (m) => console.log(chalk.gray(`  [venv] ${m}`))) {
+    if (venvIsValid(expectedVersion)) {
+        return { ok: true, pythonPath: venvPython() };
+    }
+    if (!existsSync(AGENTSCOPE)) {
+        return {
+            ok: false,
+            pythonPath: systemPython,
+            reason: `agentscope cache missing at ${AGENTSCOPE} — restart the runner so the shared bundle downloads first.`,
+        };
+    }
+    mkdirSync(CACHE_DIR, { recursive: true });
+    // Step 1: create the venv if missing.
+    if (!existsSync(venvPython())) {
+        onProgress(`creating venv at ${VENV_DIR} (one-time, ~5s)`);
+        const code = await runProc(systemPython, ["-m", "venv", VENV_DIR], onProgress);
+        if (code !== 0 || !existsSync(venvPython())) {
+            return {
+                ok: false,
+                pythonPath: systemPython,
+                reason: `python -m venv failed (exit ${code}). Confirm the venv module is available: ${systemPython} -m venv --help`,
+            };
+        }
+    }
+    // Step 2: upgrade pip + wheel so wheel-based deps install cleanly.
+    onProgress("upgrading pip / wheel inside the venv");
+    await runProc(venvPython(), ["-m", "pip", "install", "--quiet", "--upgrade", "pip", "wheel"], onProgress);
+    // Step 3: install agentscope from the local cache (its pyproject pulls
+    // anthropic, openai, shortuuid, opentelemetry-*, etc.).
+    onProgress("installing agentscope + 23 transitive deps (anthropic, openai, opentelemetry, …) — first run can take 1-2 min");
+    const acode = await runProc(venvPython(), ["-m", "pip", "install", "--quiet", "-e", AGENTSCOPE, ...EXTRA_DEPS], onProgress);
+    if (acode !== 0) {
+        return {
+            ok: false,
+            pythonPath: systemPython,
+            reason: `pip install agentscope failed (exit ${acode}). Check the lines above for the actual pip error.`,
+        };
+    }
+    writeFileSync(VENV_MARK, expectedVersion, "utf-8");
+    // sanity: confirm shortuuid resolves now (it's the historic canary
+    // import that fails on a stale env).
+    const probe = await runProc(venvPython(), ["-c", "import shortuuid, agentscope, anthropic, openai"], onProgress);
+    if (probe !== 0) {
+        return {
+            ok: false,
+            pythonPath: systemPython,
+            reason: "venv created but agentscope import probe failed. Delete ~/.melaya-runner/venv and restart the runner.",
+        };
+    }
+    onProgress(`✓ venv ready (python=${venvPython()})`);
+    return { ok: true, pythonPath: venvPython() };
+}

package/package.json

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