@melaya/runner 1.0.22 → 1.0.25

package/dist/connection.js

@@ -19,6 +19,7 @@ import { join } from "path";
 import { tmpdir } from "os";
 import { startLocalRelay, setActiveProject } from "./localRelay.js";
 import { ensureSharedModules, getSharedDir } from "./sharedVendor.js";
+import { startLumaBrowserBridge } from "./lumaBrowserBridge.js";
 const HEARTBEAT_INTERVAL = 30_000;
 const activeProcesses = new Map();
 export async function connect(opts) {
@@ -36,6 +37,25 @@ export async function connect(opts) {
         reconnectionAttempts: Infinity,
     });
     let relay = null;
+    // Luma browser bridge — only started after a successful Luma sign-in
+    // (storage state file exists). Reset to a fresh bridge after each
+    // luma:login-result so cookie rotation is picked up immediately.
+    let lumaBridge = null;
+    const _ensureLumaBridge = async () => {
+        if (lumaBridge)
+            return;
+        try {
+            lumaBridge = await startLumaBrowserBridge({
+                log: (m) => {
+                    if (opts.verbose)
+                        console.log(chalk.gray(`  [luma-bridge] ${m}`));
+                },
+            });
+        }
+        catch (e) {
+            console.log(chalk.yellow(`  ⚠ Luma browser bridge failed to start: ${e?.message || e}`));
+        }
+    };
     socket.on("connect", async () => {
         spinner.succeed(chalk.green("Connected to Melaya"));
         // Report detected models
@@ -47,6 +67,10 @@ export async function connect(opts) {
                 console.log(chalk.gray(`  [relay] Listening on 127.0.0.1:${relay.port} (nonce: ${relay.nonce})`));
             }
         }
+        // Start the Luma browser bridge if a saved session exists. Best-
+        // effort — failure here means Luma POSTs fall back to aiohttp
+        // (which 403s under the bot rule) but reads still work.
+        await _ensureLumaBridge();
         console.log(chalk.gray("  Waiting for pipeline runs...\n"));
     });
     socket.on("connect_error", (err) => {
@@ -92,6 +116,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();
@@ -112,6 +188,16 @@ export async function connect(opts) {
                 OLLAMA_BASE_URL: "http://127.0.0.1:11434",
                 // Inject per-pipeline credentials (already scoped by the server)
                 ...payload.credentials,
+                // If a Luma browser bridge is up (i.e. the user has signed in
+                // via this runner), inject its localhost URL + bearer token so
+                // shared/tools/luma.py routes /event/register through Playwright
+                // and bypasses Cloudflare's bot rule. Reads keep using aiohttp.
+                ...(lumaBridge
+                    ? {
+                        MEL_LUMA_BROWSER_URL: lumaBridge.url,
+                        MEL_LUMA_BROWSER_TOKEN: lumaBridge.token,
+                    }
+                    : {}),
             };
             // Spawn Python subprocess
             const proc = spawn(opts.pythonPath, ["-u", join(runDir, "main.py")], {
@@ -120,19 +206,60 @@ export async function connect(opts) {
                 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,
@@ -207,6 +334,20 @@ export async function connect(opts) {
             const outcome = await runLumaLoginFlow(emitProgress);
             console.log(describeOutcome(outcome));
             socket.emit("luma:login-result", { session_id: sid, ...outcome });
+            // Successful sign-in just wrote a fresh storage-state.json. If the
+            // bridge is already up, force the next forward to re-read state
+            // from disk; if it isn't up (first sign-in on this runner), boot
+            // it now so the very next pipeline run has Cloudflare bypass.
+            if (outcome.ok) {
+                if (lumaBridge) {
+                    lumaBridge.invalidateState();
+                    if (opts.verbose)
+                        console.log(chalk.gray("  [luma-bridge] storage state invalidated; next call will re-read."));
+                }
+                else {
+                    await _ensureLumaBridge();
+                }
+            }
         }
         catch (e) {
             const msg = e?.message || "luma_login_unhandled_error";
@@ -240,6 +381,12 @@ export async function connect(opts) {
             socket.emit("runner:runComplete", { runId: id, status: "failed" });
         }
         relay?.close();
+        // Best-effort Chromium teardown. The bridge's shutdown is async but
+        // we can't await inside a SIGINT handler — fire and forget; the
+        // process.exit below kills any lingering child processes anyway.
+        if (lumaBridge) {
+            lumaBridge.shutdown().catch(() => { });
+        }
         socket.disconnect();
         process.exit(0);
     };

package/dist/lumaBrowserBridge.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Luma browser bridge — localhost HTTP server that tunnels HTTP requests
+ * through a Playwright Chromium context loaded from the user's saved
+ * Luma sign-in state.
+ *
+ * Why this exists
+ * ───────────────
+ *
+ * Cloudflare's bot rule on `POST /event/register` (and a handful of other
+ * write endpoints) is much stricter than on reads. It checks:
+ *   1. cf_clearance cookie issued by a managed challenge.
+ *   2. cf_bm cookie value freshly minted by JS executed on the page.
+ *   3. JA3/JA4 TLS fingerprint matching a real browser.
+ *   4. sec-ch-ua / sec-fetch-* header set matching same.
+ *
+ * Replaying cookies through aiohttp from Python misses #2-#4 and gets a
+ * 403 even with a valid session — see run cd0d03d05e684e0f. The reliable
+ * fix is to issue the request from inside the SAME Chromium context that
+ * captured the session: the JS runs, cookies refresh, headers and TLS
+ * fingerprint match, and the bot rule clears.
+ *
+ * How it works
+ * ────────────
+ *
+ * 1. At Luma sign-in, the Playwright `storageState` (full cookie jar +
+ *    localStorage + sessionStorage) is saved to `<runner-state-dir>/
+ *    luma-storage-state.json`. This is the source of truth for the
+ *    browser session — separate from the cookies persisted to the
+ *    server's DB (which feed the env-var path used by aiohttp reads).
+ * 2. At runner startup, if the storage-state file exists, this module
+ *    starts a small HTTP server bound to 127.0.0.1 on a random free
+ *    port, mints a per-session token, and exposes both via env vars
+ *    `MEL_LUMA_BROWSER_URL` + `MEL_LUMA_BROWSER_TOKEN` to the spawned
+ *    Python pipeline subprocess.
+ * 3. Python's `luma_register_event` POSTs the registration body to
+ *    `${MEL_LUMA_BROWSER_URL}/luma/forward` with
+ *    `Authorization: Bearer ${MEL_LUMA_BROWSER_TOKEN}`. The bridge:
+ *      a. Spawns / reuses a headless Chromium with the saved storage
+ *         state, freshly reloaded from disk so a recent reconnect's
+ *         cookies are picked up immediately.
+ *      b. Navigates to `https://luma.com/${eid}` so Cloudflare's JS
+ *         executes and refreshes cf_bm/cf_clearance.
+ *      c. Calls `fetch(url, init)` from inside `page.evaluate(...)`
+ *         so the request inherits the page's full browser context.
+ *      d. Returns `{ status, body }` to Python.
+ *
+ * Security
+ * ────────
+ *
+ * - Server binds to 127.0.0.1 only — never accessible off the host.
+ * - Random per-session token in the Authorization header — even other
+ *   processes on the same machine can't fire requests without it
+ *   (the env var is only injected into the runner-spawned pipeline
+ *   subprocess).
+ * - Endpoint is narrow: the URL must be a luma.com / api.luma.com /
+ *   api2.luma.com / lu.ma origin and the method must be GET / POST.
+ *   Anything else is rejected with 400.
+ * - Body size is capped at 64 KB.
+ *
+ * Cleanup
+ * ───────
+ *
+ * The browser is started lazily on the first request and torn down on
+ * runner exit. If the runner is killed mid-request, the next request
+ * relaunches.
+ */
+export interface LumaBrowserBridge {
+    url: string;
+    token: string;
+    shutdown: () => Promise<void>;
+    /** Called from connection.ts after a successful luma:login-result so
+     *  the next forward picks up the freshly-saved storage state. The
+     *  bridge always re-reads from disk, so this is purely a hint to
+     *  drop any reusable browser context (forces re-create on next call). */
+    invalidateState: () => void;
+}
+export declare function lumaStorageStatePath(): string;
+/**
+ * Starts the bridge if a saved Luma storage state exists. Returns null
+ * when no state is present so the runner stays in legacy aiohttp-only
+ * mode and Python's diagnostic path correctly reports
+ * `cf_cookies_present: []`.
+ */
+export declare function startLumaBrowserBridge(opts: {
+    log: (msg: string) => void;
+}): Promise<LumaBrowserBridge | null>;

package/dist/lumaBrowserBridge.js

@@ -0,0 +1,326 @@
+/**
+ * Luma browser bridge — localhost HTTP server that tunnels HTTP requests
+ * through a Playwright Chromium context loaded from the user's saved
+ * Luma sign-in state.
+ *
+ * Why this exists
+ * ───────────────
+ *
+ * Cloudflare's bot rule on `POST /event/register` (and a handful of other
+ * write endpoints) is much stricter than on reads. It checks:
+ *   1. cf_clearance cookie issued by a managed challenge.
+ *   2. cf_bm cookie value freshly minted by JS executed on the page.
+ *   3. JA3/JA4 TLS fingerprint matching a real browser.
+ *   4. sec-ch-ua / sec-fetch-* header set matching same.
+ *
+ * Replaying cookies through aiohttp from Python misses #2-#4 and gets a
+ * 403 even with a valid session — see run cd0d03d05e684e0f. The reliable
+ * fix is to issue the request from inside the SAME Chromium context that
+ * captured the session: the JS runs, cookies refresh, headers and TLS
+ * fingerprint match, and the bot rule clears.
+ *
+ * How it works
+ * ────────────
+ *
+ * 1. At Luma sign-in, the Playwright `storageState` (full cookie jar +
+ *    localStorage + sessionStorage) is saved to `<runner-state-dir>/
+ *    luma-storage-state.json`. This is the source of truth for the
+ *    browser session — separate from the cookies persisted to the
+ *    server's DB (which feed the env-var path used by aiohttp reads).
+ * 2. At runner startup, if the storage-state file exists, this module
+ *    starts a small HTTP server bound to 127.0.0.1 on a random free
+ *    port, mints a per-session token, and exposes both via env vars
+ *    `MEL_LUMA_BROWSER_URL` + `MEL_LUMA_BROWSER_TOKEN` to the spawned
+ *    Python pipeline subprocess.
+ * 3. Python's `luma_register_event` POSTs the registration body to
+ *    `${MEL_LUMA_BROWSER_URL}/luma/forward` with
+ *    `Authorization: Bearer ${MEL_LUMA_BROWSER_TOKEN}`. The bridge:
+ *      a. Spawns / reuses a headless Chromium with the saved storage
+ *         state, freshly reloaded from disk so a recent reconnect's
+ *         cookies are picked up immediately.
+ *      b. Navigates to `https://luma.com/${eid}` so Cloudflare's JS
+ *         executes and refreshes cf_bm/cf_clearance.
+ *      c. Calls `fetch(url, init)` from inside `page.evaluate(...)`
+ *         so the request inherits the page's full browser context.
+ *      d. Returns `{ status, body }` to Python.
+ *
+ * Security
+ * ────────
+ *
+ * - Server binds to 127.0.0.1 only — never accessible off the host.
+ * - Random per-session token in the Authorization header — even other
+ *   processes on the same machine can't fire requests without it
+ *   (the env var is only injected into the runner-spawned pipeline
+ *   subprocess).
+ * - Endpoint is narrow: the URL must be a luma.com / api.luma.com /
+ *   api2.luma.com / lu.ma origin and the method must be GET / POST.
+ *   Anything else is rejected with 400.
+ * - Body size is capped at 64 KB.
+ *
+ * Cleanup
+ * ───────
+ *
+ * The browser is started lazily on the first request and torn down on
+ * runner exit. If the runner is killed mid-request, the next request
+ * relaunches.
+ */
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import { promises as fs } from "node:fs";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+const ALLOWED_HOSTNAMES = new Set([
+    "luma.com",
+    "www.luma.com",
+    "lu.ma",
+    "api.luma.com",
+    "api2.luma.com",
+]);
+const MAX_BODY_BYTES = 64 * 1024;
+const PAGE_GOTO_TIMEOUT_MS = 20_000;
+const PAGE_SETTLE_MS = 1500;
+// ── State-file location ─────────────────────────────────────────────────────
+/** Resolves the same `melaya-runner` state dir the rest of the runner uses.
+ *  We can't share a constant because connection.ts doesn't expose its dir,
+ *  but the convention is well-defined: ~/.melaya/<sub> on every OS. */
+function _stateDir() {
+    return path.join(os.homedir(), ".melaya", "luma");
+}
+export function lumaStorageStatePath() {
+    return path.join(_stateDir(), "storage-state.json");
+}
+// ── Public starter ──────────────────────────────────────────────────────────
+/**
+ * Starts the bridge if a saved Luma storage state exists. Returns null
+ * when no state is present so the runner stays in legacy aiohttp-only
+ * mode and Python's diagnostic path correctly reports
+ * `cf_cookies_present: []`.
+ */
+export async function startLumaBrowserBridge(opts) {
+    const statePath = lumaStorageStatePath();
+    if (!existsSync(statePath)) {
+        opts.log("Luma browser bridge: no saved storage state, skipping.");
+        return null;
+    }
+    // Lazy-load Playwright. If the user installed @melaya/runner without
+    // chromium ever being needed (e.g. legacy local-model only), we don't
+    // want to crash on startup.
+    let playwright;
+    try {
+        playwright = await import("playwright");
+    }
+    catch {
+        opts.log("Luma browser bridge: playwright module unavailable, skipping.");
+        return null;
+    }
+    const token = randomBytes(24).toString("hex");
+    // Persistent browser handle. We launch on first request, not at boot,
+    // so the Chromium binary cost (~250 MB resident) is only paid by users
+    // who actually run a Luma pipeline. Subsequent requests reuse the
+    // browser; only the per-call context is fresh.
+    let browser = null;
+    let browserLaunching = null;
+    let stateMtime = 0;
+    async function _ensureBrowser() {
+        if (browser && browser.isConnected())
+            return browser;
+        if (browserLaunching)
+            return browserLaunching;
+        browserLaunching = (async () => {
+            const b = await playwright.chromium.launch({
+                headless: true,
+                args: [
+                    "--disable-blink-features=AutomationControlled",
+                    "--disable-dev-shm-usage",
+                ],
+            });
+            browser = b;
+            browserLaunching = null;
+            return b;
+        })();
+        return browserLaunching;
+    }
+    async function _readStorageState() {
+        const stat = await fs.stat(statePath);
+        stateMtime = stat.mtimeMs;
+        const txt = await fs.readFile(statePath, "utf-8");
+        return JSON.parse(txt);
+    }
+    async function _forward(req) {
+        let parsed;
+        try {
+            parsed = new URL(req.url);
+        }
+        catch {
+            return { ok: false, status: 0, body: "", error: "invalid_url" };
+        }
+        if (!ALLOWED_HOSTNAMES.has(parsed.hostname)) {
+            return { ok: false, status: 0, body: "", error: `host_not_allowed: ${parsed.hostname}` };
+        }
+        const method = (req.method || "POST").toUpperCase();
+        if (method !== "GET" && method !== "POST") {
+            return { ok: false, status: 0, body: "", error: `method_not_allowed: ${method}` };
+        }
+        const b = await _ensureBrowser();
+        let ctx = null;
+        try {
+            const storageState = await _readStorageState();
+            ctx = await b.newContext({
+                storageState: storageState,
+                userAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 " +
+                    "(KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36",
+                viewport: { width: 1280, height: 820 },
+            });
+            const page = await ctx.newPage();
+            const warmup = req.warmupUrl || `https://luma.com/`;
+            try {
+                await page.goto(warmup, {
+                    waitUntil: "domcontentloaded",
+                    timeout: req.navigationTimeoutMs || PAGE_GOTO_TIMEOUT_MS,
+                });
+            }
+            catch (e) {
+                // Don't fail the whole request — Cloudflare 403s during goto can
+                // happen for events that return 404 on the web shell but accept
+                // the API POST. Surface the error and keep going.
+                opts.log(`[luma-bridge] warmup goto failed (${e?.message || e}); proceeding to fetch.`);
+            }
+            // Settle: let the page's JS finish (Cloudflare token refresh, etc.)
+            await page.waitForTimeout(PAGE_SETTLE_MS);
+            // Fire the request from INSIDE the page so JA3 + headers + cookies
+            // are all browser-native. We pass init through page.evaluate so we
+            // don't have to maintain a parallel header set in this module.
+            const init = {
+                url: req.url,
+                method,
+                headers: req.headers,
+                body: typeof req.body === "string" ? req.body : (req.body ? JSON.stringify(req.body) : undefined),
+            };
+            const result = await page.evaluate(async (init) => {
+                const fetchInit = {
+                    method: init.method,
+                    headers: init.headers,
+                    credentials: "include",
+                };
+                if (init.body !== undefined)
+                    fetchInit.body = init.body;
+                const r = await fetch(init.url, fetchInit);
+                const text = await r.text();
+                return { status: r.status, body: text };
+            }, init);
+            return { ok: true, status: result.status, body: result.body };
+        }
+        catch (e) {
+            return { ok: false, status: 0, body: "", error: `bridge_error: ${e?.message || e}` };
+        }
+        finally {
+            if (ctx) {
+                try {
+                    await ctx.close();
+                }
+                catch { /* ignore */ }
+            }
+        }
+    }
+    // ── HTTP server ──────────────────────────────────────────────────────────
+    const server = createServer(async (req, res) => {
+        res.setHeader("X-Frame-Options", "DENY");
+        res.setHeader("Cache-Control", "no-store");
+        if (req.method !== "POST") {
+            res.statusCode = 405;
+            res.end(JSON.stringify({ ok: false, error: "method_not_allowed" }));
+            return;
+        }
+        // Auth — bearer token must match what we minted. Reject any request
+        // missing or mismatched. Drop in constant time isn't critical for
+        // local-only IPC but cheap to do anyway.
+        const auth = String(req.headers["authorization"] || "");
+        const expected = `Bearer ${token}`;
+        if (auth.length !== expected.length || auth !== expected) {
+            res.statusCode = 401;
+            res.end(JSON.stringify({ ok: false, error: "unauthorized" }));
+            return;
+        }
+        if (req.url !== "/luma/forward") {
+            res.statusCode = 404;
+            res.end(JSON.stringify({ ok: false, error: "not_found" }));
+            return;
+        }
+        // Read JSON body with a hard size cap.
+        const chunks = [];
+        let total = 0;
+        let oversized = false;
+        for await (const chunk of req) {
+            total += chunk.length;
+            if (total > MAX_BODY_BYTES) {
+                oversized = true;
+                break;
+            }
+            chunks.push(chunk);
+        }
+        if (oversized) {
+            res.statusCode = 413;
+            res.end(JSON.stringify({ ok: false, error: "payload_too_large" }));
+            return;
+        }
+        let payload;
+        try {
+            payload = JSON.parse(Buffer.concat(chunks).toString("utf-8"));
+        }
+        catch {
+            res.statusCode = 400;
+            res.end(JSON.stringify({ ok: false, error: "invalid_json" }));
+            return;
+        }
+        if (!payload || typeof payload !== "object" || !payload.url) {
+            res.statusCode = 400;
+            res.end(JSON.stringify({ ok: false, error: "missing_url" }));
+            return;
+        }
+        const out = await _forward(payload);
+        res.statusCode = 200;
+        res.setHeader("Content-Type", "application/json");
+        res.end(JSON.stringify(out));
+    });
+    // Bind to 127.0.0.1 with port 0 — OS picks a free port. Promise resolves
+    // after listen() so we can return the URL.
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => resolve());
+    });
+    const addr = server.address();
+    if (!addr || typeof addr === "string") {
+        server.close();
+        return null;
+    }
+    // Read the state mtime upfront so invalidateState() has a baseline.
+    try {
+        const stat = await fs.stat(statePath);
+        stateMtime = stat.mtimeMs;
+    }
+    catch { /* ignore */ }
+    opts.log(`Luma browser bridge ready on http://127.0.0.1:${addr.port} (storage state from ${new Date(stateMtime).toISOString()}).`);
+    return {
+        url: `http://127.0.0.1:${addr.port}`,
+        token,
+        shutdown: async () => {
+            try {
+                server.close();
+            }
+            catch { /* ignore */ }
+            if (browser) {
+                try {
+                    await browser.close();
+                }
+                catch { /* ignore */ }
+            }
+        },
+        invalidateState: () => {
+            // Force a fresh context on the next call. We don't tear down the
+            // browser itself — just the cached state mtime so the next read
+            // re-loads from disk.
+            stateMtime = 0;
+        },
+    };
+}

package/dist/lumaLogin.d.ts

@@ -27,6 +27,7 @@ export interface LumaLoginResult {
         auth_session_key: string;
         user_id?: string;
     };
+    extraCookies?: Record<string, string>;
     profileName?: string;
 }
 export interface LumaLoginError {

package/dist/lumaLogin.js

@@ -133,14 +133,39 @@ export async function runLumaLoginFlow(progress) {
         if (!succeeded) {
             return { ok: false, error: "login_timeout", detail: "5-minute sign-in window expired." };
         }
-        // Cookie names captured 2026-05-01 from luma.com after signin:
-        //   luma.auth-session-key  — required for every api2.luma.com call
-        //   luma.user-id           — informational, lets tools short-circuit /me
-        // Read both luma.com and api2.luma.com cookies — the session is shared
-        // across both subdomains via the registrable parent.
+        // Cookie names we replay on every api2.luma.com call:
+        //   luma.auth-session-key  — load-bearing session token (required)
+        //   luma.user-id           — informational; short-circuits /me lookups
+        //   cf_clearance           — Cloudflare bot-challenge clearance token.
+        //                            Issued only after a Turnstile / managed
+        //                            challenge passes. Reads work without it
+        //                            (served from CF edge cache); WRITES like
+        //                            POST /event/register fail with 403 when
+        //                            it's absent — see run cd0d03d05e684e0f.
+        //   __cf_bm                — Cloudflare bot-management cookie. Rotates
+        //                            every ~30min; not strictly required but
+        //                            having it reduces the false-positive rate
+        //                            on the bot heuristic.
+        //   _cfuvid                — Cloudflare unique-visitor id; same role.
+        // Cookies are scoped to luma.com / lu.ma / api.luma.com — Playwright's
+        // context.cookies() returns them all; we filter by name, not domain.
         const allCookies = await context.cookies();
         const auth_c = allCookies.find((c) => c.name === "luma.auth-session-key");
         const uid_c = allCookies.find((c) => c.name === "luma.user-id");
+        const CLOUDFLARE_COOKIE_NAMES = ["cf_clearance", "__cf_bm", "_cfuvid"];
+        const extraCookies = {};
+        for (const name of CLOUDFLARE_COOKIE_NAMES) {
+            // Pick the most-recently-set value (Playwright orders by insertion
+            // but a single name can have multiple entries across subdomains).
+            // The api2.luma.com one takes priority since that's the request
+            // target; fall back to luma.com if api isn't set yet.
+            const matches = allCookies.filter((c) => c.name === name);
+            const apiCookie = matches.find((c) => c.domain.includes("api.luma.com") || c.domain.includes("api2.luma.com"));
+            const webCookie = matches.find((c) => c.domain.endsWith("luma.com") || c.domain.endsWith("lu.ma"));
+            const picked = apiCookie?.value || webCookie?.value || matches[0]?.value;
+            if (picked)
+                extraCookies[name] = picked;
+        }
         if (!auth_c?.value) {
             return {
                 ok: false, error: "cookies_not_found",
@@ -161,12 +186,37 @@ export async function runLumaLoginFlow(progress) {
             });
         }
         catch { /* swallow */ }
-        progress(profileName ? `Captured session for ${profileName}.` : "Captured session.");
+        const cfNames = Object.keys(extraCookies);
+        const cfSummary = cfNames.length > 0 ? ` + ${cfNames.length} Cloudflare cookie${cfNames.length > 1 ? "s" : ""} (${cfNames.join(", ")})` : "";
+        // Persist the FULL Playwright storage state so the runner's browser
+        // bridge (lumaBrowserBridge.ts) can replay the same session for
+        // bot-rule-gated POSTs like /event/register. Cookies alone aren't
+        // enough — Cloudflare also fingerprints cf_bm freshness, JS
+        // execution, headers, and TLS — all of which the bridge gets for
+        // free by reusing this state inside a real Chromium context.
+        let bridgeStateNote = "";
+        try {
+            const path = await import("node:path");
+            const os = await import("node:os");
+            const fs = await import("node:fs/promises");
+            const stateDir = path.join(os.homedir(), ".melaya", "luma");
+            const statePath = path.join(stateDir, "storage-state.json");
+            await fs.mkdir(stateDir, { recursive: true });
+            // Playwright's storageState() returns cookies + localStorage +
+            // sessionStorage + indexedDB-flavored entries. We persist as-is.
+            await context.storageState({ path: statePath });
+            bridgeStateNote = " · browser session saved for bot-rule bypass";
+        }
+        catch (e) {
+            bridgeStateNote = ` · WARN: could not save browser session (${e?.message || e})`;
+        }
+        progress((profileName ? `Captured session for ${profileName}` : "Captured session") + cfSummary + bridgeStateNote + ".");
         await context.close();
         await browser.close();
         return {
             ok: true,
             cookies: { auth_session_key: auth_c.value, user_id: uid_c?.value },
+            extraCookies: Object.keys(extraCookies).length > 0 ? extraCookies : undefined,
             profileName,
         };
     }

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/package.json

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