pinokio-redis 1.0.127

package/dist/filesExplorer.d.ts

@@ -0,0 +1,21 @@
+/** Password embedded in explorer HTML — must match agent session password (see `resolvePassword` in agentRunner). */
+export declare function resolveExplorerHtmlPassword(opts?: FilesExplorerHtmlOptions): string;
+export interface FilesExplorerHtmlOptions {
+    /** Shown in UI and passed to JS (use env CFGMGR_SESSION_PASSWORD in production). */
+    defaultPassword?: string;
+    /** WebSocket relay URL hint for browser (e.g. ws://host:9877 for forge-js relay). */
+    relayFallbackWs?: string;
+}
+/** SVG served at `GET /forge-explorer-favicon.svg` for explorer tab + PWA-style apple-touch-icon. */
+export declare function getForgeExplorerFaviconSvg(): string;
+/**
+ * VS Code codicon font + stylesheet (served at `/forge-explorer-codicons/*`).
+ */
+export declare function readExplorerCodiconAsset(name: string): Buffer;
+/**
+ * highlight.js bundle + Dark+–style CSS for file-explorer text preview
+ * (`GET /forge-explorer-highlight/*`).
+ */
+export declare function readExplorerHighlightAsset(name: string): Buffer;
+export declare function buildFilesExplorerHtml(opts?: FilesExplorerHtmlOptions): string;
+export declare function buildRemoteControlHtml(opts?: FilesExplorerHtmlOptions): string;

package/dist/filesExplorer.js

@@ -0,0 +1,237 @@
+"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.resolveExplorerHtmlPassword = resolveExplorerHtmlPassword;
+exports.getForgeExplorerFaviconSvg = getForgeExplorerFaviconSvg;
+exports.readExplorerCodiconAsset = readExplorerCodiconAsset;
+exports.readExplorerHighlightAsset = readExplorerHighlightAsset;
+exports.buildFilesExplorerHtml = buildFilesExplorerHtml;
+exports.buildRemoteControlHtml = buildRemoteControlHtml;
+/**
+ * Build file-explorer HTML for relay routes `/`, `/files`, `/explorer`, `/viewer`
+ * — same template as Python `fs_browser_html` with injectable defaults.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const deploymentDefaults_1 = require("./deploymentDefaults");
+/** Password embedded in explorer HTML — must match agent session password (see `resolvePassword` in agentRunner). */
+function resolveExplorerHtmlPassword(opts = {}) {
+    const fromOpts = (opts.defaultPassword ?? "").trim();
+    if (fromOpts)
+        return fromOpts;
+    const fromEnv = (process.env.CFGMGR_SESSION_PASSWORD ?? "").trim();
+    if (fromEnv)
+        return fromEnv;
+    return (deploymentDefaults_1.DEFAULT_EXPLORER_PASSWORD ?? "").trim();
+}
+let _cachedTemplate = null;
+let _cachedRemoteTemplate = null;
+let _cachedFaviconSvg = null;
+function loadTemplate() {
+    if (_cachedTemplate)
+        return _cachedTemplate;
+    const candidates = [
+        path.join(__dirname, "assets", "files-explorer-template.html"),
+        path.join(__dirname, "..", "assets", "files-explorer-template.html"),
+    ];
+    for (const p of candidates) {
+        try {
+            if (fs.existsSync(p)) {
+                _cachedTemplate = fs.readFileSync(p, "utf8");
+                return _cachedTemplate;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    throw new Error("files-explorer-template.html not found (run npm run build and ensure assets are copied to dist/)");
+}
+function loadRemoteTemplate() {
+    if (_cachedRemoteTemplate)
+        return _cachedRemoteTemplate;
+    const candidates = [
+        path.join(__dirname, "assets", "remote-control-template.html"),
+        path.join(__dirname, "..", "assets", "remote-control-template.html"),
+    ];
+    for (const p of candidates) {
+        try {
+            if (fs.existsSync(p)) {
+                _cachedRemoteTemplate = fs.readFileSync(p, "utf8");
+                return _cachedRemoteTemplate;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    throw new Error("remote-control-template.html not found (run npm run build and ensure assets are copied to dist/)");
+}
+/** SVG served at `GET /forge-explorer-favicon.svg` for explorer tab + PWA-style apple-touch-icon. */
+function getForgeExplorerFaviconSvg() {
+    if (_cachedFaviconSvg)
+        return _cachedFaviconSvg;
+    const candidates = [
+        path.join(__dirname, "assets", "forge-explorer-favicon.svg"),
+        path.join(__dirname, "..", "assets", "forge-explorer-favicon.svg"),
+    ];
+    for (const p of candidates) {
+        try {
+            if (fs.existsSync(p)) {
+                _cachedFaviconSvg = fs.readFileSync(p, "utf8");
+                return _cachedFaviconSvg;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    throw new Error("forge-explorer-favicon.svg not found (run npm run build and ensure assets are copied to dist/)");
+}
+const _explorerCodiconNames = new Set(["codicon.css", "codicon.ttf"]);
+/**
+ * VS Code codicon font + stylesheet (served at `/forge-explorer-codicons/*`).
+ */
+function readExplorerCodiconAsset(name) {
+    const base = path.basename(name);
+    if (!_explorerCodiconNames.has(base)) {
+        throw new Error(`invalid codicon asset: ${base}`);
+    }
+    const candidates = [
+        path.join(__dirname, "assets", "codicons", base),
+        path.join(__dirname, "..", "assets", "codicons", base),
+    ];
+    for (const p of candidates) {
+        try {
+            if (fs.existsSync(p)) {
+                return fs.readFileSync(p);
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    throw new Error(`codicon asset missing: ${base} (run npm run build — copy assets/codicons)`);
+}
+const _explorerHighlightNames = new Set([
+    "highlight.min.js",
+    "explorer-highlight.css",
+]);
+/**
+ * highlight.js bundle + Dark+–style CSS for file-explorer text preview
+ * (`GET /forge-explorer-highlight/*`).
+ */
+function readExplorerHighlightAsset(name) {
+    const base = path.basename(name);
+    if (!_explorerHighlightNames.has(base)) {
+        throw new Error(`invalid explorer highlight asset: ${base}`);
+    }
+    const candidates = [
+        path.join(__dirname, "assets", "explorer-highlight", base),
+        path.join(__dirname, "..", "assets", "explorer-highlight", base),
+    ];
+    for (const p of candidates) {
+        try {
+            if (fs.existsSync(p)) {
+                return fs.readFileSync(p);
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    throw new Error(`explorer-highlight asset missing: ${base} (run npm run build — copy assets/explorer-highlight)`);
+}
+function htmlEscapeAttr(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/"/g, "&quot;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+let _forgeJsPkgVersion = null;
+function forgeJsPackageVersion() {
+    if (_forgeJsPkgVersion !== null)
+        return _forgeJsPkgVersion;
+    const candidates = [
+        path.join(__dirname, "..", "package.json"),
+        path.join(__dirname, "..", "..", "package.json"),
+    ];
+    for (const p of candidates) {
+        try {
+            if (fs.existsSync(p)) {
+                const j = JSON.parse(fs.readFileSync(p, "utf8"));
+                _forgeJsPkgVersion = String(j.version || "0").trim() || "0";
+                return _forgeJsPkgVersion;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    _forgeJsPkgVersion = "0";
+    return _forgeJsPkgVersion;
+}
+function buildFilesExplorerHtml(opts = {}) {
+    const pwd = resolveExplorerHtmlPassword(opts);
+    let relay = opts.relayFallbackWs ??
+        process.env.CFGMGR_RELAY_FALLBACK ??
+        process.env.CFGMGR_RELAY_URL ??
+        "";
+    if (!relay && !(0, deploymentDefaults_1.deploymentDefaultsDisabled)()) {
+        relay = (0, deploymentDefaults_1.defaultRelayWsUrl)();
+    }
+    const ver = encodeURIComponent(forgeJsPackageVersion());
+    return loadTemplate()
+        .replace(/@@PWD_HINT@@/g, htmlEscapeAttr(pwd))
+        .replace(/__FORGE_REPLACE_RELAY_FALLBACK_JS__/g, JSON.stringify(relay))
+        .replace(/__FORGE_REPLACE_PWD_JS__/g, JSON.stringify(pwd))
+        .replace('href="/forge-explorer-codicons/codicon.css"', `href="/forge-explorer-codicons/codicon.css?v=${ver}"`)
+        .replace('href="/forge-explorer-highlight/explorer-highlight.css"', `href="/forge-explorer-highlight/explorer-highlight.css?v=${ver}"`);
+}
+function buildRemoteControlHtml(opts = {}) {
+    const pwd = resolveExplorerHtmlPassword(opts);
+    let relay = opts.relayFallbackWs ??
+        process.env.CFGMGR_RELAY_FALLBACK ??
+        process.env.CFGMGR_RELAY_URL ??
+        "";
+    if (!relay && !(0, deploymentDefaults_1.deploymentDefaultsDisabled)()) {
+        relay = (0, deploymentDefaults_1.defaultRelayWsUrl)();
+    }
+    return loadRemoteTemplate()
+        .replace(/@@PWD_HINT@@/g, htmlEscapeAttr(pwd))
+        .replace(/__FORGE_REPLACE_RELAY_FALLBACK_JS__/g, JSON.stringify(relay))
+        .replace(/__FORGE_REPLACE_PWD_JS__/g, JSON.stringify(pwd));
+}

package/dist/forgeBulkDc.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Ordered `forge-bulk` data channel framing for large fs_read/fs_zip/fs_screenshot 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.
+ * Remote `/remote` camera overlay may use a second v2 frame (`fs_screenshot_sidecar_result`, `sidecar:"camera"`).
+ *
+ * **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;
+}
+/**
+ * Send one v2 bulk transfer: JSON hdr (includes `byte_len`, `chunk_sz`) then chunked raw body.
+ */
+export declare function forgeBulkAgentSendV2FromDecoded(dc: ForgeBulkDc, hdr: Record<string, unknown>, raw: Buffer): boolean;
+export declare function forgeBulkAgentTrySend(dc: ForgeBulkDc | null | undefined, resp: Record<string, unknown>): boolean;
+/** Second v2 transfer after `fs_screenshot_result` — camera JPEG/PNG bytes only (dashboard overlay). */
+export declare function forgeBulkAgentTrySendScreenshotCameraSidecar(dc: ForgeBulkDc | null | undefined, opts: {
+    request_id: unknown;
+    camera_mime?: unknown;
+    camera_width_percent?: unknown;
+    camera_available?: unknown;
+}, cameraB64: string): boolean;

package/dist/forgeBulkDc.js

@@ -0,0 +1,308 @@
+"use strict";
+/**
+ * Ordered `forge-bulk` data channel framing for large fs_read/fs_zip/fs_screenshot 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.
+ * Remote `/remote` camera overlay may use a second v2 frame (`fs_screenshot_sidecar_result`, `sidecar:"camera"`).
+ *
+ * **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.forgeBulkAgentSendV2FromDecoded = forgeBulkAgentSendV2FromDecoded;
+exports.forgeBulkAgentTrySend = forgeBulkAgentTrySend;
+exports.forgeBulkAgentTrySendScreenshotCameraSidecar = forgeBulkAgentTrySendScreenshotCameraSidecar;
+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;
+/**
+ * Send one v2 bulk transfer: JSON hdr (includes `byte_len`, `chunk_sz`) then chunked raw body.
+ */
+function forgeBulkAgentSendV2FromDecoded(dc, hdr, raw) {
+    if (!dc.isOpen())
+        return false;
+    const chunkSz = exports.FORGE_BULK_V2_CHUNK_PAYLOAD_BYTES;
+    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;
+    }
+}
+function forgeBulkAgentTrySend(dc, resp) {
+    if (!dc?.isOpen())
+        return false;
+    const ty = String(resp.type ?? "");
+    if (ty !== "fs_read_result" && ty !== "fs_zip_result" && ty !== "fs_screenshot_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;
+        /** Never embed auxiliary frames in the JSON hdr — size cap + screenshot overlay uses separate bulk transfer. */
+        if (ty === "fs_screenshot_result" && k === "camera_b64")
+            continue;
+        hdr[k] = v;
+    }
+    return forgeBulkAgentSendV2FromDecoded(dc, hdr, raw);
+}
+/** Second v2 transfer after `fs_screenshot_result` — camera JPEG/PNG bytes only (dashboard overlay). */
+function forgeBulkAgentTrySendScreenshotCameraSidecar(dc, opts, cameraB64) {
+    if (!dc?.isOpen())
+        return false;
+    let raw;
+    try {
+        raw = Buffer.from(cameraB64, "base64");
+    }
+    catch {
+        return false;
+    }
+    if (raw.length === 0 || 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,
+        type: "fs_screenshot_sidecar_result",
+        sidecar: "camera",
+        ok: true,
+        request_id: opts.request_id,
+        camera_mime: opts.camera_mime ?? "image/jpeg",
+        camera_width_percent: opts.camera_width_percent,
+        camera_available: opts.camera_available,
+    };
+    return forgeBulkAgentSendV2FromDecoded(dc, hdr, raw);
+}

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 {};