@cli-remote/local 0.3.4 → 0.4.1

package/dist/index.cjs

@@ -2263,7 +2263,7 @@ var require_websocket = __commonJS({
     var EventEmitter = require("events");
     var https = require("https");
     var http = require("http");
-    var net = require("net");
+    var net2 = require("net");
     var tls = require("tls");
     var { randomBytes: randomBytes3, createHash: createHash2 } = require("crypto");
     var { Duplex, Readable } = require("stream");
@@ -3007,12 +3007,12 @@ var require_websocket = __commonJS({
     }
     function netConnect(options) {
       options.path = options.socketPath;
-      return net.connect(options);
+      return net2.connect(options);
     }
     function tlsConnect(options) {
       options.path = void 0;
       if (!options.servername && options.servername !== "") {
-        options.servername = net.isIP(options.host) ? "" : options.host;
+        options.servername = net2.isIP(options.host) ? "" : options.host;
       }
       return tls.connect(options);
     }
@@ -9940,7 +9940,7 @@ var require_lib = __commonJS({
 
 // src/index.ts
 var import_node_fs5 = require("node:fs");
-var import_node_child_process4 = require("node:child_process");
+var import_node_child_process5 = require("node:child_process");
 var import_node_os8 = require("node:os");
 var import_node_path8 = require("node:path");
 var import_node_url = require("node:url");
@@ -9957,7 +9957,7 @@ var import_websocket_server = __toESM(require_websocket_server(), 1);
 var wrapper_default = import_websocket.default;
 
 // src/client.ts
-var import_node_child_process3 = require("node:child_process");
+var import_node_child_process4 = require("node:child_process");
 var import_node_readline = require("node:readline");
 var import_node_fs4 = require("node:fs");
 var import_node_os7 = require("node:os");
@@ -10031,6 +10031,8 @@ function resolveCommand(cmd) {
       return { file: "kimi", args: [] };
     case "pi":
       return { file: "pi", args: [] };
+    case "desktop":
+      throw new Error("desktop sessions are not PTY sessions");
     default:
       return { file: cmd, args: [] };
   }
@@ -10214,6 +10216,12 @@ var SessionLogger = class {
     if (this.closed || this.mode === "off") return;
     this.write({ ts: Date.now(), event: "forced", cmd });
   }
+  /** Desktop display/workspace switch metadata (v0.8). Content is never
+   *  logged — this records only WHICH screen/desktop was switched to. */
+  logSwitch(kind, value) {
+    if (this.closed || this.mode === "off") return;
+    this.write({ ts: Date.now(), event: "switch", kind, value });
+  }
   logExit(code) {
     if (this.closed || this.mode === "off") return;
     this.write({ ts: Date.now(), event: "exit", code });
@@ -10421,6 +10429,396 @@ async function exists(p) {
   }
 }
 
+// src/desktop-manager.ts
+var import_node_child_process = require("node:child_process");
+var import_node_util = require("node:util");
+var import_node_net = __toESM(require("node:net"), 1);
+var execFileP = (0, import_node_util.promisify)(import_node_child_process.execFile);
+var X11VNC_START_TIMEOUT_MS = 8e3;
+var PAUSE_POLL_MS = 25;
+var EXEC_TIMEOUT_MS = 5e3;
+var DesktopManager = class {
+  constructor(hooks, config, platform2 = process.platform, execImpl, spawnImpl) {
+    this.hooks = hooks;
+    this.config = config;
+    this.platform = platform2;
+    this.exec = execImpl ?? ((file, args, timeoutMs = EXEC_TIMEOUT_MS) => execFileP(file, args, { timeout: timeoutMs }).then((r) => String(r.stdout ?? "")));
+    this.spawnChildFn = spawnImpl ?? ((file, args) => {
+      const child = (0, import_node_child_process.spawn)(file, args, { stdio: "ignore" });
+      child.unref();
+      return child;
+    });
+  }
+  sessions = /* @__PURE__ */ new Map();
+  exec;
+  spawnChildFn;
+  /** Human-readable reason when the machine cannot serve desktop sessions. */
+  unsupportedReason() {
+    if (!this.config.enabled) {
+      return 'desktop disabled on this device (config.json: {"desktop": {"enabled": true}})';
+    }
+    if (this.platform === "win32") {
+      return "desktop sessions are not supported on Windows yet";
+    }
+    return null;
+  }
+  // -------------------------------------------------------------------------
+  // Enumeration (desktop-query)
+  // -------------------------------------------------------------------------
+  /** Probes displays/workspaces. Degrades gracefully — missing tools yield
+   *  empty/unknown values, never throws (web always gets an answer). */
+  async queryInfo() {
+    if (this.platform === "darwin") {
+      const displays = await this.listScreensMac().catch(() => []);
+      return {
+        displays,
+        workspaces: null,
+        currentWorkspace: null,
+        canPickDisplay: displays.length > 1,
+        cropMode: "client"
+      };
+    }
+    if (this.platform === "linux") {
+      const [heads, ws] = await Promise.all([
+        this.listHeads().catch(() => []),
+        this.workspaceState().catch(() => null)
+      ]);
+      return {
+        displays: heads.map((h) => ({ name: h.name, width: h.w, height: h.h, x: h.x, y: h.y })),
+        workspaces: ws?.count ?? null,
+        currentWorkspace: ws?.current ?? null,
+        canPickDisplay: heads.length > 0,
+        cropMode: "server"
+      };
+    }
+    return { displays: [], workspaces: null, currentWorkspace: null, canPickDisplay: false, cropMode: "client" };
+  }
+  /** macOS: NSScreen frames via JXA (osascript -l JavaScript + AppKit).
+   *  AppKit origins are bottom-left → converted to CG top-left coords to
+   *  match the RFB framebuffer. Warm run ~1.5s; any failure → empty list. */
+  async listScreensMac() {
+    const script = [
+      'ObjC.import("AppKit")',
+      "const screens = $.NSScreen.screens",
+      "let gb = 0",
+      "for (let i = 0; i < screens.count; i++) {",
+      "  const f = screens.objectAtIndex(i).frame",
+      "  gb = Math.max(gb, f.origin.y + f.size.height)",
+      "}",
+      "const out = []",
+      "for (let i = 0; i < screens.count; i++) {",
+      "  const s = screens.objectAtIndex(i)",
+      "  const f = s.frame",
+      '  out.push([Math.round(f.origin.x), Math.round(gb - f.origin.y - f.size.height), Math.round(f.size.width), Math.round(f.size.height), s.localizedName.js].join("|"))',
+      "}",
+      'out.join("\n")'
+    ].join("\n");
+    const out = await this.exec("osascript", ["-l", "JavaScript", "-e", script], 8e3);
+    const displays = [];
+    for (const line of out.split("\n").filter((l) => l.trim())) {
+      const [x, y, w, h, ...rest] = line.split("|");
+      if (x === void 0 || w === void 0 || rest.length === 0) continue;
+      displays.push({
+        name: rest.join("|"),
+        x: Number(x),
+        y: Number(y),
+        width: Number(w),
+        height: Number(h)
+      });
+    }
+    return displays;
+  }
+  /** `xrandr --query` connected heads (name + geometry). */
+  async listHeads() {
+    const out = await this.exec("xrandr", ["--query"]);
+    const heads = [];
+    for (const line of out.split("\n")) {
+      const m = /^(\S+) connected (?:primary )?(\d+)x(\d+)\+(\d+)\+(\d+)\s/.exec(line);
+      if (m) heads.push({ name: m[1], w: Number(m[2]), h: Number(m[3]), x: Number(m[4]), y: Number(m[5]) });
+    }
+    return heads;
+  }
+  /** `wmctrl -d` → { count, current }. The current line carries ` * `. */
+  async workspaceState() {
+    const out = await this.exec("wmctrl", ["-d"]);
+    const lines = out.split("\n").filter((l) => l.trim());
+    if (lines.length === 0) return null;
+    const current = lines.findIndex((l) => /(^|\s)\*(\s|$)/.test(l));
+    return { count: lines.length, current: current >= 0 ? current : 0 };
+  }
+  // -------------------------------------------------------------------------
+  // Session lifecycle
+  // -------------------------------------------------------------------------
+  async spawn(sessionId, opts = {}) {
+    if (this.sessions.has(sessionId)) {
+      throw new Error(`session ${sessionId} already exists`);
+    }
+    const { vncHost: host, vncPort: port } = this.config;
+    if (opts.workspace !== void 0 && this.platform !== "linux") {
+      throw new Error("workspace selection is not supported on this platform (session-internal prev/next still works on macOS)");
+    }
+    if (opts.workspace !== void 0) {
+      await this.switchWorkspaceAbsolute(opts.workspace);
+      this.hooks.log(`desktop ${sessionId}: workspace \u2192 ${opts.workspace}`);
+    }
+    let tcp = await probeConnect(host, port, 750);
+    let ownChild = null;
+    let clip;
+    if (opts.display !== void 0 && this.platform === "linux") {
+      const heads = await this.listHeads().catch(() => []);
+      clip = heads[opts.display];
+      if (!clip) {
+        throw new Error(`display ${opts.display} not found (${heads.length} connected)`);
+      }
+    }
+    if (!tcp && this.platform === "linux") {
+      const x11vnc = await this.startX11vnc(port, clip);
+      ownChild = x11vnc;
+      tcp = await probeConnect(host, port, X11VNC_START_TIMEOUT_MS);
+      if (!tcp) {
+        try {
+          x11vnc?.kill("SIGTERM");
+        } catch {
+        }
+        throw new Error(
+          `no VNC server on ${host}:${port} and x11vnc did not come up (is a desktop/X11 session running?)`
+        );
+      }
+      if (x11vnc) {
+        x11vnc.once("exit", () => {
+          const s = this.sessions.get(sessionId);
+          if (s && s.x11vnc === x11vnc) this.end(sessionId, 1, "x11vnc exited");
+        });
+      }
+      this.hooks.log(
+        `desktop ${sessionId}: started x11vnc on ${host}:${port}` + (clip ? ` clipped to ${clip.w}x${clip.h}+${clip.x}+${clip.y}` : "") + ` (display ${this.config.display}, loopback only)`
+      );
+    }
+    if (!tcp) {
+      throw new Error(
+        this.platform === "darwin" ? `no VNC server on ${host}:${port} \u2014 enable \u300C\u5C4F\u5E55\u5171\u4EAB\u300Din macOS System Settings, or set desktop.vncHost/vncPort` : `no VNC server on ${host}:${port} (auto-start is only supported on Linux X11)`
+      );
+    }
+    if (clip && !ownChild) {
+      throw new Error("external VNC server on the port cannot serve a chosen display (stop it, or spawn with the default display)");
+    }
+    const session = {
+      id: sessionId,
+      tcp,
+      startedAt: Date.now(),
+      paused: false,
+      externalServer: !ownChild,
+      ...ownChild ? { x11vnc: ownChild } : {},
+      ...clip ? { clip: { w: clip.w, h: clip.h, x: clip.x, y: clip.y } } : {}
+    };
+    this.sessions.set(sessionId, session);
+    this.wireSocket(session, tcp);
+  }
+  async startX11vnc(port, clip) {
+    if (this.platform !== "linux") return null;
+    try {
+      const args = ["-display", this.config.display, "-localhost", "-nopw", "-quiet", "-rfbport", String(port)];
+      if (clip) args.push("-clip", `${clip.w}x${clip.h}+${clip.x}+${clip.y}`);
+      return this.spawnChildFn("x11vnc", args);
+    } catch {
+      return null;
+    }
+  }
+  /** Attach data/backpressure/close handlers to a session's TCP socket. */
+  wireSocket(session, tcp) {
+    session.tcp = tcp;
+    tcp.setNoDelay(true);
+    tcp.on("data", (buf) => {
+      this.hooks.send(session.id, new Uint8Array(buf));
+      if (!session.paused && this.hooks.congested()) {
+        session.paused = true;
+        tcp.pause();
+        session.pauseTimer = setInterval(() => {
+          if (!this.hooks.congested()) {
+            session.paused = false;
+            if (session.pauseTimer) clearInterval(session.pauseTimer);
+            session.pauseTimer = void 0;
+            try {
+              tcp.resume();
+            } catch {
+            }
+          }
+        }, PAUSE_POLL_MS);
+      }
+    });
+    tcp.on("error", (err) => {
+      this.hooks.log(`desktop ${session.id}: tcp error ${err.message}`);
+      this.end(session.id, 1, "tcp error");
+    });
+    tcp.on("close", () => {
+      const s = this.sessions.get(session.id);
+      if (s) this.end(session.id, 0, "vnc closed");
+    });
+  }
+  /** VNC client bytes (RFB) from the web side → the local VNC server. */
+  write(sessionId, data) {
+    const s = this.sessions.get(sessionId);
+    if (!s) throw new Error(`desktop session ${sessionId} not found`);
+    s.tcp.write(data);
+  }
+  has(sessionId) {
+    return this.sessions.has(sessionId);
+  }
+  list() {
+    return [...this.sessions.values()].map((s) => ({ sessionId: s.id, startedAt: s.startedAt }));
+  }
+  kill(sessionId) {
+    const s = this.sessions.get(sessionId);
+    if (s) this.end(sessionId, 0, "killed");
+  }
+  /** Called whenever the upstream transport dies or the process exits —
+   *  a desktop session must NEVER outlive the tunnel (design §2 #8). */
+  killAll() {
+    for (const id of [...this.sessions.keys()]) {
+      this.kill(id);
+    }
+  }
+  end(sessionId, code, why) {
+    const s = this.sessions.get(sessionId);
+    if (!s) return;
+    this.sessions.delete(sessionId);
+    if (s.pauseTimer) clearInterval(s.pauseTimer);
+    try {
+      s.tcp.destroy();
+    } catch {
+    }
+    if (s.x11vnc) {
+      try {
+        s.x11vnc.kill("SIGTERM");
+      } catch {
+      }
+    }
+    this.hooks.log(`desktop ${sessionId} ended (${why})`);
+    this.hooks.onExit(sessionId, code);
+  }
+  // -------------------------------------------------------------------------
+  // Live switching (desktop-switch)
+  // -------------------------------------------------------------------------
+  /** Returns an error reason on failure, undefined on success. */
+  async switch(sessionId, opts) {
+    const s = this.sessions.get(sessionId);
+    if (!s) return `desktop session ${sessionId} not found`;
+    if (opts.display !== void 0) {
+      const err = await this.switchDisplay(s, opts.display);
+      if (err) return err;
+    }
+    if (opts.workspaceDelta !== void 0) {
+      const err = await this.switchWorkspaceDelta(opts.workspaceDelta);
+      if (err) return err;
+    } else if (opts.workspace !== void 0) {
+      const err = await this.switchWorkspaceAbsolute(opts.workspace);
+      if (err) return err;
+    }
+    return void 0;
+  }
+  /** Linux: respawn OUR x11vnc with a new -clip and swap the TCP socket.
+   *  The RFB handshake restarts on the web side (viewer re-attaches). */
+  async switchDisplay(s, display) {
+    if (this.platform === "darwin") {
+      return "display switching is client-side on this platform (web viewport crop)";
+    }
+    if (this.platform !== "linux") return "display switching is not supported on this platform";
+    if (s.externalServer || !s.x11vnc) {
+      return "cannot switch displays on an external VNC server (only locally started x11vnc)";
+    }
+    const heads = await this.listHeads().catch(() => []);
+    const head = heads[display];
+    if (!head) return `display ${display} not found (${heads.length} connected)`;
+    const { vncHost: host, vncPort: port } = this.config;
+    try {
+      s.tcp.removeAllListeners();
+      s.tcp.destroy();
+    } catch {
+    }
+    try {
+      s.x11vnc.kill("SIGTERM");
+    } catch {
+    }
+    const child = await this.startX11vnc(port, head);
+    const tcp = await probeConnect(host, port, X11VNC_START_TIMEOUT_MS);
+    if (!tcp) {
+      this.end(s.id, 1, "x11vnc restart failed during display switch");
+      return "x11vnc did not come back up";
+    }
+    if (child) {
+      child.once("exit", () => {
+        const cur = this.sessions.get(s.id);
+        if (cur && cur.x11vnc === child) this.end(s.id, 1, "x11vnc exited");
+      });
+    }
+    s.x11vnc = child ?? void 0;
+    s.clip = { w: head.w, h: head.h, x: head.x, y: head.y };
+    this.wireSocket(s, tcp);
+    this.hooks.log(`desktop ${s.id}: display \u2192 ${display} (${head.name} ${head.w}x${head.h}+${head.x}+${head.y})`);
+    return void 0;
+  }
+  async switchWorkspaceAbsolute(n) {
+    if (this.platform !== "linux") return "absolute workspace switching is not supported on this platform";
+    try {
+      await this.exec("wmctrl", ["-s", String(n)]);
+      return void 0;
+    } catch {
+      return `wmctrl -s ${n} failed (is wmctrl installed? does workspace ${n} exist?)`;
+    }
+  }
+  async switchWorkspaceDelta(delta) {
+    if (this.platform === "linux") {
+      const ws = await this.workspaceState().catch(() => null);
+      if (!ws) return "cannot read current workspace (wmctrl missing?)";
+      const target = ws.current + delta;
+      if (target < 0 || target >= ws.count) return `no workspace ${target < 0 ? "before" : "after"} the current one`;
+      return this.switchWorkspaceAbsolute(target);
+    }
+    if (this.platform === "darwin") {
+      const keyCode = delta === 1 ? 124 : 123;
+      try {
+        await this.exec(
+          "osascript",
+          ["-e", `tell application "System Events" to key code ${keyCode} using control down`],
+          8e3
+        );
+        return void 0;
+      } catch {
+        return "System Events keystroke failed (grant Accessibility permission to the app running cli-local, or switch Spaces manually)";
+      }
+    }
+    return "workspace switching is not supported on this platform";
+  }
+};
+function probeConnect(host, port, timeoutMs) {
+  return new Promise((resolve2) => {
+    const sock = import_node_net.default.connect({ host, port });
+    let settled = false;
+    const done = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (result === null) {
+        sock.destroy();
+      }
+      resolve2(result);
+    };
+    const timer = setTimeout(() => done(null), timeoutMs);
+    sock.once("connect", () => done(sock));
+    sock.once("error", () => done(null));
+  });
+}
+
+// src/config.ts
+function resolveDesktopConfig(cfg) {
+  return {
+    enabled: cfg?.enabled === true,
+    display: cfg?.display ?? ":0",
+    vncHost: cfg?.vncHost ?? "127.0.0.1",
+    vncPort: cfg?.vncPort ?? 5900
+  };
+}
+
 // src/gateway-api.ts
 var import_node_http = require("node:http");
 var import_node_fs3 = require("node:fs");
@@ -10606,7 +11004,7 @@ function startSetupCallback(timeoutMs = 3 * 6e4) {
 }
 
 // src/auth.ts
-var import_node_child_process2 = require("node:child_process");
+var import_node_child_process3 = require("node:child_process");
 var import_node_crypto3 = require("node:crypto");
 var import_promises3 = require("node:fs/promises");
 var import_node_os6 = require("node:os");
@@ -10614,13 +11012,13 @@ var import_node_path6 = require("node:path");
 var import_qrcode = __toESM(require_lib(), 1);
 
 // src/machine-id.ts
-var import_node_child_process = require("node:child_process");
+var import_node_child_process2 = require("node:child_process");
 var import_node_crypto2 = require("node:crypto");
 var import_promises2 = require("node:fs/promises");
 var import_node_os5 = require("node:os");
 var import_node_path5 = require("node:path");
-var import_node_util = require("node:util");
-var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.execFile);
+var import_node_util2 = require("node:util");
+var execFileAsync = (0, import_node_util2.promisify)(import_node_child_process2.execFile);
 var MACHINE_ID_DOMAIN = "cli-remote.machineid.v1";
 function normalizeHardwareId(raw) {
   return raw.trim().toLowerCase().replace(/\s+/g, " ");
@@ -10785,7 +11183,7 @@ function openBrowser(url) {
   const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
   const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
   try {
-    const child = (0, import_node_child_process2.spawn)(cmd, args, { stdio: "ignore", detached: true });
+    const child = (0, import_node_child_process3.spawn)(cmd, args, { stdio: "ignore", detached: true });
     child.unref();
   } catch {
   }
@@ -10797,7 +11195,14 @@ async function loginAndFetchRegistrationKey(baseUrl, email, password) {
     throw new AuthError(`\u767B\u5F55\u5931\u8D25: ${reason ?? login.status}`);
   }
   const token = login.data.token;
-  if (!token) throw new AuthError("\u670D\u52A1\u7AEF\u672A\u8FD4\u56DE\u4F1A\u8BDD token");
+  if (!token) {
+    if (login.data?.totpRequired) {
+      throw new AuthError(
+        "\u8BE5\u8D26\u53F7\u5DF2\u5F00\u542F\u4E24\u6B65\u9A8C\u8BC1\uFF0C\u8D26\u53F7\u5BC6\u7801\u65B9\u5F0F\u4E0D\u53EF\u7528\u3002\u8BF7\u6539\u7528\uFF1A\u2460\u201C\u901A\u8FC7\u7F51\u9875\u767B\u5F55\u83B7\u53D6\u201D\uFF08\u63A8\u8350\uFF09\u6216 \u2461\u624B\u52A8\u7C98\u8D34 registrationKey"
+      );
+    }
+    throw new AuthError("\u670D\u52A1\u7AEF\u672A\u8FD4\u56DE\u4F1A\u8BDD token");
+  }
   const me = await fetch(`${baseUrl}/api/me`, {
     headers: { authorization: `Bearer ${token}` }
   });
@@ -10975,7 +11380,7 @@ function applyConfigDeprecations(cfg) {
 function isTTY() {
   return process.stdin.isTTY === true;
 }
-function detectCommands() {
+function detectCommands(desktopEnabled) {
   const bins = [
     ["claude", "claude"],
     ["codex", "codex"],
@@ -10986,15 +11391,16 @@ function detectCommands() {
   for (const [cmd, bin] of bins) {
     let ok = false;
     if (process.platform === "win32") {
-      ok = (0, import_node_child_process3.spawnSync)("where", [bin], { timeout: 5e3 }).status === 0;
+      ok = (0, import_node_child_process4.spawnSync)("where", [bin], { timeout: 5e3 }).status === 0;
     } else {
       const shell = process.env.SHELL ?? "/bin/bash";
-      ok = (0, import_node_child_process3.spawnSync)(shell, ["-l", "-c", `command -v ${bin}`], {
+      ok = (0, import_node_child_process4.spawnSync)(shell, ["-l", "-c", `command -v ${bin}`], {
         timeout: 5e3
       }).status === 0;
     }
     if (ok) found.push(cmd);
   }
+  if (desktopEnabled) found.push("desktop");
   return found;
 }
 async function readInput(prompt) {
@@ -11120,6 +11526,20 @@ async function startLocal(opts = {}) {
     (data) => safeSend(data),
     (msg) => console.log(`[local] ${msg}`)
   );
+  const desktops = new DesktopManager(
+    {
+      send: (sessionId, data) => safeSend(encodeFrame({ t: "desktop-data", sessionId, data })),
+      congested: () => ws ? ws.bufferedAmount > 4 * 1024 * 1024 : false,
+      onExit: (sessionId, code) => {
+        const logger = loggers.get(sessionId);
+        logger?.logExit(code);
+        loggers.delete(sessionId);
+        safeSend(encodeFrame({ t: "exit", sessionId, code }));
+      },
+      log: (msg) => console.log(`[local] ${msg}`)
+    },
+    resolveDesktopConfig(config.desktop)
+  );
   const other = acquireSingleInstanceLock();
   if (other !== null) {
     console.error(`[local] \u53E6\u4E00\u4E2A cli-local \u6B63\u5728\u8FD0\u884C (pid ${other})\uFF0C\u62D2\u7EDD\u53CC\u5F00\u3002`);
@@ -11153,7 +11573,7 @@ async function startLocal(opts = {}) {
   } else {
     credentials = await ensureCredentials(baseUrl, registrationKey);
   }
-  const commands = detectCommands();
+  const commands = detectCommands(desktops.unsupportedReason() === null);
   console.log(`[local] connecting to ${url}`);
   console.log(`[local] deviceId=${credentials.deviceId || "(\u672A\u6388\u6743)"}`);
   console.log(`[local] bash: passthrough (audit: ${auditMode}, retention: ${retentionDays === 0 ? "forever" : retentionDays + "d"}${dangerConfirm ? ", dangerConfirm: on" : ""})`);
@@ -11176,11 +11596,18 @@ async function startLocal(opts = {}) {
     uptimeMs: Date.now() - startedAt,
     reconnectAttempts,
     accessTokenExpiresAt: credentials.accessTokenExpiresAt || null,
-    sessions: pty.list().map((s) => ({
-      sessionId: s.id,
-      cmd: s.cmd,
-      startedAt: s.startedAt
-    }))
+    sessions: [
+      ...pty.list().map((s) => ({
+        sessionId: s.id,
+        cmd: s.cmd,
+        startedAt: s.startedAt
+      })),
+      ...desktops.list().map((d) => ({
+        sessionId: d.sessionId,
+        cmd: "desktop",
+        startedAt: d.startedAt
+      }))
+    ]
   });
   function setPhase(p, reason = "") {
     phase = p;
@@ -11231,6 +11658,10 @@ async function startLocal(opts = {}) {
         exitProcess(0);
       },
       killSession: (id) => {
+        if (desktops.has(id)) {
+          desktops.kill(id);
+          return true;
+        }
         try {
           pty.kill(id);
           return true;
@@ -11283,6 +11714,7 @@ async function startLocal(opts = {}) {
         process.exit(userExitCode);
       }
       console.log("[local] disconnected; PTY sessions kept alive, reconnecting\u2026");
+      desktops.killAll();
       if (phase !== "needs-pairing") setPhase("reconnecting");
       scheduleReconnect();
     });
@@ -11321,6 +11753,7 @@ async function startLocal(opts = {}) {
     controlApi?.close();
     if (opts.daemon) removeGatewayPid();
     transfers.abortAll();
+    desktops.killAll();
     pty.killAll();
     for (const [, logger] of loggers) logger.logExit(-1);
     loggers.clear();
@@ -11359,9 +11792,22 @@ async function startLocal(opts = {}) {
       case "spawn":
         handleSpawn(frame);
         break;
+      case "desktop-query":
+        handleDesktopQuery(frame);
+        break;
+      case "desktop-switch":
+        void handleDesktopSwitch(frame);
+        break;
       case "input":
         handleInput(frame);
         break;
+      case "desktop-data":
+        try {
+          desktops.write(frame.sessionId, frame.data);
+        } catch (e) {
+          console.error("[local] desktop write error:", e.message);
+        }
+        break;
       case "resize":
         pty.resize(frame.sessionId, frame.cols, frame.rows);
         break;
@@ -11414,6 +11860,13 @@ async function startLocal(opts = {}) {
   }
   function handleSpawn(frame) {
     const sessionId = frame.sessionId;
+    if (frame.cmd === "desktop") {
+      void handleDesktopSpawn(sessionId, {
+        ...frame.desktopDisplay !== void 0 ? { display: frame.desktopDisplay } : {},
+        ...frame.desktopWorkspace !== void 0 ? { workspace: frame.desktopWorkspace } : {}
+      });
+      return;
+    }
     try {
       const logger = new SessionLogger(sessionId, frame.cmd, auditMode);
       pty.spawn(
@@ -11461,6 +11914,64 @@ async function startLocal(opts = {}) {
       console.error(`[local] spawn failed for ${sessionId}:`, reason);
     }
   }
+  async function handleDesktopSpawn(sessionId, opts2 = {}) {
+    const unsupported = desktops.unsupportedReason();
+    if (unsupported) {
+      safeSend(encodeFrame({ t: "spawn-err", sessionId, reason: unsupported }));
+      return;
+    }
+    const logger = new SessionLogger(sessionId, "desktop", auditMode);
+    try {
+      await desktops.spawn(sessionId, opts2);
+      loggers.set(sessionId, logger);
+      safeSend(encodeFrame({ t: "spawn-ok", sessionId }));
+      console.log(`[local] desktop session ${sessionId} bridged to VNC`);
+    } catch (e) {
+      logger.logExit(1);
+      const reason = e instanceof Error ? e.message : String(e);
+      safeSend(encodeFrame({ t: "spawn-err", sessionId, reason }));
+      console.error(`[local] desktop spawn failed for ${sessionId}:`, reason);
+    }
+  }
+  function handleDesktopQuery(frame) {
+    desktops.queryInfo().then((info) => {
+      safeSend(encodeFrame({ t: "desktop-info", sessionId: frame.sessionId, ...info }));
+    }).catch(() => {
+      safeSend(
+        encodeFrame({
+          t: "desktop-info",
+          sessionId: frame.sessionId,
+          displays: [],
+          workspaces: null,
+          currentWorkspace: null,
+          canPickDisplay: false,
+          cropMode: "client"
+        })
+      );
+    });
+  }
+  async function handleDesktopSwitch(frame) {
+    const logger = loggers.get(frame.sessionId);
+    const reason = await desktops.switch(frame.sessionId, {
+      ...frame.display !== void 0 ? { display: frame.display } : {},
+      ...frame.workspace !== void 0 ? { workspace: frame.workspace } : {},
+      ...frame.workspaceDelta !== void 0 ? { workspaceDelta: frame.workspaceDelta } : {}
+    }).catch((e) => e instanceof Error ? e.message : String(e));
+    if (reason === void 0) {
+      if (frame.display !== void 0) logger?.logSwitch("display", String(frame.display));
+      if (frame.workspace !== void 0) logger?.logSwitch("workspace", String(frame.workspace));
+      if (frame.workspaceDelta !== void 0)
+        logger?.logSwitch("workspace", frame.workspaceDelta === 1 ? "next" : "prev");
+    }
+    safeSend(
+      encodeFrame({
+        t: "desktop-switch-res",
+        sessionId: frame.sessionId,
+        ok: reason === void 0,
+        ...reason !== void 0 ? { reason } : {}
+      })
+    );
+  }
   function handleInput(frame) {
     const sessionId = frame.sessionId;
     const logger = loggers.get(sessionId);
@@ -11535,10 +12046,25 @@ async function startLocal(opts = {}) {
     }
   }
   function handleKill(sessionId) {
+    if (desktops.has(sessionId)) {
+      desktops.kill(sessionId);
+      return;
+    }
     pty.kill(sessionId);
     lineBuffers.delete(sessionId);
   }
   function handleReplay(frame) {
+    if (desktops.has(frame.sessionId)) {
+      safeSend(
+        encodeFrame({
+          t: "replay-res",
+          sessionId: frame.sessionId,
+          frames: [],
+          exists: true
+        })
+      );
+      return;
+    }
     const frames = pty.replay(frame.sessionId, frame.fromSeq);
     safeSend(
       encodeFrame({
@@ -11698,7 +12224,7 @@ function resolveHere() {
 var argUrl = process.argv[2];
 var argMatch = argUrl && (argUrl.startsWith("ws://") || argUrl.startsWith("wss://"));
 function readVersion() {
-  if (true) return "0.3.4";
+  if (true) return "0.4.1";
   try {
     const pkg = JSON.parse(
       (0, import_node_fs5.readFileSync)(new URL("../package.json", import_meta.url), "utf-8")
@@ -11771,7 +12297,7 @@ function entryScript() {
 }
 function run(cmd, args, okToFail = false) {
   try {
-    return (0, import_node_child_process4.execFileSync)(cmd, args, { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
+    return (0, import_node_child_process5.execFileSync)(cmd, args, { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
   } catch (e) {
     if (okToFail) return null;
     throw e;
@@ -11972,7 +12498,7 @@ if (argUrl === "gateway") {
     for (const [k, v] of Object.entries(process.env)) if (v !== void 0) env[k] = v;
     const args = [entry, "gateway", "run"];
     if (hubArg) args.push("--hub", hubArg);
-    const child = (0, import_node_child_process4.spawn)(process.execPath, args, {
+    const child = (0, import_node_child_process5.spawn)(process.execPath, args, {
       detached: true,
       stdio: ["ignore", out, out],
       env

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cli-remote/local",
-  "version": "0.3.4",
+  "version": "0.4.1",
   "description": "Local PTY agent for cli-remote — exposes your local CLI tools (claude/codex/kimi-cli/shell) to the mobile web client via a self-hosted hub.",
   "license": "MIT",
   "repository": {