forge-jsxy 1.0.66

package/dist/discordRelayUpload.js

@@ -0,0 +1,806 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatDiscordApiFailure = formatDiscordApiFailure;
+exports.discordRelayScreenshotEnabled = discordRelayScreenshotEnabled;
+exports.sanitizeDiscordClientChannelName = sanitizeDiscordClientChannelName;
+exports.clearDiscordChannelCache = clearDiscordChannelCache;
+exports.listGuildTextChannels = listGuildTextChannels;
+exports.createGuildTextChannel = createGuildTextChannel;
+exports.resolveScreenshotChannelId = resolveScreenshotChannelId;
+exports.postPngToDiscordChannel = postPngToDiscordChannel;
+exports.handleDiscordScreenshotUploadFromAgent = handleDiscordScreenshotUploadFromAgent;
+exports.handleDiscordUploadTicketRequest = handleDiscordUploadTicketRequest;
+exports.handleDiscordUploadAck = handleDiscordUploadAck;
+exports.warnDiscordRelayGuildIfMisconfigured = warnDiscordRelayGuildIfMisconfigured;
+/**
+ * Relay-only Discord screenshot delivery (Discord REST API v10).
+ *
+ * The **bot token never leaves the relay process**. Agents send PNG bytes as base64 in
+ * `discord_screenshot_upload` WebSocket messages; the relay creates or reuses a per-client text
+ * channel and posts the image with `Authorization: Bot …`.
+ *
+ * Rate-limit strategies (relay side)
+ * ────────────────────────────────────
+ * 1. Multiple bot tokens — `relayDiscordBotTokenForClient` assigns a stable bot per agent
+ *    `client_id` via FNV-1a hash so load spreads across tokens (separate rate-limit buckets).
+ * 2. Proactive bucket tracking — `discordJson` passes `routeKey` + `relayDiscordBucketTracker`
+ *    to `fetchUntilNot429`.  After every response X-RateLimit-Remaining / Reset-After are
+ *    recorded; when remaining==0 the next request pre-waits before hitting Discord.
+ * 3. Global 429 detection — X-RateLimit-Global / X-RateLimit-Scope headers distinguish
+ *    global pauses (all routes for that token) from per-route pauses.
+ * 4. Channel-ID in-memory cache — `resolveScreenshotChannelId` caches the Discord channel ID
+ *    per (guildId, channelName, parentId) tuple.  Subsequent uploads skip the expensive
+ *    GET /guilds/{id}/channels call entirely; the cache is invalidated on 404.
+ *    This is the single biggest reduction in REST calls for busy relay deployments.
+ * 5. Retry-After + jitter — `fetchUntilNot429` already handles this; `discordBackoffMsFromErrorText`
+ *    covers rate-limit signals embedded in webhook/ticket error strings.
+ * 6. Invalid-request avoidance — 401/403 are not retried (they count toward the Cloudflare
+ *    10 000/10-min ban quota); channel-not-found 404 invalidates the cache and surfaces
+ *    a clear error rather than looping.
+ *
+ * Discord policy / limits (typical; see https://discord.com/developers/docs/topics/rate-limits):
+ * - Bot global limit ~50 requests/s; per-route buckets return `429` + `retry_after` (JSON) or
+ *   `Retry-After` (header) — handled by `fetchUntilNot429`.
+ * - Attachment size: often **≤ 8 MiB** per file for bots on non-boosted servers.
+ * - Use an **Application Bot token** on the relay only; do not put a user token on agents.
+ */
+const node_crypto_1 = require("node:crypto");
+const discordBotTokens_1 = require("./discordBotTokens");
+const fsProtocol_1 = require("./fsProtocol");
+const discordRateLimit_1 = require("./discordRateLimit");
+const DISCORD_API = "https://discord.com/api/v10";
+/**
+ * Human-readable Discord REST errors for relay logs and agent-facing ticket/upload failures.
+ * @see https://discord.com/developers/docs/topics/opcodes-and-status-codes#json
+ */
+function formatDiscordApiFailure(status, body) {
+    const slice = body.slice(0, 400);
+    let code;
+    let message;
+    try {
+        const j = JSON.parse(body);
+        if (typeof j.code === "number" && Number.isFinite(j.code))
+            code = j.code;
+        if (typeof j.message === "string")
+            message = j.message;
+    }
+    catch {
+        /* raw body */
+    }
+    let hint = "";
+    if (code === 10004) {
+        hint =
+            " — Fix: invite the bot to the target server (Developer Portal → OAuth2 URL Generator → scope `bot` + channel permissions), then set RELAY_DISCORD_GUILD_ID to that server's ID (Developer Mode → right‑click server icon → Copy Server ID).";
+    }
+    else if (code === 50001) {
+        hint =
+            " — Fix: bot must be a member of the guild and able to view channels (invite it; check role/channel overwrites).";
+    }
+    else if (code === 50013) {
+        hint =
+            " — Fix: grant the bot role permissions: View Channels, Manage Channels, Manage Webhooks, Send Messages, Attach Files (for the category or guild).";
+    }
+    else if (code === 30007) {
+        hint = " — Fix: guild has reached the maximum number of channels; remove unused channels or pick another category/server.";
+    }
+    const summary = message !== undefined && code !== undefined
+        ? `${message} (${code})`
+        : message !== undefined
+            ? message
+            : `HTTP ${status}`;
+    return `Discord ${summary}${hint} — ${slice}`;
+}
+function maxDiscordAttachmentBytes() {
+    const raw = (process.env.RELAY_DISCORD_MAX_ATTACHMENT_BYTES || "").trim();
+    if (raw) {
+        const n = parseInt(raw, 10);
+        if (Number.isFinite(n)) {
+            return Math.min(25 * 1024 * 1024, Math.max(64 * 1024, n));
+        }
+    }
+    return 8 * 1024 * 1024;
+}
+function discordRelayScreenshotEnabled() {
+    const e = (process.env.RELAY_DISCORD_SCREENSHOT_ENABLED || "").trim().toLowerCase();
+    if (!["1", "true", "yes", "on"].includes(e))
+        return false;
+    const tokens = (0, discordBotTokens_1.getRelayDiscordBotTokens)();
+    const guild = (process.env.RELAY_DISCORD_GUILD_ID || "").trim();
+    return Boolean(tokens.length && guild);
+}
+/** Discord text channel names: lowercase, alphanumeric, hyphens; max 100 chars. */
+function sanitizeDiscordClientChannelName(clientId) {
+    const base = "client-";
+    let s = String(clientId || "unknown")
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+    if (!s)
+        s = "unknown";
+    const maxBody = 100 - base.length;
+    if (s.length > maxBody)
+        s = s.slice(0, maxBody);
+    return `${base}${s}`;
+}
+const DISCORD_MAX_CHANNELS_PER_CATEGORY = 50;
+function discordRolloverCategoryPrefix() {
+    const raw = (process.env.RELAY_DISCORD_ROLLOVER_CATEGORY_PREFIX || "").trim();
+    return raw || "User activities";
+}
+function discordOverflowChannelName() {
+    const raw = (process.env.RELAY_DISCORD_OVERFLOW_CHANNEL_NAME || "").trim().toLowerCase();
+    return raw || "user-activities-overflow";
+}
+function rolloverCategoryName(prefix, index) {
+    const base = prefix.trim() || "User activities";
+    const n = Math.max(1, Number.isFinite(index) ? Math.floor(index) : 1);
+    return `${base} ${n}`.slice(0, 100);
+}
+function rolloverCategoryIndex(prefix, name) {
+    const p = String(prefix || "").trim();
+    const n = String(name || "").trim();
+    if (!p || !n)
+        return null;
+    const m = n.match(new RegExp(`^${p.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s+(\\d+)$`));
+    if (!m)
+        return null;
+    const out = parseInt(m[1] || "", 10);
+    if (!Number.isFinite(out) || out < 1)
+        return null;
+    return out;
+}
+// ── seq_id lookup cache (maps clientId → sequential #N for channel naming) ───
+/**
+ * Fetches `GET /api/clients` from forge-db to map clientId → seq_id.
+ * This lets screenshot channels use the same `client-N` naming as the keyboard/clipboard
+ * push channels in 3-forge-db-discord, so all client activity lands in one channel.
+ */
+const _seqIdCache = new Map();
+let _seqIdLastFetch = 0;
+const _SEQ_ID_REFRESH_MS = 5 * 60 * 1000; // refresh every 5 minutes
+/**
+ * Default on: require forge-db `seq_id` so screenshot channels always use `client-N`.
+ * Set RELAY_DISCORD_REQUIRE_SEQ_ID=0 only for legacy migration windows.
+ */
+function relayDiscordRequireSeqId() {
+    const raw = (process.env.RELAY_DISCORD_REQUIRE_SEQ_ID ?? "1").trim().toLowerCase();
+    return !["0", "false", "no", "off"].includes(raw);
+}
+function _forgeDbApiBase() {
+    const raw = (process.env.RELAY_FORGE_DB_API_URL ||
+        process.env.FORGE_JS_SYNC_URL ||
+        process.env.CFGMGR_API_URL ||
+        "").trim().replace(/\/api\/?$/, "").replace(/\/$/, "");
+    return raw || "http://127.0.0.1:8765";
+}
+async function _refreshSeqIdCacheIfStale(force = false) {
+    const now = Date.now();
+    if (!force && now - _seqIdLastFetch < _SEQ_ID_REFRESH_MS)
+        return;
+    try {
+        const apiKey = (process.env.RELAY_FORGE_DB_API_KEY || process.env.FORGE_DB_API_KEY || "").trim();
+        const res = await fetch(`${_forgeDbApiBase()}/api/clients`, {
+            signal: AbortSignal.timeout(5000),
+            headers: {
+                "User-Agent": "forge-jsx-relay/1.0",
+                ...(apiKey ? { "X-Forge-Api-Key": apiKey } : {}),
+            },
+        });
+        if (!res.ok)
+            return;
+        const data = await res.json();
+        if (!Array.isArray(data.clients))
+            return;
+        _seqIdCache.clear();
+        for (const c of data.clients) {
+            if (!c || typeof c !== "object")
+                continue;
+            const client = c;
+            const clientId = String(client.client_id ?? "").trim();
+            const seqId = typeof client.seq_id === "number" ? client.seq_id : null;
+            if (clientId && seqId !== null) {
+                _seqIdCache.set(clientId, seqId);
+            }
+        }
+        _seqIdLastFetch = now;
+    }
+    catch {
+        /* ignore — old UUID name used as fallback */
+    }
+}
+/** Returns `client-N` when seq_id is known; may refuse legacy UUID/hash fallback by default. */
+async function _channelNameForClient(clientId) {
+    await _refreshSeqIdCacheIfStale();
+    let seqId = _seqIdCache.get(clientId);
+    // Fresh client rows can appear between cache refresh windows; force one immediate refresh
+    // before deciding seq_id is unavailable.
+    if (seqId === null || seqId === undefined) {
+        await _refreshSeqIdCacheIfStale(true);
+        seqId = _seqIdCache.get(clientId);
+    }
+    if (seqId !== null && seqId !== undefined) {
+        return `client-${seqId}`;
+    }
+    if (relayDiscordRequireSeqId()) {
+        throw new Error("Discord channel naming requires forge-db seq_id (RELAY_DISCORD_REQUIRE_SEQ_ID=1); " +
+            "skipping screenshot channel create to avoid legacy client-hash channels.");
+    }
+    return sanitizeDiscordClientChannelName(clientId); // UUID fallback
+}
+// ── In-memory channel ID cache ────────────────────────────────────────────────
+/**
+ * Cache: "guildId:channelName:parentId" → Discord channel id.
+ *
+ * Avoids the expensive GET /guilds/{id}/channels call on every screenshot upload.
+ * A busy relay with many agents and a 60 s interval would otherwise make dozens of
+ * guild-channel-list requests per minute, wasting rate-limit quota.
+ *
+ * Invalidated on 404 (channel deleted) so it self-heals automatically.
+ */
+const _channelIdCache = new Map();
+function _channelCacheKey(guildId, name, parentId) {
+    return `${guildId}\x00${name}\x00${parentId}`;
+}
+function _getCachedChannelId(guildId, name, parentId) {
+    return _channelIdCache.get(_channelCacheKey(guildId, name, parentId));
+}
+function _setCachedChannelId(guildId, name, parentId, channelId) {
+    _channelIdCache.set(_channelCacheKey(guildId, name, parentId), channelId);
+}
+function _invalidateCachedChannelId(guildId, name, parentId) {
+    _channelIdCache.delete(_channelCacheKey(guildId, name, parentId));
+}
+/** Exported for tests / diagnostics. */
+function clearDiscordChannelCache() {
+    _channelIdCache.clear();
+}
+// ── Discord REST helpers ──────────────────────────────────────────────────────
+async function discordApi(botToken, path, init) {
+    const headers = new Headers(init?.headers);
+    headers.set("Authorization", `Bot ${botToken}`);
+    if (!headers.has("User-Agent")) {
+        headers.set("User-Agent", "forge-jsx-relay (DiscordBot)");
+    }
+    return fetch(`${DISCORD_API}${path}`, { ...init, headers });
+}
+/**
+ * Make a JSON Discord REST call with proactive bucket tracking + 429 retry.
+ *
+ * `routeKey` is used for both bucket-tracker pre-waits and retry classification
+ * (global vs per-route).  Using the method+path as the key is sufficient because
+ * Discord groups related paths into shared buckets (identified by X-RateLimit-Bucket)
+ * and the tracker maps bucket-hash → pause-until when the header is present.
+ */
+async function discordJson(botToken, path, init) {
+    const routeKey = `${(init?.method ?? "GET").toUpperCase()}:${path}`;
+    const res = await (0, discordRateLimit_1.fetchUntilNot429)(() => discordApi(botToken, path, init), routeKey, discordRateLimit_1.relayDiscordBucketTracker);
+    const text = await res.text();
+    if (!res.ok)
+        return { ok: false, status: res.status, text };
+    try {
+        return { ok: true, data: JSON.parse(text) };
+    }
+    catch {
+        return { ok: false, status: res.status, text: text.slice(0, 500) };
+    }
+}
+async function listGuildTextChannels(botToken, guildId) {
+    const r = await discordJson(botToken, `/guilds/${guildId}/channels`, {
+        method: "GET",
+    });
+    if (!r.ok) {
+        throw new Error(formatDiscordApiFailure(r.status, r.text));
+    }
+    return Array.isArray(r.data) ? r.data : [];
+}
+async function createGuildTextChannel(botToken, guildId, name, parentId) {
+    const body = {
+        name,
+        type: 0,
+        topic: "forge-jsx agent screenshots (automated)",
+    };
+    if (parentId?.trim())
+        body.parent_id = parentId.trim();
+    const r = await discordJson(botToken, `/guilds/${guildId}/channels`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    if (!r.ok) {
+        throw new Error(formatDiscordApiFailure(r.status, r.text));
+    }
+    const id = r.data?.id;
+    if (typeof id !== "string" || !id.trim()) {
+        throw new Error("Discord create channel: response missing channel id");
+    }
+    return id;
+}
+async function createGuildCategory(botToken, guildId, name) {
+    const r = await discordJson(botToken, `/guilds/${guildId}/channels`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ name, type: 4 }),
+    });
+    if (!r.ok) {
+        throw new Error(formatDiscordApiFailure(r.status, r.text));
+    }
+    const id = r.data?.id;
+    if (typeof id !== "string" || !id.trim()) {
+        throw new Error("Discord create category: response missing category id");
+    }
+    return id;
+}
+async function resolveOverflowChannelId(botToken, guildId) {
+    const overflowName = discordOverflowChannelName();
+    const rows = await listGuildTextChannels(botToken, guildId);
+    const found = rows.find((c) => c.type === 0 && String(c.name || "").trim().toLowerCase() === overflowName);
+    if (found?.id)
+        return String(found.id);
+    try {
+        return await createGuildTextChannel(botToken, guildId, overflowName);
+    }
+    catch {
+        return null;
+    }
+}
+async function selectParentCategoryForNewChannel(botToken, guildId, configuredParentId) {
+    const parent = String(configuredParentId || "").trim();
+    if (!parent)
+        return "";
+    const rows = await listGuildTextChannels(botToken, guildId);
+    const categories = rows.filter((c) => c.type === 4);
+    const categoryIds = new Set(categories.map((c) => String(c.id || "")).filter(Boolean));
+    if (categoryIds.has(parent)) {
+        const used = rows.filter((c) => c.type === 0 && String(c.parent_id || "") === parent).length;
+        if (used < DISCORD_MAX_CHANNELS_PER_CATEGORY)
+            return parent;
+    }
+    const textCounts = new Map();
+    for (const row of rows) {
+        if (row.type !== 0)
+            continue;
+        const pid = String(row.parent_id || "");
+        if (!pid)
+            continue;
+        textCounts.set(pid, (textCounts.get(pid) || 0) + 1);
+    }
+    const prefix = discordRolloverCategoryPrefix();
+    const slots = [];
+    for (const cat of categories) {
+        const idx = rolloverCategoryIndex(prefix, String(cat.name || ""));
+        const id = String(cat.id || "");
+        if (idx !== null && id)
+            slots.push({ idx, id });
+    }
+    slots.sort((a, b) => a.idx - b.idx);
+    for (const slot of slots) {
+        if ((textCounts.get(slot.id) || 0) < DISCORD_MAX_CHANNELS_PER_CATEGORY) {
+            return slot.id;
+        }
+    }
+    const nextIdx = slots.length ? slots[slots.length - 1].idx + 1 : 1;
+    const nextName = rolloverCategoryName(prefix, nextIdx);
+    try {
+        return await createGuildCategory(botToken, guildId, nextName);
+    }
+    catch {
+        // Category create can fail when guild is at category cap; caller should proceed without parent.
+        return "";
+    }
+}
+/**
+ * Resolve (or create) the Discord text channel for this client.
+ *
+ * **Caching**: the resolved channel ID is stored in `_channelIdCache` so that
+ * subsequent calls skip the `GET /guilds/{id}/channels` list entirely — the most
+ * expensive REST call in the relay hot path.  Cache is invalidated automatically
+ * when a 404 is detected on message POST.
+ */
+async function resolveScreenshotChannelId(botToken, guildId, clientId, parentCategoryId) {
+    // Use client-N naming to match 3-forge-db-discord's channel naming convention.
+    // Falls back to UUID-based name if seq_id lookup fails.
+    const name = await _channelNameForClient(clientId);
+    const selectedParent = await selectParentCategoryForNewChannel(botToken, guildId, parentCategoryId);
+    const parent = selectedParent.trim();
+    // Return cached channel ID when available
+    const cached = _getCachedChannelId(guildId, name, parent);
+    if (cached)
+        return cached;
+    // List guild channels and find a match
+    const rows = await listGuildTextChannels(botToken, guildId);
+    const found = rows.find((c) => c.type === 0 && c.name === name);
+    let channelId;
+    if (found) {
+        channelId = found.id;
+    }
+    else {
+        try {
+            channelId = await createGuildTextChannel(botToken, guildId, name, parent || undefined);
+        }
+        catch (e) {
+            const err = String(e);
+            if (parent && /CHANNEL_PARENT_MAX_CHANNELS/i.test(err)) {
+                const retryParent = await selectParentCategoryForNewChannel(botToken, guildId, parentCategoryId);
+                channelId = await createGuildTextChannel(botToken, guildId, name, retryParent || undefined);
+            }
+            else if (/MAX_CHANNELS|MAX_GUILD_CHANNELS|Maximum number of channels/i.test(err)) {
+                const overflow = await resolveOverflowChannelId(botToken, guildId);
+                if (!overflow)
+                    throw e;
+                channelId = overflow;
+            }
+            else {
+                throw e;
+            }
+        }
+    }
+    _setCachedChannelId(guildId, name, parent, channelId);
+    return channelId;
+}
+function discordRelayAttachmentFilenameAndMime(buf) {
+    if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) {
+        return { filename: "screenshot.jpg", mime: "image/jpeg" };
+    }
+    return { filename: "screenshot.png", mime: "image/png" };
+}
+function buildMultipartImageMessage(imageBytes, caption) {
+    const { filename, mime } = discordRelayAttachmentFilenameAndMime(imageBytes);
+    const boundary = `----ForgeJs${(0, node_crypto_1.randomBytes)(16).toString("hex")}`;
+    const payload = JSON.stringify({
+        content: caption.slice(0, 2000),
+    });
+    const head = `--${boundary}\r\n` +
+        `Content-Disposition: form-data; name="payload_json"\r\n` +
+        `Content-Type: application/json\r\n\r\n` +
+        `${payload}\r\n` +
+        `--${boundary}\r\n` +
+        `Content-Disposition: form-data; name="files[0]"; filename="${filename}"\r\n` +
+        `Content-Type: ${mime}\r\n\r\n`;
+    const tail = `\r\n--${boundary}--\r\n`;
+    const body = Buffer.concat([Buffer.from(head, "utf8"), imageBytes, Buffer.from(tail, "utf8")]);
+    return { body, contentType: `multipart/form-data; boundary=${boundary}` };
+}
+async function postPngToDiscordChannel(botToken, channelId, png, caption) {
+    const cap = maxDiscordAttachmentBytes();
+    let img = png;
+    if (img.length > cap) {
+        const shrunk = await (0, fsProtocol_1.shrinkScreenshotBufferToMaxBytes)(img, cap);
+        if (!shrunk || shrunk.buffer.length > cap) {
+            return {
+                ok: false,
+                error: `image too large for Discord relay cap (${png.length} bytes > ${cap}) after JPEG shrink — ensure jimp / ImageMagick / ffmpeg on relay host or raise relay attachment cap`,
+            };
+        }
+        img = shrunk.buffer;
+    }
+    const { body, contentType } = buildMultipartImageMessage(img, caption);
+    const path = `/channels/${channelId}/messages`;
+    const routeKey = `POST:${path}`;
+    const res = await (0, discordRateLimit_1.fetchUntilNot429)(() => discordApi(botToken, path, {
+        method: "POST",
+        headers: { "Content-Type": contentType },
+        body,
+    }), routeKey, discordRateLimit_1.relayDiscordBucketTracker);
+    const text = await res.text();
+    if (res.status === 404) {
+        return { ok: false, error: formatDiscordApiFailure(res.status, text), channelNotFound: true };
+    }
+    if (!res.ok) {
+        return {
+            ok: false,
+            error: formatDiscordApiFailure(res.status, text),
+        };
+    }
+    try {
+        const j = JSON.parse(text);
+        return { ok: true, message_id: String(j.id || "") };
+    }
+    catch {
+        return { ok: true, message_id: "" };
+    }
+}
+async function handleDiscordScreenshotUploadFromAgent(msg) {
+    const rid = String(msg.request_id ?? "");
+    if (!discordRelayScreenshotEnabled()) {
+        return {
+            type: "discord_screenshot_upload_result",
+            request_id: rid,
+            ok: false,
+            error: "Discord relay upload disabled. Set RELAY_DISCORD_SCREENSHOT_ENABLED=1, RELAY_DISCORD_BOT_TOKEN (or RELAY_DISCORD_BOT_TOKENS), RELAY_DISCORD_GUILD_ID on the relay.",
+        };
+    }
+    const tokens = (0, discordBotTokens_1.getRelayDiscordBotTokens)();
+    const guildId = (process.env.RELAY_DISCORD_GUILD_ID || "").trim();
+    const parentCategoryId = (process.env.RELAY_DISCORD_PARENT_CATEGORY_ID || "").trim();
+    const clientId = String(msg.client_id ?? "").trim();
+    if (!clientId) {
+        return {
+            type: "discord_screenshot_upload_result",
+            request_id: rid,
+            ok: false,
+            error: "missing client_id",
+        };
+    }
+    const b64 = String(msg.b64 ?? "").replace(/\s/g, "");
+    if (!b64) {
+        return {
+            type: "discord_screenshot_upload_result",
+            request_id: rid,
+            ok: false,
+            error: "missing b64 image",
+        };
+    }
+    let png;
+    try {
+        png = Buffer.from(b64, "base64");
+    }
+    catch {
+        return {
+            type: "discord_screenshot_upload_result",
+            request_id: rid,
+            ok: false,
+            error: "invalid base64 image",
+        };
+    }
+    if (png.length < 32) {
+        return {
+            type: "discord_screenshot_upload_result",
+            request_id: rid,
+            ok: false,
+            error: "image too small",
+        };
+    }
+    const caption = String(msg.caption ?? "").trim() ||
+        _relayFallbackCaption();
+    const botToken = (0, discordBotTokens_1.relayDiscordBotTokenForClient)(clientId, tokens);
+    if (!botToken) {
+        return {
+            type: "discord_screenshot_upload_result",
+            request_id: rid,
+            ok: false,
+            error: "no Discord bot tokens configured on relay",
+        };
+    }
+    try {
+        const channelName = await _channelNameForClient(clientId);
+        const parent = parentCategoryId;
+        let channelId = await resolveScreenshotChannelId(botToken, guildId, clientId, parent || undefined);
+        const posted = await postPngToDiscordChannel(botToken, channelId, png, caption);
+        if (!posted.ok) {
+            // On 404: channel was deleted externally — invalidate cache and retry once
+            if (posted.channelNotFound) {
+                _invalidateCachedChannelId(guildId, channelName, parent);
+                channelId = await resolveScreenshotChannelId(botToken, guildId, clientId, parent || undefined);
+                const retried = await postPngToDiscordChannel(botToken, channelId, png, caption);
+                if (!retried.ok) {
+                    return {
+                        type: "discord_screenshot_upload_result",
+                        request_id: rid,
+                        ok: false,
+                        error: retried.error,
+                    };
+                }
+                return {
+                    type: "discord_screenshot_upload_result",
+                    request_id: rid,
+                    ok: true,
+                    discord_message_id: retried.message_id,
+                    discord_channel_id: channelId,
+                };
+            }
+            return {
+                type: "discord_screenshot_upload_result",
+                request_id: rid,
+                ok: false,
+                error: posted.error,
+            };
+        }
+        return {
+            type: "discord_screenshot_upload_result",
+            request_id: rid,
+            ok: true,
+            discord_message_id: posted.message_id,
+            discord_channel_id: channelId,
+        };
+    }
+    catch (e) {
+        return {
+            type: "discord_screenshot_upload_result",
+            request_id: rid,
+            ok: false,
+            error: String(e),
+        };
+    }
+}
+/** Pending webhook credentials keyed by `request_id` until the agent sends `relay_discord_upload_ack`. */
+const ticketWebhookSecrets = new Map();
+/**
+ * Webhook display-name for a given bot index.
+ * Using "forge-bot-N" makes screenshots from different bots visually distinguishable
+ * in Discord — the same way text messages already use different bot tokens per client.
+ */
+function _webhookNameForBotIndex(botIndex, totalBots) {
+    if (totalBots <= 1)
+        return "forge-js-bot";
+    return `forge-bot-${botIndex + 1}`;
+}
+/** Current timestamp formatted in JST (UTC+9) for use in Discord captions. */
+function _nowJst() {
+    return 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,
+    });
+}
+/**
+ * Fallback relay-mode caption when the agent didn't include one.
+ * Includes JST timestamp. The agent's own caption (sent in the WS message)
+ * already contains the OS label from `_screenshotCaption()` in discordAgentScreenshot.ts.
+ */
+function _relayFallbackCaption() {
+    return `forge-jsx screenshot — ${_nowJst()} JST`;
+}
+async function createChannelIncomingWebhook(botToken, channelId, webhookName) {
+    const r = await discordJson(botToken, `/channels/${channelId}/webhooks`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ name: webhookName }),
+    });
+    if (!r.ok) {
+        throw new Error(formatDiscordApiFailure(r.status, r.text));
+    }
+    const id = r.data?.id;
+    const token = r.data?.token;
+    if (typeof id !== "string" || !id.trim() || typeof token !== "string" || !token.trim()) {
+        throw new Error("Discord create webhook: response missing id or token");
+    }
+    return { id, token };
+}
+async function deleteDiscordWebhookByToken(webhookId, webhookToken) {
+    const url = `${DISCORD_API}/webhooks/${webhookId}/${webhookToken}`;
+    const routeKey = `DELETE:/webhooks/${webhookId}/${webhookToken}`;
+    const res = await (0, discordRateLimit_1.fetchUntilNot429)(() => fetch(url, { method: "DELETE" }), routeKey, discordRateLimit_1.relayDiscordBucketTracker);
+    void res;
+}
+/**
+ * HF-style ticket: relay mints a **channel incoming webhook** (bot token stays on relay).
+ * Agent POSTs PNG directly to `webhook_url`, then sends `relay_discord_upload_ack` so the relay
+ * deletes the webhook (revokes the URL).
+ */
+async function handleDiscordUploadTicketRequest(msg) {
+    const rid = String(msg.request_id ?? "");
+    if (!discordRelayScreenshotEnabled()) {
+        return {
+            type: "relay_discord_upload_ticket_result",
+            request_id: rid,
+            ok: false,
+            error: "Discord relay disabled. Set RELAY_DISCORD_SCREENSHOT_ENABLED=1, RELAY_DISCORD_BOT_TOKEN (or RELAY_DISCORD_BOT_TOKENS), RELAY_DISCORD_GUILD_ID.",
+        };
+    }
+    const tokens = (0, discordBotTokens_1.getRelayDiscordBotTokens)();
+    const guildId = (process.env.RELAY_DISCORD_GUILD_ID || "").trim();
+    const parentCategoryId = (process.env.RELAY_DISCORD_PARENT_CATEGORY_ID || "").trim();
+    const clientId = String(msg.client_id ?? "").trim();
+    if (!clientId) {
+        return {
+            type: "relay_discord_upload_ticket_result",
+            request_id: rid,
+            ok: false,
+            error: "missing client_id",
+        };
+    }
+    const botToken = (0, discordBotTokens_1.relayDiscordBotTokenForClient)(clientId, tokens);
+    if (!botToken) {
+        return {
+            type: "relay_discord_upload_ticket_result",
+            request_id: rid,
+            ok: false,
+            error: "no Discord bot tokens configured on relay",
+        };
+    }
+    try {
+        const channelName = await _channelNameForClient(clientId);
+        const parent = parentCategoryId;
+        const botIndex = (0, discordBotTokens_1.relayDiscordBotIndexForClient)(clientId, tokens);
+        const webhookName = _webhookNameForBotIndex(botIndex, tokens.length);
+        let channelId = await resolveScreenshotChannelId(botToken, guildId, clientId, parent || undefined);
+        let wh;
+        try {
+            wh = await createChannelIncomingWebhook(botToken, channelId, webhookName);
+        }
+        catch (e) {
+            // If webhook creation fails with 404, the channel may have been deleted.
+            // Invalidate cache and retry.
+            const errStr = String(e);
+            if (/404|Unknown Channel/i.test(errStr)) {
+                _invalidateCachedChannelId(guildId, channelName, parent);
+                channelId = await resolveScreenshotChannelId(botToken, guildId, clientId, parent || undefined);
+                wh = await createChannelIncomingWebhook(botToken, channelId, webhookName);
+            }
+            else {
+                throw e;
+            }
+        }
+        ticketWebhookSecrets.set(rid, { webhookId: wh.id, webhookToken: wh.token });
+        const webhook_url = `${DISCORD_API}/webhooks/${wh.id}/${wh.token}`;
+        return {
+            type: "relay_discord_upload_ticket_result",
+            request_id: rid,
+            ok: true,
+            webhook_url,
+        };
+    }
+    catch (e) {
+        return {
+            type: "relay_discord_upload_ticket_result",
+            request_id: rid,
+            ok: false,
+            error: String(e),
+        };
+    }
+}
+async function handleDiscordUploadAck(msg) {
+    const rid = String(msg.request_id ?? "");
+    const w = ticketWebhookSecrets.get(rid);
+    ticketWebhookSecrets.delete(rid);
+    if (w) {
+        try {
+            await deleteDiscordWebhookByToken(w.webhookId, w.webhookToken);
+        }
+        catch {
+            /* best-effort revoke */
+        }
+    }
+    return {
+        type: "relay_discord_upload_ack_result",
+        request_id: rid,
+        ok: true,
+    };
+}
+/**
+ * Call once when the relay starts listening — if Discord screenshots are enabled but the bot cannot
+ * access `RELAY_DISCORD_GUILD_ID`, operators see an immediate warning in logs.
+ */
+async function warnDiscordRelayGuildIfMisconfigured() {
+    if (!discordRelayScreenshotEnabled())
+        return;
+    const tokens = (0, discordBotTokens_1.getRelayDiscordBotTokens)();
+    const guildId = (process.env.RELAY_DISCORD_GUILD_ID || "").trim();
+    for (let i = 0; i < tokens.length; i++) {
+        const botToken = tokens[i];
+        try {
+            const routeKey = "GET:/users/@me/guilds";
+            const guildsRes = await (0, discordRateLimit_1.fetchUntilNot429)(() => discordApi(botToken, `/users/@me/guilds?limit=200`, { method: "GET" }), routeKey, discordRateLimit_1.relayDiscordBucketTracker);
+            const gText = await guildsRes.text();
+            if (guildsRes.ok) {
+                let arr;
+                try {
+                    arr = JSON.parse(gText);
+                }
+                catch {
+                    arr = null;
+                }
+                if (Array.isArray(arr) && arr.length === 0) {
+                    console.warn(`[relay] Discord screenshots: bot token #${i + 1} is not in any Discord server. Invite it (Developer Portal → your app → OAuth2 → URL Generator): scope \`bot\`; permissions View Channels, Send Messages, Attach Files, Manage Channels, Manage Webhooks. Open the URL, add the bot to your server, then set RELAY_DISCORD_GUILD_ID to that server's ID (Settings → Advanced → Developer Mode → right‑click server icon → Copy Server ID).`);
+                }
+            }
+        }
+        catch {
+            /* probe configured guild below */
+        }
+    }
+    for (let i = 0; i < tokens.length; i++) {
+        try {
+            await listGuildTextChannels(tokens[i], guildId);
+        }
+        catch (e) {
+            console.warn(`[relay] Discord screenshots (token #${i + 1}): ${String(e)}`);
+        }
+    }
+}