@melaya/runner 1.1.44 → 1.1.46

package/dist/browserBridge.js

@@ -39,6 +39,8 @@ import { SessionManager, SessionError, spaceUserDataDir, } from "./sessionManage
 import { ensureEngine } from "./browserProvisioner.js";
 import { runSandboxedScript } from "./codeWorker.js";
 import { classifyControlEffect, writeGatedInMode } from "./publishGate.js";
+import { applyUploadResize, parseUploadResize, resolveDataUrlSource, resolveHandleSource, resolvePathSource, resolveUrlSource, UploadSourceError, } from "./uploadFetch.js";
+import { unlink } from "node:fs/promises";
 // A wall-clock around a CDP command. Playwright's CDPSession.send has NO default
 // timeout, so a wedged/busy renderer means the promise NEVER settles (not a
 // rejection - no catch fires) and the lease op-chain queues every later op
@@ -1772,14 +1774,136 @@ export async function startBrowserBridge(opts) {
                     };
                 }
                 case "upload_file": {
-                    // Honest refusal, not act_kind_unknown. The tool is advertised and
-                    // the schema validates the handle shape, but NOTHING anywhere
-                    // resolves an approved handle back to bytes — not this bridge, not
-                    // the server, not the extension. Saying "unknown kind" sent the model
-                    // hunting for a different spelling of a tool that cannot work yet.
-                    throw new BridgeError("effect_not_granted", "File upload is not available on this transport: an approved file handle cannot be resolved to " +
-                        "a file yet, on any transport. Ask the USER to attach the file themselves with " +
-                        "browser_ask_user, then continue once they confirm.");
+                    // Attach file(s) to a page <input type=file> via CDP
+                    // DOM.setFileInputFiles. Sources, in precedence order: a staged
+                    // handle ("fh_<hex>_<ext>", from the server's browserUploadMedia
+                    // staging flow), a public image URL (guarded direct download — the
+                    // runner IS the executing side), or a LOCAL-RUNNER-ONLY file path.
+                    // v1 is images only (png/jpg/webp/gif), 10MB, magic-byte verified.
+                    //
+                    // GATE FIRST, download after: selecting a file onto a site is a
+                    // commit-shaped write (same family as submit), so in safe autonomy
+                    // it stages the approval card BEFORE any bytes move. browser.py's
+                    // poll loop re-issues the same act; the approved re-issue is the one
+                    // that downloads and attaches.
+                    await enforcePublishGate(reg, page, kind, "", String(args.ref ?? "file input"), args.hitl_mode, "publish");
+                    const handle = String(args.handle ?? args.value ?? (Array.isArray(args.fileHandles) ? args.fileHandles[0] : "") ?? "").trim();
+                    const srcUrl = String(args.url ?? "").trim();
+                    const srcPath = String(args.path ?? "").trim();
+                    const srcData = String(args.data ?? "").trim();
+                    const attachmentId = String(args.attachment_id ?? "").trim();
+                    let file;
+                    try {
+                        if (attachmentId) {
+                            // Per-turn chat attachments resolve to fh_ handles on the SERVER
+                            // (assistant stream / ext-bridge). A runner-LAUNCHED browser is a
+                            // pipeline transport with no chat turn to hold them, so the id is
+                            // unresolvable here — name the sources that do work.
+                            throw new BridgeError("act_args_invalid", "attachment_id is not available on the runner-launched browser transport — pass the image as " +
+                                "a public `url`, a base64 `data` URL, or a runner-local `path` instead.");
+                        }
+                        if (handle)
+                            file = await resolveHandleSource(String(reg.spec.serverBase || ""), handle);
+                        else if (srcUrl)
+                            file = await resolveUrlSource(srcUrl);
+                        else if (srcData)
+                            file = await resolveDataUrlSource(srcData);
+                        else if (srcPath)
+                            file = await resolvePathSource(srcPath);
+                        else {
+                            throw new BridgeError("act_args_invalid", "upload_file needs a file source: `url` (public http(s) image URL, max 10MB), `data` (a base64 " +
+                                "data URL), a staged `handle` (fh_...), or — on this local runner only — `path` (an image file " +
+                                "on this machine).");
+                        }
+                    }
+                    catch (e) {
+                        if (e instanceof BridgeError)
+                            throw e;
+                        if (e instanceof UploadSourceError)
+                            throw new BridgeError("act_args_invalid", `upload_file: ${e.message}`);
+                        throw new BridgeError("unknown_outcome", `upload_file could not resolve the file source: ${e.message}`);
+                    }
+                    if (file.temp)
+                        reg.uploadTmpFiles.push(file.path);
+                    // Convert-before-attach (width/height/fit/format): a canvas job run
+                    // through the page's JS context — the runner has no image library,
+                    // but it HAS a browser. Pure computation; no DOM mutation.
+                    const resizeSpec = parseUploadResize(args);
+                    if (resizeSpec) {
+                        const cdpForResize = await getCdp(rec, page);
+                        try {
+                            file = await applyUploadResize(file, resizeSpec, async (expression) => {
+                                const r = await cdpRace(cdpForResize.send("Runtime.evaluate", {
+                                    expression, awaitPromise: true, returnByValue: true,
+                                }), "Runtime.evaluate", 60_000);
+                                if (r.exceptionDetails)
+                                    throw new Error(r.exceptionDetails.text || "page threw during the canvas conversion");
+                                return r.result?.value;
+                            });
+                        }
+                        catch (e) {
+                            if (e instanceof UploadSourceError)
+                                throw new BridgeError("act_args_invalid", `upload_file: ${e.message}`);
+                            throw new BridgeError("unknown_outcome", `upload_file could not convert the image: ${e.message}`);
+                        }
+                        if (file.temp)
+                            reg.uploadTmpFiles.push(file.path);
+                    }
+                    // Locate the REAL <input type=file>. The ref may point at the input
+                    // itself, at a styled upload button that HIDES the input, or be
+                    // absent entirely — the common case, since hidden inputs rarely get
+                    // a ref in the tree. Search order: self, descendant, label control,
+                    // the enclosing form's input, the page's first file input.
+                    const FIND_FROM_REF = "function(){ var el = this;" +
+                        " var isFile = function(n){ return n && n.tagName && n.tagName.toLowerCase()==='input' && (n.getAttribute('type')||'').toLowerCase()==='file'; };" +
+                        " if (isFile(el)) return el;" +
+                        " var q = el && el.querySelector ? el.querySelector('input[type=file]') : null; if (q) return q;" +
+                        " if (el && el.tagName && el.tagName.toLowerCase()==='label') {" +
+                        "   var c = el.control || (el.htmlFor ? document.getElementById(el.htmlFor) : null); if (isFile(c)) return c; }" +
+                        " var f = el && el.closest ? el.closest('form') : null;" +
+                        " var q2 = f ? f.querySelector('input[type=file]') : null; if (q2) return q2;" +
+                        " var all = document.querySelectorAll('input[type=file]'); return all.length ? all[0] : null; }";
+                    const FIND_ON_PAGE = "(function(){ var all = Array.prototype.slice.call(document.querySelectorAll('input[type=file]'));" +
+                        " if (!all.length) return null;" +
+                        " var vis = all.filter(function(i){ var r = i.getBoundingClientRect(); return r.width>0 && r.height>0; });" +
+                        " return vis[0] || all[0]; })()";
+                    const cdp = await getCdp(rec, page);
+                    let inputObjectId = null;
+                    if (args.ref) {
+                        const binding = sessions.resolveRef(lease, args.ref);
+                        const resolved = await cdpRace(cdp.send("DOM.resolveNode", { backendNodeId: binding.backendNodeId }), "DOM.resolveNode");
+                        const found = await cdpRace(cdp.send("Runtime.callFunctionOn", {
+                            objectId: resolved.object.objectId,
+                            functionDeclaration: FIND_FROM_REF,
+                        }), "Runtime.callFunctionOn");
+                        inputObjectId = found.result?.objectId && found.result.subtype !== "null" ? found.result.objectId : null;
+                    }
+                    else {
+                        const found = await cdpRace(cdp.send("Runtime.evaluate", {
+                            expression: FIND_ON_PAGE,
+                        }), "Runtime.evaluate");
+                        inputObjectId = found.result?.objectId && found.result.subtype !== "null" ? found.result.objectId : null;
+                    }
+                    if (!inputObjectId) {
+                        throw new BridgeError("act_args_invalid", "no <input type=file> found" + (args.ref ? ` at or near ref '${args.ref}'` : " on this page") + ". " +
+                            "Some uploaders only create the input after their Upload button is clicked — click it first, then " +
+                            "retry upload_file. If the page opens a NATIVE file-picker dialog instead, hand off with browser_ask_user.");
+                    }
+                    // Set the files, then fire the events a real selection fires — CDP's
+                    // DOM.setFileInputFiles changes .files WITHOUT dispatching them, and
+                    // every framework listens on input/change.
+                    await cdpRace(cdp.send("DOM.setFileInputFiles", { files: [file.path], objectId: inputObjectId }), "DOM.setFileInputFiles");
+                    await cdpRace(cdp.send("Runtime.callFunctionOn", {
+                        objectId: inputObjectId,
+                        functionDeclaration: "function(){ this.dispatchEvent(new Event('input',{bubbles:true})); this.dispatchEvent(new Event('change',{bubbles:true})); return this.files ? this.files.length : 0; }",
+                        returnByValue: true,
+                    }), "Runtime.callFunctionOn");
+                    return {
+                        uploaded: true,
+                        files: [file.name],
+                        bytes: file.bytes,
+                        note: "file attached to the input — the page's own submit/save control still commits it",
+                    };
                 }
                 default:
                     throw new BridgeError("act_kind_unknown", `unhandled kind '${kind}'`);
@@ -2423,6 +2547,7 @@ export async function startBrowserBridge(opts) {
             sessionInit: null,
             traces: [],
             externalAttach: false,
+            uploadTmpFiles: [],
         };
         byToken.set(token, reg);
         byRunId.set(spec.runId, reg);
@@ -2451,6 +2576,12 @@ export async function startBrowserBridge(opts) {
         for (const e of reg.enforcement.splice(0)) {
             await e.dispose().catch(() => { });
         }
+        // Delete any upload temp files this run staged. Deferred to teardown on
+        // purpose: the browser reads the file LAZILY when the page's form submits,
+        // which can be several agent turns after the upload_file act.
+        for (const p of reg.uploadTmpFiles.splice(0)) {
+            await unlink(p).catch(() => { });
+        }
         byRunId.delete(runId);
         byToken.delete(reg.token);
         activePageByRunId.delete(runId);

package/dist/connection.js

@@ -78,6 +78,27 @@ export async function connect(opts) {
         reconnectionAttempts: Infinity,
     });
     let relay = null;
+    // ── Disconnect diagnostics (transport-close root-cause) ──────────────
+    // A "transport close" disconnect can be a NETWORK blip OR the Node event loop
+    // being BLOCKED (e.g. relaying big browser screenshots/trees) long enough that
+    // Socket.IO can't service the connection. These need OPPOSITE fixes, so we
+    // sample event-loop lag continuously and print the recent PEAK on disconnect:
+    // a multi-second spike ⇒ event-loop block (in-process work); ~0 ⇒ network/proxy.
+    let connectedAt = 0;
+    let lastHeartbeatAt = 0;
+    let peakLagMs = 0;
+    {
+        let last = Date.now();
+        const TICK = 500;
+        const t = setInterval(() => {
+            const now = Date.now();
+            const lag = now - last - TICK; // how much longer than TICK the loop actually took
+            last = now;
+            if (lag > peakLagMs)
+                peakLagMs = lag;
+        }, TICK);
+        t.unref?.();
+    }
     // ── Melaya Browser bridge state (plan Sections 3/4) ──────────────────
     // The governed browser control bridge is started lazily on the first
     // browser run. Grant public keys arrive over the socket (server push)
@@ -209,6 +230,8 @@ export async function connect(opts) {
     };
     socket.on("connect", async () => {
         spinner.succeed(chalk.green("Connected to Melaya"));
+        connectedAt = Date.now();
+        peakLagMs = 0; // fresh window each connection so the disconnect line reflects THIS session
         // New socket lifetime → new generation. Grants minted for an earlier
         // generation are refused (plan Section 4). Any browser runs from the
         // previous connection are already torn down on the disconnect path.
@@ -269,7 +292,16 @@ export async function connect(opts) {
         }
     });
     socket.on("disconnect", (reason) => {
-        console.log(chalk.yellow(`\n  Disconnected: ${reason}`));
+        const upS = connectedAt ? Math.round((Date.now() - connectedAt) / 1000) : 0;
+        const hbS = lastHeartbeatAt ? Math.round((Date.now() - lastHeartbeatAt) / 1000) : -1;
+        console.log(chalk.yellow(`\n  Disconnected: ${reason} (up ${upS}s, last heartbeat ${hbS}s ago, peak event-loop lag ${peakLagMs}ms)`));
+        // The discriminator: a big peak lag (or a stale heartbeat) means the Node
+        // event loop was BLOCKED while connected — heavy in-process work (big browser
+        // screenshot/tree relay), NOT a network drop → fix is to offload/chunk that
+        // work. A small lag with "transport close" points at the network/proxy path.
+        if (peakLagMs > 2000 || hbS > 45) {
+            console.log(chalk.yellow(`  ↳ event loop was blocked ~${peakLagMs}ms (heartbeat ${hbS}s ago) — this is in-process backpressure (likely big browser payload relay), not a network drop.`));
+        }
         // Melaya Browser: a dropped socket invalidates every browser grant
         // bound to this socket generation. Tear down ALL browser runs
         // (cancels in-flight ops, releases leases, closes owned browsers);
@@ -430,8 +462,10 @@ export async function connect(opts) {
     });
     // ── Heartbeat ──────────────────────────────────────────────────────
     setInterval(() => {
-        if (socket.connected)
+        if (socket.connected) {
             socket.emit("runner:heartbeat");
+            lastHeartbeatAt = Date.now();
+        }
     }, HEARTBEAT_INTERVAL);
     // ── Run command ────────────────────────────────────────────────────
     socket.on("runner:run", async (payload) => {

package/dist/uploadFetch.d.ts

@@ -0,0 +1,39 @@
+export declare const UPLOAD_MAX_BYTES: number;
+export interface ResolvedUploadFile {
+    /** Absolute path of the temp (or caller-supplied local) file. */
+    path: string;
+    /** Basename to report back ("logo.png" style). */
+    name: string;
+    bytes: number;
+    /** True when `path` is a temp file this module created (caller cleans up). */
+    temp: boolean;
+}
+export declare class UploadSourceError extends Error {
+}
+export interface UploadResize {
+    width?: number;
+    height?: number;
+    fit?: "contain" | "cover";
+    format?: "png" | "jpeg" | "webp";
+}
+/** Loose act args (flat width/height/fit/format from browser.py, or a strict
+ *  `resize` object) → a normalized UploadResize, or null when none asked. */
+export declare function parseUploadResize(args: Record<string, unknown>): UploadResize | null;
+/** Apply a resize/convert to a resolved file by running a canvas job through
+ *  the supplied JS evaluator (an async-IIFE expression whose awaited value is
+ *  the transformed image as base64). Returns a NEW temp file; throws
+ *  UploadSourceError with an actionable message when the page cannot do it. */
+export declare function applyUploadResize(file: ResolvedUploadFile, resize: UploadResize, evaluate: (expression: string) => Promise<unknown>): Promise<ResolvedUploadFile>;
+/** Staged-handle source: fetch <serverBase>/browser-media/<hex>.<ext>. */
+export declare function resolveHandleSource(serverBase: string, handle: string): Promise<ResolvedUploadFile>;
+/** URL source: guarded direct download from the runner machine. */
+export declare function resolveUrlSource(url: string): Promise<ResolvedUploadFile>;
+/** Base64 data-URL source: decoded locally (no network). Same image-only
+ *  allowlist, sniff and cap. NOTE the local bridge's request body cap bounds
+ *  how much base64 can arrive this way; large files should come as a staged
+ *  handle or a url. */
+export declare function resolveDataUrlSource(dataUrl: string): Promise<ResolvedUploadFile>;
+/** Local-path source (LOCAL RUNNER ONLY): an image file already on this
+ *  machine. Image-gated by magic bytes, so this cannot be used to lift an
+ *  arbitrary local file (keys, configs, code) onto a website. */
+export declare function resolvePathSource(path: string): Promise<ResolvedUploadFile>;

package/dist/uploadFetch.js

@@ -0,0 +1,393 @@
+// File-source resolution for the runner bridge's `upload_file` act.
+//
+// The runner machine is the EXECUTING side, so it is the one that turns a file
+// source into real bytes on disk before CDP's DOM.setFileInputFiles can attach
+// them to a page's <input type=file>. Three sources:
+//
+//   handle "fh_<hex>_<ext>"  — minted by the server's staging flow
+//                              (services/browser/browserUploadMedia.ts);
+//                              fetched from GET <serverBase>/browser-media/
+//                              <hex>.<ext> (public capability URL, short TTL).
+//   url (http/https)         — downloaded directly by the runner. The URL was
+//                              chosen by a model, and this code runs on the
+//                              USER'S machine, so private/loopback/link-local
+//                              addresses are blocked (a mirror of the server's
+//                              safeFetch guard, self-contained here): the
+//                              user's LAN must not be reachable through it.
+//   path (local file)        — LOCAL-RUNNER-ONLY convenience for pipeline
+//                              artifacts already on this machine. Never
+//                              reachable from the cloud action schema (it has
+//                              no path field); the loose local-bridge contract
+//                              is the only door, and it is image-gated below.
+//
+// v1 is IMAGES ONLY (png/jpg/webp/gif), 10MB cap, magic-byte verified — the
+// same allowlist the server's stager enforces, re-checked here because this
+// path can bypass the server entirely (direct url / local path).
+import { lookup as dnsLookup } from "node:dns";
+import * as http from "node:http";
+import * as https from "node:https";
+import { randomBytes } from "node:crypto";
+import { writeFile, readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+export const UPLOAD_MAX_BYTES = 10 * 1024 * 1024;
+const CT_BY_EXT = {
+    png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", webp: "image/webp",
+    gif: "image/gif",
+};
+export class UploadSourceError extends Error {
+}
+function extForContentType(ct) {
+    const base = (ct || "").split(";")[0].trim().toLowerCase();
+    switch (base) {
+        case "image/png": return "png";
+        case "image/jpeg":
+        case "image/jpg": return "jpg";
+        case "image/webp": return "webp";
+        case "image/gif": return "gif";
+        default: return null;
+    }
+}
+function extOfName(name) {
+    const m = /\.([a-z0-9]{2,4})(?:[?#]|$)/i.exec(name || "");
+    const ext = m ? m[1].toLowerCase() : "";
+    return ext in CT_BY_EXT ? ext : null;
+}
+function imageSniffOk(buf, ext) {
+    if (buf.length < 12)
+        return false;
+    if (ext === "png")
+        return buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47;
+    if (ext === "jpg" || ext === "jpeg")
+        return buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff;
+    if (ext === "webp")
+        return buf.toString("ascii", 0, 4) === "RIFF" && buf.toString("ascii", 8, 12) === "WEBP";
+    if (ext === "gif")
+        return buf.toString("ascii", 0, 3) === "GIF";
+    return false;
+}
+// ── Private-address guard (mirror of server safeFetch's block ranges) ────────
+function ipv4ToInt(ip) {
+    const m = ip.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (!m)
+        return null;
+    const o = m.slice(1).map(Number);
+    if (o.some((x) => x > 255))
+        return null;
+    return (((o[0] << 24) >>> 0) + (o[1] << 16) + (o[2] << 8) + o[3]) >>> 0;
+}
+function isBlockedV4(ip) {
+    const n = ipv4ToInt(ip);
+    if (n === null)
+        return true; // unparseable -> block (fail closed)
+    const inRange = (base, bits) => {
+        const b = ipv4ToInt(base);
+        if (b === null)
+            return false;
+        const mask = bits === 0 ? 0 : (~0 << (32 - bits)) >>> 0;
+        return (n & mask) === (b & mask);
+    };
+    return inRange("0.0.0.0", 8) || inRange("10.0.0.0", 8) || inRange("100.64.0.0", 10) ||
+        inRange("127.0.0.0", 8) || inRange("169.254.0.0", 16) || inRange("172.16.0.0", 12) ||
+        inRange("192.0.0.0", 24) || inRange("192.168.0.0", 16) || inRange("198.18.0.0", 15) ||
+        inRange("224.0.0.0", 4) || inRange("240.0.0.0", 4);
+}
+function parseV6(addr) {
+    let a = addr.trim().toLowerCase().replace(/^\[|\]$/g, "").replace(/%.*$/, "");
+    if (!a.includes(":"))
+        return null;
+    const dotted = a.match(/(.*:)(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+    if (dotted) {
+        const v4 = ipv4ToInt(dotted[2]);
+        if (v4 === null)
+            return null;
+        a = dotted[1] + (((v4 >>> 16) & 0xffff).toString(16)) + ":" + ((v4 & 0xffff).toString(16));
+    }
+    const halves = a.split("::");
+    if (halves.length > 2)
+        return null;
+    const head = halves[0] ? halves[0].split(":") : [];
+    const tail = halves.length === 2 ? (halves[1] ? halves[1].split(":") : []) : null;
+    const toWords = (parts) => {
+        const out = [];
+        for (const p of parts) {
+            if (!/^[0-9a-f]{1,4}$/.test(p))
+                return null;
+            out.push(parseInt(p, 16));
+        }
+        return out;
+    };
+    const h = toWords(head);
+    if (h === null)
+        return null;
+    if (tail === null)
+        return h.length === 8 ? h : null;
+    const t = toWords(tail);
+    if (t === null)
+        return null;
+    const fill = 8 - h.length - t.length;
+    if (fill < 0)
+        return null;
+    return [...h, ...Array(fill).fill(0), ...t];
+}
+function isBlockedIp(addr) {
+    const a = addr.trim().toLowerCase().replace(/^\[|\]$/g, "").replace(/%.*$/, "");
+    if (!a.includes(":"))
+        return isBlockedV4(a);
+    const w = parseV6(a);
+    if (w === null)
+        return true;
+    if (w[0] === 0 && w[1] === 0 && w[2] === 0 && w[3] === 0 && w[4] === 0 && w[5] === 0xffff) {
+        const v4 = `${(w[6] >> 8) & 0xff}.${w[6] & 0xff}.${(w[7] >> 8) & 0xff}.${w[7] & 0xff}`;
+        return isBlockedV4(v4);
+    }
+    return (w[0] & 0xe000) !== 0x2000; // only global unicast 2000::/3
+}
+/** Validating + pinning lookup: the socket connects to exactly the vetted
+ *  address, so there is no DNS-rebinding TOCTOU window. */
+function validatingLookup(hostname, options, callback) {
+    const all = !!(options && typeof options === "object" && options.all);
+    dnsLookup(hostname, { all: true, verbatim: true }, (err, addresses) => {
+        if (err || !addresses || (Array.isArray(addresses) && addresses.length === 0)) {
+            callback(Object.assign(new Error("upload_url_unresolvable"), { code: "ENOTFOUND" }), "");
+            return;
+        }
+        const recs = addresses;
+        for (const r of recs) {
+            if (isBlockedIp(r.address)) {
+                callback(Object.assign(new Error("upload_url_blocked_ip"), { code: "EACCES" }), "");
+                return;
+            }
+        }
+        if (all)
+            callback(null, recs);
+        else
+            callback(null, recs[0].address, recs[0].family);
+    });
+}
+/** One guarded GET, following up to 5 redirects (each hop re-validated). */
+async function guardedGet(urlStr, opts) {
+    let current = urlStr;
+    for (let hop = 0; hop <= 5; hop++) {
+        let u;
+        try {
+            u = new URL(current);
+        }
+        catch {
+            throw new UploadSourceError(`invalid URL: ${current}`);
+        }
+        if (u.protocol !== "http:" && u.protocol !== "https:")
+            throw new UploadSourceError(`unsupported scheme '${u.protocol}' — only http(s) URLs can be uploaded`);
+        if (opts.guardPrivate && u.port && u.port !== "80" && u.port !== "443")
+            throw new UploadSourceError("non-standard ports are blocked for upload URLs");
+        if (opts.guardPrivate) {
+            const bare = u.hostname.replace(/^\[|\]$/g, "");
+            if ((ipv4ToInt(bare) !== null || bare.includes(":")) && isBlockedIp(bare)) {
+                throw new UploadSourceError("that URL points at a private/loopback address, which is blocked");
+            }
+        }
+        const r = await new Promise((resolve, reject) => {
+            const mod = u.protocol === "https:" ? https : http;
+            const req = mod.request(u, {
+                method: "GET",
+                ...(opts.guardPrivate ? { lookup: validatingLookup } : {}),
+                headers: { Accept: "image/*,*/*;q=0.5", "User-Agent": "MelayaRunner/1.0 (browser_upload)" },
+            }, (res) => {
+                const status = res.statusCode || 0;
+                const contentType = String(res.headers["content-type"] || "");
+                if (status >= 300 && status < 400 && res.headers.location) {
+                    res.resume();
+                    resolve({ status, contentType, location: String(res.headers.location), body: Buffer.alloc(0) });
+                    return;
+                }
+                const chunks = [];
+                let received = 0;
+                res.on("data", (c) => {
+                    received += c.length;
+                    if (received > opts.maxBytes) {
+                        req.destroy();
+                        reject(new UploadSourceError(`the file exceeds the ${Math.round(opts.maxBytes / 1024 / 1024)}MB upload cap`));
+                        return;
+                    }
+                    chunks.push(c);
+                });
+                res.on("end", () => resolve({ status, contentType, body: Buffer.concat(chunks) }));
+                res.on("error", (e) => reject(e));
+            });
+            req.on("error", (e) => reject(e));
+            req.setTimeout(opts.timeoutMs, () => { req.destroy(); reject(new UploadSourceError("timed out downloading the file")); });
+            req.end();
+        });
+        if (r.status >= 300 && r.status < 400 && r.location) {
+            current = new URL(r.location, current).toString();
+            continue;
+        }
+        if (r.status < 200 || r.status >= 300)
+            throw new UploadSourceError(`download failed with HTTP ${r.status}`);
+        return { body: r.body, contentType: r.contentType, finalUrl: current };
+    }
+    throw new UploadSourceError("too many redirects");
+}
+function validateImage(buf, extHint, label) {
+    if (!buf.length)
+        throw new UploadSourceError(`${label} is empty`);
+    if (buf.length > UPLOAD_MAX_BYTES)
+        throw new UploadSourceError(`${label} exceeds the ${Math.round(UPLOAD_MAX_BYTES / 1024 / 1024)}MB upload cap`);
+    // Sniff first, trust headers/extensions second: the bytes are the authority.
+    for (const ext of extHint ? [extHint] : []) {
+        if (imageSniffOk(buf, ext))
+            return ext;
+    }
+    for (const ext of Object.keys(CT_BY_EXT)) {
+        if (imageSniffOk(buf, ext))
+            return ext;
+    }
+    throw new UploadSourceError(`${label} is not a supported image — v1 uploads accept png, jpg, webp or gif only`);
+}
+async function toTemp(buf, ext) {
+    const name = `melaya-upload-${randomBytes(6).toString("hex")}.${ext}`;
+    const p = join(tmpdir(), name);
+    await writeFile(p, buf, { mode: 0o600 });
+    return { path: p, name: `upload.${ext}`, bytes: buf.length, temp: true };
+}
+/** Loose act args (flat width/height/fit/format from browser.py, or a strict
+ *  `resize` object) → a normalized UploadResize, or null when none asked. */
+export function parseUploadResize(args) {
+    const src = (args.resize && typeof args.resize === "object" ? args.resize : args);
+    const w = Math.trunc(Number(src.width));
+    const h = Math.trunc(Number(src.height));
+    const fit = String(src.fit ?? "").trim().toLowerCase();
+    const format = String(src.format ?? "").trim().toLowerCase().replace(/^jpg$/, "jpeg");
+    const out = {
+        ...(Number.isFinite(w) && w >= 1 && w <= 10_000 ? { width: w } : {}),
+        ...(Number.isFinite(h) && h >= 1 && h <= 10_000 ? { height: h } : {}),
+        ...(fit === "contain" || fit === "cover" ? { fit: fit } : {}),
+        ...(format === "png" || format === "jpeg" || format === "webp" ? { format: format } : {}),
+    };
+    return out.width || out.height || out.format ? out : null;
+}
+const MIME_BY_EXT = {
+    png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", webp: "image/webp", gif: "image/gif",
+};
+/** Apply a resize/convert to a resolved file by running a canvas job through
+ *  the supplied JS evaluator (an async-IIFE expression whose awaited value is
+ *  the transformed image as base64). Returns a NEW temp file; throws
+ *  UploadSourceError with an actionable message when the page cannot do it. */
+export async function applyUploadResize(file, resize, evaluate) {
+    const srcExt = (file.path.split(".").pop() || "png").toLowerCase();
+    const srcMime = MIME_BY_EXT[srcExt] || "image/png";
+    const outExt = resize.format === "jpeg" ? "jpg" : (resize.format || (srcExt === "gif" ? "png" : srcExt));
+    const outMime = MIME_BY_EXT[outExt] || srcMime;
+    const raw = await readFile(file.path);
+    const w = resize.width || 0;
+    const h = resize.height || 0;
+    const fit = resize.fit === "cover" ? "cover" : "contain";
+    // Everything interpolated below is numeric or JSON-quoted — nothing from a
+    // page, nothing free-form; the base64 alphabet cannot break the string out.
+    const expression = `(async function(){
+    var bin = atob(${JSON.stringify(raw.toString("base64"))});
+    var bytes = new Uint8Array(bin.length);
+    for (var i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+    var bmp = await createImageBitmap(new Blob([bytes], { type: ${JSON.stringify(srcMime)} }));
+    var sw = bmp.width, sh = bmp.height;
+    var w = ${w}, h = ${h};
+    var W, H, dx, dy, dw, dh;
+    if (w && h) {
+      W = w; H = h;
+      var s = ${JSON.stringify(fit)} === "cover" ? Math.max(w / sw, h / sh) : Math.min(w / sw, h / sh);
+      dw = sw * s; dh = sh * s; dx = (W - dw) / 2; dy = (H - dh) / 2;
+    } else if (w) { W = w; H = Math.max(1, Math.round(sh * w / sw)); dx = 0; dy = 0; dw = W; dh = H; }
+    else if (h) { H = h; W = Math.max(1, Math.round(sw * h / sh)); dx = 0; dy = 0; dw = W; dh = H; }
+    else { W = sw; H = sh; dx = 0; dy = 0; dw = sw; dh = sh; }
+    var canvas = new OffscreenCanvas(W, H);
+    var g = canvas.getContext("2d");
+    if (${JSON.stringify(outMime)} === "image/jpeg") { g.fillStyle = "#fff"; g.fillRect(0, 0, W, H); }
+    g.imageSmoothingQuality = "high";
+    g.drawImage(bmp, dx, dy, dw, dh);
+    var blob = await canvas.convertToBlob({ type: ${JSON.stringify(outMime)}, quality: 0.92 });
+    var out = new Uint8Array(await blob.arrayBuffer());
+    var s2 = ""; var CH = 32768;
+    for (var j = 0; j < out.length; j += CH) s2 += String.fromCharCode.apply(null, Array.prototype.slice.call(out.subarray(j, j + CH)));
+    return btoa(s2);
+  })()`;
+    let outB64;
+    try {
+        outB64 = await evaluate(expression);
+    }
+    catch (e) {
+        throw new UploadSourceError(`could not convert the image in the browser (${e.message}). ` +
+            "Retry without width/height/format, or convert the file before uploading.");
+    }
+    if (typeof outB64 !== "string" || !outB64) {
+        throw new UploadSourceError("the in-browser image conversion returned nothing — retry without width/height/format, or convert the file before uploading.");
+    }
+    const buf = Buffer.from(outB64, "base64");
+    if (!buf.length)
+        throw new UploadSourceError("the in-browser image conversion produced an empty file.");
+    if (buf.length > UPLOAD_MAX_BYTES)
+        throw new UploadSourceError(`the converted image exceeds the ${Math.round(UPLOAD_MAX_BYTES / 1024 / 1024)}MB upload cap.`);
+    return toTemp(buf, outExt);
+}
+/** Staged-handle source: fetch <serverBase>/browser-media/<hex>.<ext>. */
+export async function resolveHandleSource(serverBase, handle) {
+    const m = /^fh_([a-f0-9]{32})_([a-z0-9]{2,4})$/.exec((handle || "").trim());
+    if (!m || !(m[2].toLowerCase() in CT_BY_EXT)) {
+        throw new UploadSourceError(`'${String(handle).slice(0, 60)}' is not a staged file handle (expected "fh_<hex>_<ext>"). ` +
+            "Use browser_upload with a public image `url` — it stages the file and mints the handle for you.");
+    }
+    const base = (serverBase || "").replace(/\/+$/, "");
+    if (!base)
+        throw new UploadSourceError("this run has no server base configured, so a staged handle cannot be resolved — pass a public image `url` instead");
+    const { body } = await guardedGet(`${base}/browser-media/${m[1]}.${m[2].toLowerCase()}`, {
+        maxBytes: UPLOAD_MAX_BYTES, timeoutMs: 30_000, guardPrivate: false, // the user's own server base may be private in dev
+    });
+    const ext = validateImage(body, m[2].toLowerCase(), "the staged file");
+    return toTemp(body, ext);
+}
+/** URL source: guarded direct download from the runner machine. */
+export async function resolveUrlSource(url) {
+    const { body, contentType, finalUrl } = await guardedGet(url, {
+        maxBytes: UPLOAD_MAX_BYTES, timeoutMs: 30_000, guardPrivate: true,
+    });
+    const hint = extForContentType(contentType) ?? extOfName(new URL(finalUrl).pathname);
+    const ext = validateImage(body, hint, `the file at ${url}`);
+    return toTemp(body, ext);
+}
+/** Base64 data-URL source: decoded locally (no network). Same image-only
+ *  allowlist, sniff and cap. NOTE the local bridge's request body cap bounds
+ *  how much base64 can arrive this way; large files should come as a staged
+ *  handle or a url. */
+export async function resolveDataUrlSource(dataUrl) {
+    const m = /^data:([a-z0-9.+/-]+)(?:;[a-z0-9=.-]+)*;base64,([A-Za-z0-9+/=\s]+)$/i.exec((dataUrl || "").trim());
+    if (!m)
+        throw new UploadSourceError('expected a base64 data URL like "data:image/png;base64,..."');
+    const b64 = m[2].replace(/\s+/g, "");
+    if (b64.length > Math.ceil((UPLOAD_MAX_BYTES * 4) / 3) + 8) {
+        throw new UploadSourceError(`the file exceeds the ${Math.round(UPLOAD_MAX_BYTES / 1024 / 1024)}MB upload cap`);
+    }
+    const buf = Buffer.from(b64, "base64");
+    const ext = validateImage(buf, extForContentType(m[1]), "the data URL payload");
+    return toTemp(buf, ext);
+}
+/** Local-path source (LOCAL RUNNER ONLY): an image file already on this
+ *  machine. Image-gated by magic bytes, so this cannot be used to lift an
+ *  arbitrary local file (keys, configs, code) onto a website. */
+export async function resolvePathSource(path) {
+    const p = (path || "").trim();
+    if (!p)
+        throw new UploadSourceError("empty path");
+    let size;
+    try {
+        size = (await stat(p)).size;
+    }
+    catch {
+        throw new UploadSourceError(`no file at '${p}' on the runner machine`);
+    }
+    if (size > UPLOAD_MAX_BYTES)
+        throw new UploadSourceError(`the file exceeds the ${Math.round(UPLOAD_MAX_BYTES / 1024 / 1024)}MB upload cap`);
+    const buf = await readFile(p);
+    const ext = validateImage(buf, extOfName(p), `the file at ${p}`);
+    // The file already exists locally with the right bytes — attach it in place
+    // (no temp copy) so nothing else has to be cleaned up.
+    return { path: p, name: `upload.${ext}`, bytes: buf.length, temp: false };
+}

package/package.json

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