tensorlake 0.4.42 → 0.4.45

package/dist/index.cjs

@@ -33,6 +33,7 @@ __export(index_exports, {
   APIClient: () => APIClient,
   CloudClient: () => CloudClient,
   ContainerState: () => ContainerState,
+  Desktop: () => Desktop,
   Image: () => Image,
   ImageBuildOperationType: () => ImageBuildOperationType,
   OutputMode: () => OutputMode,
@@ -53,6 +54,7 @@ __export(index_exports, {
   SandboxStatus: () => SandboxStatus,
   SnapshotStatus: () => SnapshotStatus,
   StdinMode: () => StdinMode,
+  TcpTunnel: () => TcpTunnel,
   createSandboxImage: () => createSandboxImage,
   dockerfileContent: () => dockerfileContent
 });
@@ -431,6 +433,2395 @@ function fromSnakeKeys(obj, idField) {
   return obj;
 }
 
+// src/desktop.ts
+var import_node_zlib = require("zlib");
+
+// src/tunnel.ts
+var net = __toESM(require("net"), 1);
+var import_ws = __toESM(require("ws"), 1);
+var DEFAULT_TUNNEL_CONNECT_TIMEOUT_MS = 1e4;
+var WEBSOCKET_KEEPALIVE_INTERVAL_MS = 15e3;
+async function openTunnelWebSocket(options) {
+  const wsUrl = buildTunnelWsUrl(options.baseUrl, options.remotePort);
+  const timeoutMs = options.connectTimeoutMs ?? DEFAULT_TUNNEL_CONNECT_TIMEOUT_MS;
+  return new Promise((resolve, reject) => {
+    const socket = new import_ws.default(wsUrl, {
+      headers: options.wsHeaders
+    });
+    let settled = false;
+    const timer = setTimeout(() => {
+      fail(
+        new SandboxError(
+          `timed out while connecting tunnel websocket after ${(timeoutMs / 1e3).toFixed(2)}s`
+        )
+      );
+    }, timeoutMs);
+    const cleanup = () => {
+      clearTimeout(timer);
+      socket.removeListener("open", onOpen);
+      socket.removeListener("error", onError);
+      socket.removeListener("close", onCloseBeforeOpen);
+      socket.removeListener("unexpected-response", onUnexpectedResponse);
+    };
+    const settle = (callback) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      callback();
+    };
+    const fail = (error) => {
+      settle(() => {
+        reject(error);
+      });
+    };
+    const onOpen = () => {
+      settle(() => resolve(socket));
+    };
+    const onError = (error) => {
+      fail(new SandboxConnectionError(error.message));
+    };
+    const onCloseBeforeOpen = (code, reason) => {
+      const closeReason = reason.length > 0 ? reason.toString("utf8") : "no reason";
+      fail(
+        new SandboxError(
+          `tunnel websocket closed before opening: ${code} ${closeReason}`
+        )
+      );
+    };
+    const onUnexpectedResponse = (_request, response) => {
+      const status = response.statusCode ?? 0;
+      const statusMessage = response.statusMessage?.trim();
+      fail(
+        new SandboxError(
+          `tunnel websocket handshake failed with HTTP ${status}${statusMessage ? ` ${statusMessage}` : ""}`
+        )
+      );
+    };
+    socket.on("open", onOpen);
+    socket.on("error", onError);
+    socket.on("close", onCloseBeforeOpen);
+    socket.on("unexpected-response", onUnexpectedResponse);
+  });
+}
+var TunnelByteStream = class _TunnelByteStream {
+  socket;
+  readBuffer = Buffer.alloc(0);
+  pendingReads = [];
+  closeError = null;
+  closePromise = null;
+  keepAliveInterval;
+  constructor(socket) {
+    this.socket = socket;
+    this.keepAliveInterval = setInterval(() => {
+      if (socket.readyState === import_ws.default.OPEN) {
+        socket.ping();
+      }
+    }, WEBSOCKET_KEEPALIVE_INTERVAL_MS);
+    this.keepAliveInterval.unref?.();
+    socket.on("message", (message, isBinary) => {
+      if (!isBinary) {
+        this.fail(
+          new SandboxError("desktop tunnel received unexpected text frame")
+        );
+        return;
+      }
+      this.pushBytes(normalizeWebSocketData(message));
+    });
+    socket.on("ping", (data) => {
+      if (socket.readyState === import_ws.default.OPEN) {
+        socket.pong(data, false, () => {
+        });
+      }
+    });
+    socket.on("close", (_code, reason) => {
+      clearInterval(this.keepAliveInterval);
+      const closeReason = reason.length > 0 ? reason.toString("utf8") : "desktop tunnel closed unexpectedly";
+      this.fail(new SandboxError(closeReason));
+    });
+    socket.on("error", (error) => {
+      clearInterval(this.keepAliveInterval);
+      this.fail(new SandboxConnectionError(error.message));
+    });
+  }
+  static async connect(options) {
+    const socket = await openTunnelWebSocket(options);
+    return new _TunnelByteStream(socket);
+  }
+  async readExactly(length) {
+    if (length < 0) {
+      throw new SandboxError(`read length must be >= 0, got ${length}`);
+    }
+    if (length === 0) {
+      return Buffer.alloc(0);
+    }
+    if (this.readBuffer.length >= length) {
+      const chunk = this.readBuffer.subarray(0, length);
+      this.readBuffer = this.readBuffer.subarray(length);
+      return chunk;
+    }
+    if (this.closeError) {
+      throw this.closeError;
+    }
+    return new Promise((resolve, reject) => {
+      this.pendingReads.push({ length, resolve, reject });
+    });
+  }
+  async writeAll(data) {
+    if (this.closeError) {
+      throw this.closeError;
+    }
+    if (this.socket.readyState !== import_ws.default.OPEN) {
+      throw new SandboxError("desktop tunnel is not connected");
+    }
+    const payload = Buffer.from(data);
+    await new Promise((resolve, reject) => {
+      this.socket.send(payload, { binary: true }, (error) => {
+        if (error) {
+          reject(new SandboxConnectionError(error.message));
+          return;
+        }
+        resolve();
+      });
+    });
+  }
+  async close() {
+    if (this.closePromise) {
+      return this.closePromise;
+    }
+    if (this.socket.readyState === import_ws.default.CLOSED || this.socket.readyState === import_ws.default.CLOSING) {
+      this.closePromise = Promise.resolve();
+      return this.closePromise;
+    }
+    this.closePromise = new Promise((resolve) => {
+      const onClose = () => {
+        this.socket.removeListener("close", onClose);
+        resolve();
+      };
+      this.socket.on("close", onClose);
+      this.socket.close();
+    });
+    return this.closePromise;
+  }
+  pushBytes(chunk) {
+    this.readBuffer = this.readBuffer.length === 0 ? chunk : Buffer.from(Buffer.concat([this.readBuffer, chunk]));
+    this.flushPendingReads();
+  }
+  flushPendingReads() {
+    while (this.pendingReads.length > 0) {
+      const next = this.pendingReads[0];
+      if (this.readBuffer.length < next.length) {
+        break;
+      }
+      const chunk = this.readBuffer.subarray(0, next.length);
+      this.readBuffer = this.readBuffer.subarray(next.length);
+      this.pendingReads.shift();
+      next.resolve(chunk);
+    }
+  }
+  fail(error) {
+    if (this.closeError) {
+      return;
+    }
+    this.closeError = error;
+    while (this.pendingReads.length > 0) {
+      const pending = this.pendingReads.shift();
+      pending?.reject(error);
+    }
+  }
+};
+var TcpTunnel = class _TcpTunnel {
+  remotePort;
+  localHost;
+  localPort;
+  baseUrl;
+  wsHeaders;
+  server;
+  connectTimeoutMs;
+  activeRelays = /* @__PURE__ */ new Set();
+  closePromise = null;
+  constructor(options) {
+    this.baseUrl = options.baseUrl;
+    this.wsHeaders = options.wsHeaders;
+    this.remotePort = options.remotePort;
+    this.localHost = options.localHost;
+    this.localPort = options.localPort;
+    this.server = options.server;
+    this.connectTimeoutMs = options.connectTimeoutMs;
+  }
+  static async listen(options) {
+    const remotePort = validatePort(options.remotePort, "remote port");
+    const localHost = options.localHost ?? "127.0.0.1";
+    const localPort = validatePort(
+      options.localPort ?? remotePort,
+      "local port",
+      true
+    );
+    const connectTimeoutMs = secondsToMillis(options.connectTimeout ?? 10);
+    const server = net.createServer();
+    await listenServer(server, localPort, localHost);
+    const address = server.address();
+    if (!address || typeof address === "string") {
+      server.close();
+      throw new SandboxError("failed to determine bound tunnel address");
+    }
+    const tunnel = new _TcpTunnel({
+      baseUrl: options.baseUrl,
+      wsHeaders: options.wsHeaders,
+      remotePort,
+      localHost,
+      localPort: address.port,
+      server,
+      connectTimeoutMs
+    });
+    server.on("connection", (localSocket) => {
+      void tunnel.handleConnection(localSocket);
+    });
+    return tunnel;
+  }
+  address() {
+    return { host: this.localHost, port: this.localPort };
+  }
+  async close() {
+    if (this.closePromise) {
+      return this.closePromise;
+    }
+    for (const relay of this.activeRelays) {
+      relay.localSocket.destroy();
+      relay.websocket?.close();
+    }
+    this.closePromise = new Promise((resolve, reject) => {
+      this.server.close((error) => {
+        if (error) {
+          reject(new SandboxError(`failed to close tunnel listener: ${error.message}`));
+          return;
+        }
+        resolve();
+      });
+    });
+    return this.closePromise;
+  }
+  async handleConnection(localSocket) {
+    localSocket.setNoDelay(true);
+    const relay = { localSocket, websocket: null };
+    this.activeRelays.add(relay);
+    try {
+      relay.websocket = await openTunnelWebSocket({
+        baseUrl: this.baseUrl,
+        wsHeaders: this.wsHeaders,
+        remotePort: this.remotePort,
+        connectTimeoutMs: this.connectTimeoutMs
+      });
+      await relaySocket(localSocket, relay.websocket);
+    } catch (error) {
+      localSocket.destroy(
+        error instanceof Error ? error : new Error(String(error))
+      );
+    } finally {
+      this.activeRelays.delete(relay);
+    }
+  }
+};
+function buildTunnelWsUrl(baseUrl, remotePort) {
+  const url = new URL(baseUrl);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  url.pathname = "/api/v1/tunnels/tcp";
+  url.search = `port=${encodeURIComponent(String(remotePort))}`;
+  return url.toString();
+}
+function normalizeWebSocketData(message) {
+  if (Buffer.isBuffer(message)) return message;
+  if (Array.isArray(message)) {
+    return Buffer.concat(message.map((part) => Buffer.from(part)));
+  }
+  return Buffer.from(message);
+}
+async function relaySocket(localSocket, websocket) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const keepAliveInterval = setInterval(() => {
+      if (websocket.readyState === import_ws.default.OPEN) {
+        websocket.ping();
+      }
+    }, WEBSOCKET_KEEPALIVE_INTERVAL_MS);
+    keepAliveInterval.unref?.();
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearInterval(keepAliveInterval);
+      cleanup();
+      resolve();
+    };
+    const cleanup = () => {
+      localSocket.removeListener("data", onLocalData);
+      localSocket.removeListener("end", onLocalEnd);
+      localSocket.removeListener("close", onLocalClose);
+      localSocket.removeListener("error", onLocalError);
+      websocket.removeListener("message", onWsMessage);
+      websocket.removeListener("close", onWsClose);
+      websocket.removeListener("error", onWsError);
+      websocket.removeListener("ping", onWsPing);
+    };
+    const onLocalData = (chunk) => {
+      if (websocket.readyState !== import_ws.default.OPEN) {
+        localSocket.destroy();
+        return;
+      }
+      websocket.send(chunk, { binary: true }, (error) => {
+        if (error) {
+          localSocket.destroy(error);
+        }
+      });
+    };
+    const onLocalEnd = () => {
+      if (websocket.readyState === import_ws.default.OPEN) {
+        websocket.close();
+      }
+    };
+    const onLocalClose = () => {
+      if (websocket.readyState === import_ws.default.OPEN || websocket.readyState === import_ws.default.CONNECTING) {
+        websocket.close();
+      }
+      finish();
+    };
+    const onLocalError = () => {
+      websocket.close();
+      finish();
+    };
+    const onWsMessage = (message, isBinary) => {
+      if (!isBinary) {
+        localSocket.destroy(
+          new SandboxError("received unexpected text frame from tunnel")
+        );
+        websocket.close();
+        return;
+      }
+      const payload = normalizeWebSocketData(message);
+      if (!localSocket.destroyed) {
+        localSocket.write(payload);
+      }
+    };
+    const onWsClose = () => {
+      if (!localSocket.destroyed) {
+        localSocket.end();
+      }
+      finish();
+    };
+    const onWsError = (error) => {
+      localSocket.destroy(error);
+      finish();
+    };
+    const onWsPing = (data) => {
+      if (websocket.readyState === import_ws.default.OPEN) {
+        websocket.pong(data, false, () => {
+        });
+      }
+    };
+    localSocket.on("data", onLocalData);
+    localSocket.on("end", onLocalEnd);
+    localSocket.on("close", onLocalClose);
+    localSocket.on("error", onLocalError);
+    websocket.on("message", onWsMessage);
+    websocket.on("close", onWsClose);
+    websocket.on("error", onWsError);
+    websocket.on("ping", onWsPing);
+  });
+}
+async function listenServer(server, localPort, localHost) {
+  await new Promise((resolve, reject) => {
+    const onError = (error) => {
+      server.removeListener("listening", onListening);
+      reject(
+        new SandboxError(
+          `failed to bind local tunnel listener on ${localHost}:${localPort}: ${error.message}`
+        )
+      );
+    };
+    const onListening = () => {
+      server.removeListener("error", onError);
+      resolve();
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(localPort, localHost);
+  });
+}
+function validatePort(port, label, allowZero = false) {
+  if (!Number.isInteger(port)) {
+    throw new SandboxError(`${label} must be an integer, got ${port}`);
+  }
+  if (allowZero && port === 0) {
+    return port;
+  }
+  if (port < 1 || port > 65535) {
+    throw new SandboxError(`${label} must be between 1 and 65535, got ${port}`);
+  }
+  return port;
+}
+function secondsToMillis(seconds) {
+  if (!Number.isFinite(seconds) || seconds < 0) {
+    throw new SandboxError(`timeout must be >= 0 seconds, got ${seconds}`);
+  }
+  return Math.round(seconds * 1e3);
+}
+async function withTimeout(timeoutMs, operation, timeoutMessage) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new SandboxError(timeoutMessage));
+    }, timeoutMs);
+    void operation().then((value) => {
+      clearTimeout(timer);
+      resolve(value);
+    }).catch((error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+  });
+}
+
+// src/desktop.ts
+var SECURITY_TYPE_NONE = 1;
+var SECURITY_TYPE_VNC_AUTH = 2;
+var ENCODING_RAW = 0;
+var ENCODING_DESKTOP_SIZE = -223;
+var BUTTON_LEFT_MASK = 1;
+var BUTTON_MIDDLE_MASK = 1 << 1;
+var BUTTON_RIGHT_MASK = 1 << 2;
+var BUTTON_SCROLL_UP_MASK = 1 << 3;
+var BUTTON_SCROLL_DOWN_MASK = 1 << 4;
+var PNG_SIGNATURE = Buffer.from([
+  137,
+  80,
+  78,
+  71,
+  13,
+  10,
+  26,
+  10
+]);
+var CRC32_TABLE = buildCrc32Table();
+var DesktopSession = class _DesktopSession {
+  transport;
+  width;
+  height;
+  pixelFormat;
+  framebuffer;
+  pointerX = 0;
+  pointerY = 0;
+  buttonMask = 0;
+  framebufferVersion = 0;
+  closed = false;
+  updateLoopError = null;
+  updateSignal = createDeferredSignal();
+  updateLoopPromise = null;
+  constructor(options) {
+    this.transport = options.transport;
+    this.width = options.width;
+    this.height = options.height;
+    this.pixelFormat = options.pixelFormat;
+    this.framebuffer = options.framebuffer;
+  }
+  static async connect(transport, password, shared = true) {
+    const serverVersion = await ProtocolVersion.read(transport);
+    const clientVersion = serverVersion.negotiated();
+    await transport.writeAll(Buffer.from(clientVersion.render(), "ascii"));
+    await negotiateSecurity(transport, clientVersion, password);
+    await transport.writeAll(Uint8Array.of(shared ? 1 : 0));
+    const init = await ServerInit.read(transport);
+    if (!init.pixelFormat.trueColor) {
+      throw new SandboxError(
+        "desktop sessions require a true-color VNC pixel format"
+      );
+    }
+    const pixelFormat = PixelFormat.preferred();
+    await sendSetPixelFormat(transport, pixelFormat);
+    await sendSetEncodings(transport, [ENCODING_RAW, ENCODING_DESKTOP_SIZE]);
+    const session = new _DesktopSession({
+      transport,
+      width: init.width,
+      height: init.height,
+      pixelFormat,
+      framebuffer: allocateFramebuffer(init.width, init.height)
+    });
+    session.startFramebufferUpdates();
+    return session;
+  }
+  async close() {
+    this.closed = true;
+    this.updateSignal.resolve();
+    await this.transport.close();
+    await this.updateLoopPromise;
+  }
+  async screenshot(timeoutSeconds = 5) {
+    await this.waitForFramebufferVersion(
+      1,
+      timeoutSeconds,
+      `timed out waiting for initial desktop framebuffer after ${timeoutSeconds.toFixed(2)}s`
+    );
+    return encodePng(this.width, this.height, this.framebuffer);
+  }
+  getFrameVersion() {
+    return this.framebufferVersion;
+  }
+  async screenshotAfter(frameVersion, timeoutSeconds = 1) {
+    const minimumVersion = validateNonNegativeInteger(frameVersion, "frame version") + 1;
+    if (this.framebufferVersion < minimumVersion) {
+      await this.waitForFramebufferVersion(
+        minimumVersion,
+        timeoutSeconds,
+        `timed out waiting for a fresher desktop framebuffer after ${timeoutSeconds.toFixed(2)}s`
+      );
+    }
+    return encodePng(this.width, this.height, this.framebuffer);
+  }
+  async moveMouse(x, y) {
+    const nextX = validateCoordinate(x, "mouse x coordinate");
+    const nextY = validateCoordinate(y, "mouse y coordinate");
+    this.ensurePointerInBounds(nextX, nextY);
+    this.pointerX = nextX;
+    this.pointerY = nextY;
+    await sendPointerEvent(this.transport, this.buttonMask, nextX, nextY);
+  }
+  async mousePress(options) {
+    const button = options?.button ?? "left";
+    await this.moveIfRequested(options?.x, options?.y);
+    this.buttonMask |= buttonMask(button);
+    await sendPointerEvent(
+      this.transport,
+      this.buttonMask,
+      this.pointerX,
+      this.pointerY
+    );
+  }
+  async mouseRelease(options) {
+    const button = options?.button ?? "left";
+    await this.moveIfRequested(options?.x, options?.y);
+    this.buttonMask &= ~buttonMask(button);
+    await sendPointerEvent(
+      this.transport,
+      this.buttonMask,
+      this.pointerX,
+      this.pointerY
+    );
+  }
+  async click(options) {
+    await this.mousePress(options);
+    await this.mouseRelease({ button: options?.button ?? "left" });
+  }
+  async doubleClick(options) {
+    const button = options?.button ?? "left";
+    const delayMs = options?.delayMs ?? 50;
+    validateNonNegativeInteger(delayMs, "double click delay");
+    await this.click({ button, x: options?.x, y: options?.y });
+    if (delayMs > 0) {
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+    await this.click({ button });
+  }
+  async scroll(steps, x, y) {
+    const normalizedSteps = validateInteger(steps, "scroll steps");
+    await this.moveIfRequested(x, y);
+    if (normalizedSteps === 0) {
+      return;
+    }
+    const wheelMask = normalizedSteps > 0 ? BUTTON_SCROLL_UP_MASK : BUTTON_SCROLL_DOWN_MASK;
+    const stepCount = Math.abs(normalizedSteps);
+    for (let index = 0; index < stepCount; index += 1) {
+      await sendPointerEvent(
+        this.transport,
+        this.buttonMask | wheelMask,
+        this.pointerX,
+        this.pointerY
+      );
+      await sendPointerEvent(
+        this.transport,
+        this.buttonMask,
+        this.pointerX,
+        this.pointerY
+      );
+    }
+  }
+  async keyDown(key) {
+    await sendKeyEvent(this.transport, true, keysymFromKeyName(key));
+  }
+  async keyUp(key) {
+    await sendKeyEvent(this.transport, false, keysymFromKeyName(key));
+  }
+  async press(keys) {
+    const parts = Array.isArray(keys) ? keys : [keys];
+    if (parts.length === 0) {
+      throw new SandboxError("desktop press requires at least one key");
+    }
+    const keysyms = parts.map((part) => keysymFromKeyName(part));
+    if (keysyms.length === 1) {
+      await sendKeyEvent(this.transport, true, keysyms[0]);
+      await sendKeyEvent(this.transport, false, keysyms[0]);
+      return;
+    }
+    for (const keysym of keysyms.slice(0, -1)) {
+      await sendKeyEvent(this.transport, true, keysym);
+    }
+    const last = keysyms[keysyms.length - 1];
+    await sendKeyEvent(this.transport, true, last);
+    await sendKeyEvent(this.transport, false, last);
+    for (const keysym of keysyms.slice(0, -1).reverse()) {
+      await sendKeyEvent(this.transport, false, keysym);
+    }
+  }
+  async typeText(text) {
+    for (const char of text) {
+      const keysym = keysymFromChar(char);
+      await sendKeyEvent(this.transport, true, keysym);
+      await sendKeyEvent(this.transport, false, keysym);
+    }
+  }
+  async moveIfRequested(x, y) {
+    if (x == null && y == null) {
+      return;
+    }
+    if (x == null || y == null) {
+      throw new SandboxError(
+        "desktop pointer actions require both x and y when specifying coordinates"
+      );
+    }
+    await this.moveMouse(x, y);
+  }
+  ensurePointerInBounds(x, y) {
+    if (this.width > 0 && x >= this.width) {
+      throw new SandboxError(
+        `mouse x coordinate ${x} is outside desktop width ${this.width}`
+      );
+    }
+    if (this.height > 0 && y >= this.height) {
+      throw new SandboxError(
+        `mouse y coordinate ${y} is outside desktop height ${this.height}`
+      );
+    }
+  }
+  startFramebufferUpdates() {
+    if (this.updateLoopPromise) {
+      return;
+    }
+    this.updateLoopPromise = this.runFramebufferUpdateLoop().catch((error) => {
+      if (this.closed) {
+        return;
+      }
+      this.updateLoopError = normalizeError(error);
+      this.updateSignal.resolve();
+    });
+  }
+  async runFramebufferUpdateLoop() {
+    let incremental = false;
+    while (!this.closed) {
+      await sendFramebufferUpdateRequest(
+        this.transport,
+        incremental,
+        0,
+        0,
+        this.width,
+        this.height
+      );
+      const outcome = await this.readUntilFramebufferUpdate();
+      if (outcome.sawResize && !outcome.sawRaw) {
+        incremental = false;
+        continue;
+      }
+      if (outcome.sawRaw) {
+        this.framebufferVersion += 1;
+        this.updateSignal.resolve();
+      }
+      incremental = true;
+    }
+  }
+  async readUntilFramebufferUpdate() {
+    while (true) {
+      const outcome = await this.readServerMessage();
+      if (outcome.kind === "framebufferUpdate") {
+        return outcome;
+      }
+    }
+  }
+  async waitForFramebufferVersion(minimumVersion, timeoutSeconds, timeoutMessage) {
+    const timeoutMs = secondsToMillis2(timeoutSeconds);
+    const deadline = Date.now() + timeoutMs;
+    while (this.framebufferVersion < minimumVersion) {
+      if (this.updateLoopError) {
+        throw this.updateLoopError;
+      }
+      if (this.closed) {
+        throw new SandboxError("desktop session is closed");
+      }
+      const observedVersion = this.framebufferVersion;
+      const waitForUpdate = this.updateSignal.wait();
+      if (this.framebufferVersion !== observedVersion) {
+        continue;
+      }
+      const remainingMs = Math.max(0, deadline - Date.now());
+      if (remainingMs === 0) {
+        break;
+      }
+      await withTimeout(remainingMs, () => waitForUpdate, timeoutMessage);
+    }
+    if (this.framebufferVersion < minimumVersion) {
+      throw new SandboxError(timeoutMessage);
+    }
+  }
+  async readServerMessage() {
+    const messageType = await readU8(this.transport);
+    if (messageType === 0) {
+      return this.readFramebufferUpdate();
+    }
+    if (messageType === 1) {
+      await this.readSetColorMapEntries();
+      return { kind: "bell" };
+    }
+    if (messageType === 2) {
+      return { kind: "bell" };
+    }
+    if (messageType === 3) {
+      await this.readServerCutText();
+      return { kind: "serverCutText" };
+    }
+    throw new SandboxError(`unsupported VNC server message type ${messageType}`);
+  }
+  async readFramebufferUpdate() {
+    await readU8(this.transport);
+    const rectangleCount = await readU16(this.transport);
+    let sawResize = false;
+    let sawRaw = false;
+    for (let index = 0; index < rectangleCount; index += 1) {
+      const x = await readU16(this.transport);
+      const y = await readU16(this.transport);
+      const width = await readU16(this.transport);
+      const height = await readU16(this.transport);
+      const encoding = await readI32(this.transport);
+      if (encoding === ENCODING_RAW) {
+        const bytesPerPixel = this.pixelFormat.bytesPerPixel();
+        const length = width * height * bytesPerPixel;
+        const data = await this.transport.readExactly(length);
+        this.blitRawRectangle(x, y, width, height, data);
+        sawRaw = true;
+        continue;
+      }
+      if (encoding === ENCODING_DESKTOP_SIZE) {
+        this.resizeFramebuffer(width, height);
+        sawResize = true;
+        continue;
+      }
+      throw new SandboxError(`unsupported VNC rectangle encoding ${encoding}`);
+    }
+    return { kind: "framebufferUpdate", sawResize, sawRaw };
+  }
+  async readSetColorMapEntries() {
+    await readU8(this.transport);
+    await readU16(this.transport);
+    const colorCount = await readU16(this.transport);
+    await this.transport.readExactly(colorCount * 6);
+    throw new SandboxError(
+      "desktop sessions do not support color-map VNC pixel formats"
+    );
+  }
+  async readServerCutText() {
+    await this.transport.readExactly(3);
+    const length = await readU32(this.transport);
+    await this.transport.readExactly(length);
+  }
+  resizeFramebuffer(width, height) {
+    this.width = width;
+    this.height = height;
+    this.framebuffer = allocateFramebuffer(width, height);
+    this.pointerX = width > 0 ? Math.min(this.pointerX, width - 1) : 0;
+    this.pointerY = height > 0 ? Math.min(this.pointerY, height - 1) : 0;
+  }
+  blitRawRectangle(x, y, width, height, data) {
+    if (x + width > this.width || y + height > this.height) {
+      throw new SandboxError("desktop raw rectangle exceeds framebuffer bounds");
+    }
+    const bytesPerPixel = this.pixelFormat.bytesPerPixel();
+    for (let row = 0; row < height; row += 1) {
+      for (let col = 0; col < width; col += 1) {
+        const srcIndex = (row * width + col) * bytesPerPixel;
+        const rgba = this.pixelFormat.decodePixel(
+          data.subarray(srcIndex, srcIndex + bytesPerPixel)
+        );
+        const dstIndex = ((y + row) * this.width + x + col) * 4;
+        this.framebuffer.set(rgba, dstIndex);
+      }
+    }
+  }
+};
+var Desktop = class _Desktop {
+  session;
+  connectRequest;
+  operationChain = Promise.resolve();
+  reconnectPromise = null;
+  closed = false;
+  constructor(session, connectRequest) {
+    this.session = session;
+    this.connectRequest = connectRequest;
+  }
+  static async connect(options) {
+    const connectRequest = normalizeDesktopConnectRequest(options);
+    const session = await openDesktopSession(connectRequest);
+    return new _Desktop(session, connectRequest);
+  }
+  get width() {
+    return this.session.width;
+  }
+  get height() {
+    return this.session.height;
+  }
+  async close() {
+    this.closed = true;
+    await this.enqueue(() => this.session.close());
+  }
+  async screenshot(timeout = 5) {
+    return this.enqueue(() => this.captureScreenshot(timeout));
+  }
+  getFrameVersion() {
+    return this.session.getFrameVersion();
+  }
+  async screenshotAfter(frameVersion, timeout = 1) {
+    return this.enqueue(() => this.captureScreenshotAfter(frameVersion, timeout));
+  }
+  async moveMouse(x, y) {
+    await this.enqueue(() => this.session.moveMouse(x, y));
+  }
+  async mousePress(options) {
+    await this.enqueue(() => this.session.mousePress(options));
+  }
+  async mouseRelease(options) {
+    await this.enqueue(() => this.session.mouseRelease(options));
+  }
+  async click(options) {
+    await this.enqueue(() => this.session.click(options));
+  }
+  async doubleClick(options) {
+    await this.enqueue(() => this.session.doubleClick(options));
+  }
+  async leftClick(x, y) {
+    await this.click({ button: "left", x, y });
+  }
+  async middleClick(x, y) {
+    await this.click({ button: "middle", x, y });
+  }
+  async rightClick(x, y) {
+    await this.click({ button: "right", x, y });
+  }
+  async scroll(steps, x, y) {
+    await this.enqueue(() => this.session.scroll(steps, x, y));
+  }
+  async scrollUp(steps = 1, x, y) {
+    await this.scroll(Math.abs(steps), x, y);
+  }
+  async scrollDown(steps = 1, x, y) {
+    await this.scroll(-Math.abs(steps), x, y);
+  }
+  async keyDown(key) {
+    await this.enqueue(() => this.session.keyDown(key));
+  }
+  async keyUp(key) {
+    await this.enqueue(() => this.session.keyUp(key));
+  }
+  async press(keys) {
+    await this.enqueue(() => this.session.press(keys));
+  }
+  async typeText(text) {
+    await this.enqueue(() => this.session.typeText(text));
+  }
+  enqueue(operation) {
+    const run = this.operationChain.catch(() => {
+    }).then(operation);
+    this.operationChain = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
+  }
+  async captureScreenshot(timeout) {
+    try {
+      return await this.session.screenshot(timeout);
+    } catch (error) {
+      if (!isReconnectableDesktopScreenshotError(error) || this.closed) {
+        throw error;
+      }
+      await this.reconnect();
+      return this.session.screenshot(timeout);
+    }
+  }
+  async captureScreenshotAfter(frameVersion, timeout) {
+    try {
+      return await this.session.screenshotAfter(frameVersion, timeout);
+    } catch (error) {
+      if (!isReconnectableDesktopScreenshotError(error) || this.closed) {
+        throw error;
+      }
+      await this.reconnect();
+      return this.session.screenshot(timeout);
+    }
+  }
+  async reconnect() {
+    if (this.reconnectPromise) {
+      return this.reconnectPromise;
+    }
+    this.reconnectPromise = this.performReconnect().finally(() => {
+      this.reconnectPromise = null;
+    });
+    return this.reconnectPromise;
+  }
+  async performReconnect() {
+    const previousSession = this.session;
+    await previousSession.close().catch(() => {
+    });
+    this.session = await openDesktopSession(this.connectRequest);
+  }
+};
+var ProtocolVersion = class _ProtocolVersion {
+  major;
+  minor;
+  constructor(major, minor) {
+    this.major = major;
+    this.minor = minor;
+  }
+  static async read(transport) {
+    const raw = await transport.readExactly(12);
+    const text = raw.toString("ascii");
+    const trimmed = text.endsWith("\n") ? text.slice(0, -1) : text;
+    const match = /^RFB (\d{3})\.(\d{3})$/.exec(trimmed);
+    if (!match) {
+      throw new SandboxError(`invalid VNC protocol banner \`${text}\``);
+    }
+    return new _ProtocolVersion(Number.parseInt(match[1], 10), Number.parseInt(match[2], 10));
+  }
+  negotiated() {
+    if (this.major !== 3 || this.minor >= 8) {
+      return new _ProtocolVersion(3, 8);
+    }
+    if (this.minor >= 7) {
+      return new _ProtocolVersion(3, 7);
+    }
+    return new _ProtocolVersion(3, 3);
+  }
+  render() {
+    return `RFB ${String(this.major).padStart(3, "0")}.${String(this.minor).padStart(3, "0")}
+`;
+  }
+};
+var PixelFormat = class _PixelFormat {
+  bitsPerPixel;
+  depth;
+  bigEndian;
+  trueColor;
+  redMax;
+  greenMax;
+  blueMax;
+  redShift;
+  greenShift;
+  blueShift;
+  constructor(options) {
+    this.bitsPerPixel = options.bitsPerPixel;
+    this.depth = options.depth;
+    this.bigEndian = options.bigEndian;
+    this.trueColor = options.trueColor;
+    this.redMax = options.redMax;
+    this.greenMax = options.greenMax;
+    this.blueMax = options.blueMax;
+    this.redShift = options.redShift;
+    this.greenShift = options.greenShift;
+    this.blueShift = options.blueShift;
+  }
+  static preferred() {
+    return new _PixelFormat({
+      bitsPerPixel: 32,
+      depth: 24,
+      bigEndian: false,
+      trueColor: true,
+      redMax: 255,
+      greenMax: 255,
+      blueMax: 255,
+      redShift: 16,
+      greenShift: 8,
+      blueShift: 0
+    });
+  }
+  static parse(bytes) {
+    if (bytes.length !== 16) {
+      throw new SandboxError("invalid VNC pixel format payload length");
+    }
+    return new _PixelFormat({
+      bitsPerPixel: bytes[0],
+      depth: bytes[1],
+      bigEndian: bytes[2] !== 0,
+      trueColor: bytes[3] !== 0,
+      redMax: Buffer.from(bytes.subarray(4, 6)).readUInt16BE(0),
+      greenMax: Buffer.from(bytes.subarray(6, 8)).readUInt16BE(0),
+      blueMax: Buffer.from(bytes.subarray(8, 10)).readUInt16BE(0),
+      redShift: bytes[10],
+      greenShift: bytes[11],
+      blueShift: bytes[12]
+    });
+  }
+  bytesPerPixel() {
+    return this.bitsPerPixel / 8;
+  }
+  encode() {
+    const bytes = Buffer.alloc(16);
+    bytes[0] = this.bitsPerPixel;
+    bytes[1] = this.depth;
+    bytes[2] = this.bigEndian ? 1 : 0;
+    bytes[3] = this.trueColor ? 1 : 0;
+    bytes.writeUInt16BE(this.redMax, 4);
+    bytes.writeUInt16BE(this.greenMax, 6);
+    bytes.writeUInt16BE(this.blueMax, 8);
+    bytes[10] = this.redShift;
+    bytes[11] = this.greenShift;
+    bytes[12] = this.blueShift;
+    return bytes;
+  }
+  decodePixel(bytes) {
+    if (bytes.length !== this.bytesPerPixel()) {
+      throw new SandboxError("desktop pixel buffer has an unexpected size");
+    }
+    let value = 0;
+    if (this.bigEndian) {
+      for (const byte of bytes) {
+        value = value << 8 | byte;
+      }
+    } else {
+      for (let index = 0; index < bytes.length; index += 1) {
+        value |= bytes[index] << index * 8;
+      }
+    }
+    const red = scaleChannel(value >> this.redShift & this.redMax, this.redMax);
+    const green = scaleChannel(
+      value >> this.greenShift & this.greenMax,
+      this.greenMax
+    );
+    const blue = scaleChannel(value >> this.blueShift & this.blueMax, this.blueMax);
+    return Uint8Array.of(red, green, blue, 255);
+  }
+};
+var ServerInit = class _ServerInit {
+  width;
+  height;
+  pixelFormat;
+  constructor(width, height, pixelFormat) {
+    this.width = width;
+    this.height = height;
+    this.pixelFormat = pixelFormat;
+  }
+  static async read(transport) {
+    const width = await readU16(transport);
+    const height = await readU16(transport);
+    const pixelFormat = PixelFormat.parse(await transport.readExactly(16));
+    const nameLength = await readU32(transport);
+    await transport.readExactly(nameLength);
+    return new _ServerInit(width, height, pixelFormat);
+  }
+};
+async function negotiateSecurity(transport, version, password) {
+  let securityTypes;
+  if (version.minor === 3) {
+    const securityType = await readU32(transport);
+    if (securityType === 0) {
+      const reasonLength = await readU32(transport);
+      const reason = (await transport.readExactly(reasonLength)).toString("utf8");
+      throw new SandboxError(`VNC security negotiation failed: ${reason}`);
+    }
+    securityTypes = [securityType];
+  } else {
+    const count = await readU8(transport);
+    if (count === 0) {
+      const reasonLength = await readU32(transport);
+      const reason = (await transport.readExactly(reasonLength)).toString("utf8");
+      throw new SandboxError(`VNC security negotiation failed: ${reason}`);
+    }
+    securityTypes = [...await transport.readExactly(count)];
+  }
+  let selected;
+  if (password != null && securityTypes.includes(SECURITY_TYPE_VNC_AUTH)) {
+    selected = SECURITY_TYPE_VNC_AUTH;
+  } else if (securityTypes.includes(SECURITY_TYPE_NONE)) {
+    selected = SECURITY_TYPE_NONE;
+  } else if (securityTypes.includes(SECURITY_TYPE_VNC_AUTH)) {
+    throw new SandboxError(
+      "VNC server requires password authentication but no password was provided"
+    );
+  } else {
+    throw new SandboxError(
+      `unsupported VNC security types advertised by server: [${securityTypes.join(", ")}]`
+    );
+  }
+  if (version.minor >= 7) {
+    await transport.writeAll(Uint8Array.of(selected));
+  }
+  if (selected === SECURITY_TYPE_VNC_AUTH) {
+    if (password == null) {
+      throw new SandboxError(
+        "VNC server requires password authentication but no password was provided"
+      );
+    }
+    const challenge = await transport.readExactly(16);
+    const response = encryptVncChallenge(Buffer.from(password, "utf8"), challenge);
+    await transport.writeAll(response);
+    await readSecurityResult(transport, version.minor >= 8);
+  } else if (version.minor >= 8) {
+    await readSecurityResult(transport, true);
+  }
+  return selected;
+}
+function encryptVncChallenge(password, challenge) {
+  if (challenge.length !== 16) {
+    throw new SandboxError("VNC authentication challenge must be 16 bytes");
+  }
+  const key = Buffer.alloc(8);
+  for (let index = 0; index < Math.min(password.length, 8); index += 1) {
+    key[index] = reverseBits(password[index]);
+  }
+  const roundKeys = buildDesRoundKeys(key);
+  const output = Buffer.alloc(16);
+  for (let blockIndex = 0; blockIndex < 2; blockIndex += 1) {
+    const start = blockIndex * 8;
+    const encrypted = encryptDesBlock(challenge.subarray(start, start + 8), roundKeys);
+    output.set(encrypted, start);
+  }
+  return output;
+}
+function reverseBits(value) {
+  let reversed = 0;
+  for (let bit = 0; bit < 8; bit += 1) {
+    reversed |= (value >> bit & 1) << 7 - bit;
+  }
+  return reversed;
+}
+async function readSecurityResult(transport, hasReasonString) {
+  const status = await readU32(transport);
+  if (status === 0) {
+    return;
+  }
+  let reason;
+  if (hasReasonString) {
+    const reasonLength = await readU32(transport);
+    reason = (await transport.readExactly(reasonLength)).toString("utf8");
+  } else if (status === 1) {
+    reason = "authentication failed";
+  } else {
+    reason = `security handshake failed with status ${status}`;
+  }
+  throw new SandboxError(`VNC security negotiation failed: ${reason}`);
+}
+async function sendSetPixelFormat(transport, pixelFormat) {
+  const message = Buffer.alloc(20);
+  message[0] = 0;
+  message.set(pixelFormat.encode(), 4);
+  await transport.writeAll(message);
+}
+async function sendSetEncodings(transport, encodings) {
+  const message = Buffer.alloc(4 + encodings.length * 4);
+  message[0] = 2;
+  message.writeUInt16BE(encodings.length, 2);
+  for (let index = 0; index < encodings.length; index += 1) {
+    message.writeInt32BE(encodings[index], 4 + index * 4);
+  }
+  await transport.writeAll(message);
+}
+async function sendFramebufferUpdateRequest(transport, incremental, x, y, width, height) {
+  const message = Buffer.alloc(10);
+  message[0] = 3;
+  message[1] = incremental ? 1 : 0;
+  message.writeUInt16BE(x, 2);
+  message.writeUInt16BE(y, 4);
+  message.writeUInt16BE(width, 6);
+  message.writeUInt16BE(height, 8);
+  await transport.writeAll(message);
+}
+async function sendPointerEvent(transport, buttonMask2, x, y) {
+  const message = Buffer.alloc(6);
+  message[0] = 5;
+  message[1] = buttonMask2;
+  message.writeUInt16BE(x, 2);
+  message.writeUInt16BE(y, 4);
+  await transport.writeAll(message);
+}
+async function sendKeyEvent(transport, down, keysym) {
+  const message = Buffer.alloc(8);
+  message[0] = 4;
+  message[1] = down ? 1 : 0;
+  message.writeUInt32BE(keysym, 4);
+  await transport.writeAll(message);
+}
+async function readU8(transport) {
+  return (await transport.readExactly(1))[0];
+}
+async function readU16(transport) {
+  return (await transport.readExactly(2)).readUInt16BE(0);
+}
+async function readU32(transport) {
+  return (await transport.readExactly(4)).readUInt32BE(0);
+}
+async function readI32(transport) {
+  return (await transport.readExactly(4)).readInt32BE(0);
+}
+function scaleChannel(value, max) {
+  if (max === 0) {
+    throw new SandboxError("invalid VNC pixel format with zero channel range");
+  }
+  return Math.trunc(value * 255 / max);
+}
+function allocateFramebuffer(width, height) {
+  return new Uint8Array(width * height * 4);
+}
+function normalizeDesktopConnectRequest(options) {
+  return {
+    ...options,
+    port: validatePort2(options.port ?? 5901, "desktop port"),
+    shared: options.shared ?? true,
+    connectTimeout: options.connectTimeout ?? 10
+  };
+}
+async function openDesktopSession(options) {
+  const connectTimeoutMs = secondsToMillis2(options.connectTimeout);
+  const state = {};
+  try {
+    return await withTimeout(
+      connectTimeoutMs,
+      async () => {
+        state.transport = await TunnelByteStream.connect({
+          baseUrl: options.baseUrl,
+          wsHeaders: options.wsHeaders,
+          remotePort: options.port,
+          connectTimeoutMs
+        });
+        return DesktopSession.connect(
+          state.transport,
+          options.password,
+          options.shared
+        );
+      },
+      `timed out while connecting desktop session after ${options.connectTimeout.toFixed(2)}s`
+    );
+  } catch (error) {
+    if (state.transport) {
+      await state.transport.close().catch(() => {
+      });
+    }
+    throw error;
+  }
+}
+function isReconnectableDesktopScreenshotError(error) {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  const message = error.message.toLowerCase();
+  return message.includes("desktop tunnel closed unexpectedly") || message.includes("desktop tunnel is not connected") || message.includes("connection closed") || message.includes("econnreset") || message.includes("timed out waiting for initial desktop framebuffer") || message.includes("timed out while connecting tunnel websocket") || message.includes("tunnel websocket closed before opening") || message.includes("tunnel websocket handshake failed");
+}
+function createDeferredSignal() {
+  let resolveCurrent;
+  let promise = new Promise((resolve) => {
+    resolveCurrent = resolve;
+  });
+  return {
+    resolve() {
+      resolveCurrent();
+      promise = new Promise((resolve) => {
+        resolveCurrent = resolve;
+      });
+    },
+    wait() {
+      return promise;
+    }
+  };
+}
+function normalizeError(error) {
+  return error instanceof Error ? error : new SandboxError(String(error));
+}
+function buttonMask(button) {
+  const normalized = button.trim().toLowerCase();
+  if (normalized === "left") return BUTTON_LEFT_MASK;
+  if (normalized === "middle") return BUTTON_MIDDLE_MASK;
+  if (normalized === "right") return BUTTON_RIGHT_MASK;
+  throw new SandboxError(
+    `unsupported mouse button \`${button}\`; expected left, middle, or right`
+  );
+}
+function keysymFromKeyName(key) {
+  const trimmed = key.trim();
+  if (trimmed.length === 0) {
+    throw new SandboxError("desktop key name cannot be empty");
+  }
+  if ([...trimmed].length === 1) {
+    return keysymFromChar(trimmed);
+  }
+  const normalized = trimmed.toLowerCase();
+  const special = SPECIAL_KEYSYMS.get(normalized);
+  if (special != null) {
+    return special;
+  }
+  const functionMatch = /^f([1-9]|1[0-2])$/.exec(normalized);
+  if (functionMatch) {
+    return 65469 + Number.parseInt(functionMatch[1], 10);
+  }
+  throw new SandboxError(`unsupported desktop key \`${trimmed}\``);
+}
+function keysymFromChar(char) {
+  const codePoint = char.codePointAt(0);
+  if (codePoint == null) {
+    throw new SandboxError("desktop key name cannot be empty");
+  }
+  if (char === "\n" || char === "\r") return 65293;
+  if (char === "	") return 65289;
+  if (char === "\b") return 65288;
+  if (codePoint >= 32 && codePoint <= 126) return codePoint;
+  if (codePoint < 32 || codePoint >= 127 && codePoint <= 159) {
+    throw new SandboxError(
+      `unsupported control character U+${codePoint.toString(16).toUpperCase().padStart(4, "0")} for desktop typing`
+    );
+  }
+  return 16777216 | codePoint;
+}
+function encodePng(width, height, rgba) {
+  const stride = width * 4;
+  const raw = Buffer.alloc((stride + 1) * height);
+  for (let row = 0; row < height; row += 1) {
+    const srcOffset = row * stride;
+    const dstOffset = row * (stride + 1);
+    raw[dstOffset] = 0;
+    raw.set(rgba.subarray(srcOffset, srcOffset + stride), dstOffset + 1);
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8;
+  ihdr[9] = 6;
+  ihdr[10] = 0;
+  ihdr[11] = 0;
+  ihdr[12] = 0;
+  const idat = (0, import_node_zlib.deflateSync)(raw);
+  return Buffer.concat([
+    PNG_SIGNATURE,
+    pngChunk("IHDR", ihdr),
+    pngChunk("IDAT", idat),
+    pngChunk("IEND", Buffer.alloc(0))
+  ]);
+}
+function pngChunk(type, data) {
+  const chunkType = Buffer.from(type, "ascii");
+  const length = Buffer.alloc(4);
+  length.writeUInt32BE(data.length, 0);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(Buffer.concat([chunkType, data])), 0);
+  return Buffer.concat([length, chunkType, data, crc]);
+}
+function crc32(data) {
+  let crc = 4294967295;
+  for (const byte of data) {
+    crc = CRC32_TABLE[(crc ^ byte) & 255] ^ crc >>> 8;
+  }
+  return (crc ^ 4294967295) >>> 0;
+}
+function buildCrc32Table() {
+  const table = new Uint32Array(256);
+  for (let index = 0; index < 256; index += 1) {
+    let value = index;
+    for (let bit = 0; bit < 8; bit += 1) {
+      value = (value & 1) !== 0 ? 3988292384 ^ value >>> 1 : value >>> 1;
+    }
+    table[index] = value >>> 0;
+  }
+  return table;
+}
+function validateCoordinate(value, label) {
+  return validateIntegerInRange(value, label, 0, 65535);
+}
+function validatePort2(value, label) {
+  return validateIntegerInRange(value, label, 1, 65535);
+}
+function validateIntegerInRange(value, label, min, max) {
+  if (!Number.isInteger(value) || value < min || value > max) {
+    throw new SandboxError(`${label} must be an integer between ${min} and ${max}, got ${value}`);
+  }
+  return value;
+}
+function validateInteger(value, label) {
+  if (!Number.isInteger(value)) {
+    throw new SandboxError(`${label} must be an integer, got ${value}`);
+  }
+  return value;
+}
+function validateNonNegativeInteger(value, label) {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new SandboxError(`${label} must be a non-negative integer, got ${value}`);
+  }
+  return value;
+}
+function secondsToMillis2(seconds) {
+  if (!Number.isFinite(seconds) || seconds < 0) {
+    throw new SandboxError(`timeout must be >= 0 seconds, got ${seconds}`);
+  }
+  return Math.round(seconds * 1e3);
+}
+var SPECIAL_KEYSYMS = /* @__PURE__ */ new Map([
+  ["enter", 65293],
+  ["tab", 65289],
+  ["escape", 65307],
+  ["backspace", 65288],
+  ["delete", 65535],
+  ["space", 32],
+  ["up", 65362],
+  ["down", 65364],
+  ["left", 65361],
+  ["right", 65363],
+  ["home", 65360],
+  ["end", 65367],
+  ["pageup", 65365],
+  ["pagedown", 65366],
+  ["page_up", 65365],
+  ["page_down", 65366],
+  ["shift", 65505],
+  ["ctrl", 65507],
+  ["control", 65507],
+  ["alt", 65513],
+  ["meta", 65511]
+]);
+var DES_INITIAL_PERMUTATION = [
+  58,
+  50,
+  42,
+  34,
+  26,
+  18,
+  10,
+  2,
+  60,
+  52,
+  44,
+  36,
+  28,
+  20,
+  12,
+  4,
+  62,
+  54,
+  46,
+  38,
+  30,
+  22,
+  14,
+  6,
+  64,
+  56,
+  48,
+  40,
+  32,
+  24,
+  16,
+  8,
+  57,
+  49,
+  41,
+  33,
+  25,
+  17,
+  9,
+  1,
+  59,
+  51,
+  43,
+  35,
+  27,
+  19,
+  11,
+  3,
+  61,
+  53,
+  45,
+  37,
+  29,
+  21,
+  13,
+  5,
+  63,
+  55,
+  47,
+  39,
+  31,
+  23,
+  15,
+  7
+];
+var DES_FINAL_PERMUTATION = [
+  40,
+  8,
+  48,
+  16,
+  56,
+  24,
+  64,
+  32,
+  39,
+  7,
+  47,
+  15,
+  55,
+  23,
+  63,
+  31,
+  38,
+  6,
+  46,
+  14,
+  54,
+  22,
+  62,
+  30,
+  37,
+  5,
+  45,
+  13,
+  53,
+  21,
+  61,
+  29,
+  36,
+  4,
+  44,
+  12,
+  52,
+  20,
+  60,
+  28,
+  35,
+  3,
+  43,
+  11,
+  51,
+  19,
+  59,
+  27,
+  34,
+  2,
+  42,
+  10,
+  50,
+  18,
+  58,
+  26,
+  33,
+  1,
+  41,
+  9,
+  49,
+  17,
+  57,
+  25
+];
+var DES_EXPANSION = [
+  32,
+  1,
+  2,
+  3,
+  4,
+  5,
+  4,
+  5,
+  6,
+  7,
+  8,
+  9,
+  8,
+  9,
+  10,
+  11,
+  12,
+  13,
+  12,
+  13,
+  14,
+  15,
+  16,
+  17,
+  16,
+  17,
+  18,
+  19,
+  20,
+  21,
+  20,
+  21,
+  22,
+  23,
+  24,
+  25,
+  24,
+  25,
+  26,
+  27,
+  28,
+  29,
+  28,
+  29,
+  30,
+  31,
+  32,
+  1
+];
+var DES_P_PERMUTATION = [
+  16,
+  7,
+  20,
+  21,
+  29,
+  12,
+  28,
+  17,
+  1,
+  15,
+  23,
+  26,
+  5,
+  18,
+  31,
+  10,
+  2,
+  8,
+  24,
+  14,
+  32,
+  27,
+  3,
+  9,
+  19,
+  13,
+  30,
+  6,
+  22,
+  11,
+  4,
+  25
+];
+var DES_PC1 = [
+  57,
+  49,
+  41,
+  33,
+  25,
+  17,
+  9,
+  1,
+  58,
+  50,
+  42,
+  34,
+  26,
+  18,
+  10,
+  2,
+  59,
+  51,
+  43,
+  35,
+  27,
+  19,
+  11,
+  3,
+  60,
+  52,
+  44,
+  36,
+  63,
+  55,
+  47,
+  39,
+  31,
+  23,
+  15,
+  7,
+  62,
+  54,
+  46,
+  38,
+  30,
+  22,
+  14,
+  6,
+  61,
+  53,
+  45,
+  37,
+  29,
+  21,
+  13,
+  5,
+  28,
+  20,
+  12,
+  4
+];
+var DES_PC2 = [
+  14,
+  17,
+  11,
+  24,
+  1,
+  5,
+  3,
+  28,
+  15,
+  6,
+  21,
+  10,
+  23,
+  19,
+  12,
+  4,
+  26,
+  8,
+  16,
+  7,
+  27,
+  20,
+  13,
+  2,
+  41,
+  52,
+  31,
+  37,
+  47,
+  55,
+  30,
+  40,
+  51,
+  45,
+  33,
+  48,
+  44,
+  49,
+  39,
+  56,
+  34,
+  53,
+  46,
+  42,
+  50,
+  36,
+  29,
+  32
+];
+var DES_ROTATIONS = [
+  1,
+  1,
+  2,
+  2,
+  2,
+  2,
+  2,
+  2,
+  1,
+  2,
+  2,
+  2,
+  2,
+  2,
+  2,
+  1
+];
+var DES_SBOXES = [
+  [
+    14,
+    4,
+    13,
+    1,
+    2,
+    15,
+    11,
+    8,
+    3,
+    10,
+    6,
+    12,
+    5,
+    9,
+    0,
+    7,
+    0,
+    15,
+    7,
+    4,
+    14,
+    2,
+    13,
+    1,
+    10,
+    6,
+    12,
+    11,
+    9,
+    5,
+    3,
+    8,
+    4,
+    1,
+    14,
+    8,
+    13,
+    6,
+    2,
+    11,
+    15,
+    12,
+    9,
+    7,
+    3,
+    10,
+    5,
+    0,
+    15,
+    12,
+    8,
+    2,
+    4,
+    9,
+    1,
+    7,
+    5,
+    11,
+    3,
+    14,
+    10,
+    0,
+    6,
+    13
+  ],
+  [
+    15,
+    1,
+    8,
+    14,
+    6,
+    11,
+    3,
+    4,
+    9,
+    7,
+    2,
+    13,
+    12,
+    0,
+    5,
+    10,
+    3,
+    13,
+    4,
+    7,
+    15,
+    2,
+    8,
+    14,
+    12,
+    0,
+    1,
+    10,
+    6,
+    9,
+    11,
+    5,
+    0,
+    14,
+    7,
+    11,
+    10,
+    4,
+    13,
+    1,
+    5,
+    8,
+    12,
+    6,
+    9,
+    3,
+    2,
+    15,
+    13,
+    8,
+    10,
+    1,
+    3,
+    15,
+    4,
+    2,
+    11,
+    6,
+    7,
+    12,
+    0,
+    5,
+    14,
+    9
+  ],
+  [
+    10,
+    0,
+    9,
+    14,
+    6,
+    3,
+    15,
+    5,
+    1,
+    13,
+    12,
+    7,
+    11,
+    4,
+    2,
+    8,
+    13,
+    7,
+    0,
+    9,
+    3,
+    4,
+    6,
+    10,
+    2,
+    8,
+    5,
+    14,
+    12,
+    11,
+    15,
+    1,
+    13,
+    6,
+    4,
+    9,
+    8,
+    15,
+    3,
+    0,
+    11,
+    1,
+    2,
+    12,
+    5,
+    10,
+    14,
+    7,
+    1,
+    10,
+    13,
+    0,
+    6,
+    9,
+    8,
+    7,
+    4,
+    15,
+    14,
+    3,
+    11,
+    5,
+    2,
+    12
+  ],
+  [
+    7,
+    13,
+    14,
+    3,
+    0,
+    6,
+    9,
+    10,
+    1,
+    2,
+    8,
+    5,
+    11,
+    12,
+    4,
+    15,
+    13,
+    8,
+    11,
+    5,
+    6,
+    15,
+    0,
+    3,
+    4,
+    7,
+    2,
+    12,
+    1,
+    10,
+    14,
+    9,
+    10,
+    6,
+    9,
+    0,
+    12,
+    11,
+    7,
+    13,
+    15,
+    1,
+    3,
+    14,
+    5,
+    2,
+    8,
+    4,
+    3,
+    15,
+    0,
+    6,
+    10,
+    1,
+    13,
+    8,
+    9,
+    4,
+    5,
+    11,
+    12,
+    7,
+    2,
+    14
+  ],
+  [
+    2,
+    12,
+    4,
+    1,
+    7,
+    10,
+    11,
+    6,
+    8,
+    5,
+    3,
+    15,
+    13,
+    0,
+    14,
+    9,
+    14,
+    11,
+    2,
+    12,
+    4,
+    7,
+    13,
+    1,
+    5,
+    0,
+    15,
+    10,
+    3,
+    9,
+    8,
+    6,
+    4,
+    2,
+    1,
+    11,
+    10,
+    13,
+    7,
+    8,
+    15,
+    9,
+    12,
+    5,
+    6,
+    3,
+    0,
+    14,
+    11,
+    8,
+    12,
+    7,
+    1,
+    14,
+    2,
+    13,
+    6,
+    15,
+    0,
+    9,
+    10,
+    4,
+    5,
+    3
+  ],
+  [
+    12,
+    1,
+    10,
+    15,
+    9,
+    2,
+    6,
+    8,
+    0,
+    13,
+    3,
+    4,
+    14,
+    7,
+    5,
+    11,
+    10,
+    15,
+    4,
+    2,
+    7,
+    12,
+    9,
+    5,
+    6,
+    1,
+    13,
+    14,
+    0,
+    11,
+    3,
+    8,
+    9,
+    14,
+    15,
+    5,
+    2,
+    8,
+    12,
+    3,
+    7,
+    0,
+    4,
+    10,
+    1,
+    13,
+    11,
+    6,
+    4,
+    3,
+    2,
+    12,
+    9,
+    5,
+    15,
+    10,
+    11,
+    14,
+    1,
+    7,
+    6,
+    0,
+    8,
+    13
+  ],
+  [
+    4,
+    11,
+    2,
+    14,
+    15,
+    0,
+    8,
+    13,
+    3,
+    12,
+    9,
+    7,
+    5,
+    10,
+    6,
+    1,
+    13,
+    0,
+    11,
+    7,
+    4,
+    9,
+    1,
+    10,
+    14,
+    3,
+    5,
+    12,
+    2,
+    15,
+    8,
+    6,
+    1,
+    4,
+    11,
+    13,
+    12,
+    3,
+    7,
+    14,
+    10,
+    15,
+    6,
+    8,
+    0,
+    5,
+    9,
+    2,
+    6,
+    11,
+    13,
+    8,
+    1,
+    4,
+    10,
+    7,
+    9,
+    5,
+    0,
+    15,
+    14,
+    2,
+    3,
+    12
+  ],
+  [
+    13,
+    2,
+    8,
+    4,
+    6,
+    15,
+    11,
+    1,
+    10,
+    9,
+    3,
+    14,
+    5,
+    0,
+    12,
+    7,
+    1,
+    15,
+    13,
+    8,
+    10,
+    3,
+    7,
+    4,
+    12,
+    5,
+    6,
+    11,
+    0,
+    14,
+    9,
+    2,
+    7,
+    11,
+    4,
+    1,
+    9,
+    12,
+    14,
+    2,
+    0,
+    6,
+    10,
+    13,
+    15,
+    3,
+    5,
+    8,
+    2,
+    1,
+    14,
+    7,
+    4,
+    10,
+    8,
+    13,
+    15,
+    12,
+    9,
+    0,
+    3,
+    5,
+    6,
+    11
+  ]
+];
+function buildDesRoundKeys(key) {
+  const keyBlock = bytesToBigInt(key);
+  const permuted = permuteBits(keyBlock, DES_PC1, 64);
+  let c = Number(permuted >> 28n & 0x0fffffffn);
+  let d = Number(permuted & 0x0fffffffn);
+  const roundKeys = [];
+  for (const rotation of DES_ROTATIONS) {
+    c = rotateLeft28(c, rotation);
+    d = rotateLeft28(d, rotation);
+    const combined = BigInt(c) << 28n | BigInt(d);
+    roundKeys.push(permuteBits(combined, DES_PC2, 56));
+  }
+  return roundKeys;
+}
+function encryptDesBlock(block, roundKeys) {
+  let value = permuteBits(bytesToBigInt(block), DES_INITIAL_PERMUTATION, 64);
+  let left = Number(value >> 32n & 0xffffffffn);
+  let right = Number(value & 0xffffffffn);
+  for (const roundKey of roundKeys) {
+    const nextLeft = right;
+    const nextRight = (left ^ feistel(right, roundKey)) >>> 0;
+    left = nextLeft >>> 0;
+    right = nextRight;
+  }
+  value = BigInt(right) << 32n | BigInt(left);
+  return bigIntToBytes(permuteBits(value, DES_FINAL_PERMUTATION, 64), 8);
+}
+function feistel(right, roundKey) {
+  const expanded = permuteBits(BigInt(right >>> 0), DES_EXPANSION, 32) ^ roundKey;
+  let output = 0;
+  for (let index = 0; index < 8; index += 1) {
+    const shift = BigInt((7 - index) * 6);
+    const chunk = Number(expanded >> shift & 0x3fn);
+    const row = (chunk & 32) >> 4 | chunk & 1;
+    const column = chunk >> 1 & 15;
+    output = output << 4 | DES_SBOXES[index][row * 16 + column];
+  }
+  return Number(permuteBits(BigInt(output >>> 0), DES_P_PERMUTATION, 32)) >>> 0;
+}
+function rotateLeft28(value, shift) {
+  const masked = value & 268435455;
+  return (masked << shift | masked >>> 28 - shift) & 268435455;
+}
+function permuteBits(input, table, inputBits) {
+  let output = 0n;
+  for (const position of table) {
+    const shift = BigInt(inputBits - position);
+    output = output << 1n | input >> shift & 1n;
+  }
+  return output;
+}
+function bytesToBigInt(bytes) {
+  let value = 0n;
+  for (const byte of bytes) {
+    value = value << 8n | BigInt(byte);
+  }
+  return value;
+}
+function bigIntToBytes(value, length) {
+  const out = Buffer.alloc(length);
+  let remaining = value;
+  for (let index = length - 1; index >= 0; index -= 1) {
+    out[index] = Number(remaining & 0xffn);
+    remaining >>= 8n;
+  }
+  return out;
+}
+
 // src/sse.ts
 async function* parseSSEMessages(stream, signal) {
   const reader = stream.getReader();
@@ -541,7 +2932,7 @@ function lifecyclePath(path2, isLocal, namespace) {
 }
 
 // src/sandbox.ts
-var import_ws = __toESM(require("ws"), 1);
+var import_ws2 = __toESM(require("ws"), 1);
 var PTY_OP_DATA = 0;
 var PTY_OP_RESIZE = 1;
 var PTY_OP_READY = 2;
@@ -585,7 +2976,7 @@ var Pty = class {
     return () => this.exitHandlers.delete(handler);
   }
   async connect() {
-    if (this.socket?.readyState === import_ws.default.OPEN) {
+    if (this.socket?.readyState === import_ws2.default.OPEN) {
       return this;
     }
     if (this.connectPromise) {
@@ -594,7 +2985,7 @@ var Pty = class {
     this.intentionalDisconnect = false;
     this.connectPromise = new Promise((resolve, reject) => {
       let opened = false;
-      const socket = new import_ws.default(this.wsUrl, {
+      const socket = new import_ws2.default(this.wsUrl, {
         headers: this.wsHeaders
       });
       this.socket = socket;
@@ -684,7 +3075,7 @@ var Pty = class {
     await this.killSession();
   }
   requireOpenSocket() {
-    if (!this.socket || this.socket.readyState !== import_ws.default.OPEN) {
+    if (!this.socket || this.socket.readyState !== import_ws2.default.OPEN) {
       throw new SandboxError("PTY is not connected");
     }
     return this.socket;
@@ -1010,6 +3401,26 @@ var Sandbox = class {
     await pty.connect();
     return pty;
   }
+  async createTunnel(remotePort, options) {
+    return TcpTunnel.listen({
+      baseUrl: this.baseUrl,
+      wsHeaders: this.wsHeaders,
+      remotePort,
+      localHost: options?.localHost,
+      localPort: options?.localPort,
+      connectTimeout: options?.connectTimeout
+    });
+  }
+  async connectDesktop(options) {
+    return Desktop.connect({
+      baseUrl: this.baseUrl,
+      wsHeaders: this.wsHeaders,
+      port: options?.port,
+      password: options?.password,
+      shared: options?.shared,
+      connectTimeout: options?.connectTimeout
+    });
+  }
   ptyWsUrl(sessionId, token) {
     let wsBase;
     if (this.baseUrl.startsWith("https://")) {
@@ -1209,10 +3620,12 @@ var SandboxClient = class _SandboxClient {
     return fromSnakeKeys(raw, "sandboxId");
   }
   // --- Snapshots ---
-  async snapshot(sandboxId) {
+  async snapshot(sandboxId, options) {
+    const requestOptions = options?.contentMode != null ? { body: { snapshot_content_mode: options.contentMode } } : void 0;
     const raw = await this.http.requestJson(
       "POST",
-      this.path(`sandboxes/${sandboxId}/snapshot`)
+      this.path(`sandboxes/${sandboxId}/snapshot`),
+      requestOptions
     );
     return fromSnakeKeys(raw, "snapshotId");
   }
@@ -1241,7 +3654,9 @@ var SandboxClient = class _SandboxClient {
   async snapshotAndWait(sandboxId, options) {
     const timeout = options?.timeout ?? 300;
     const pollInterval = options?.pollInterval ?? 1;
-    const result = await this.snapshot(sandboxId);
+    const result = await this.snapshot(sandboxId, {
+      contentMode: options?.contentMode
+    });
     const deadline = Date.now() + timeout * 1e3;
     while (Date.now() < deadline) {
       const info = await this.getSnapshot(result.snapshotId);
@@ -2562,7 +4977,9 @@ async function createSandboxImage(source, options = {}, deps = {}) {
     });
     await executeDockerfilePlan(sandbox, plan, emit, sleep4);
     emit({ type: "status", message: "Creating snapshot..." });
-    const snapshot = await client.snapshotAndWait(sandbox.sandboxId);
+    const snapshot = await client.snapshotAndWait(sandbox.sandboxId, {
+      contentMode: "filesystem_only"
+    });
     emit({
       type: "snapshot_created",
       snapshot_id: snapshot.snapshotId,
@@ -2607,6 +5024,7 @@ async function createSandboxImage(source, options = {}, deps = {}) {
   APIClient,
   CloudClient,
   ContainerState,
+  Desktop,
   Image,
   ImageBuildOperationType,
   OutputMode,
@@ -2627,6 +5045,7 @@ async function createSandboxImage(source, options = {}, deps = {}) {
   SandboxStatus,
   SnapshotStatus,
   StdinMode,
+  TcpTunnel,
   createSandboxImage,
   dockerfileContent
 });