computesdk 2.0.0 → 2.0.2

package/dist/index.mjs

@@ -1,671 +1,4428 @@
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
+// src/client/protocol.ts
+var MessageType = /* @__PURE__ */ ((MessageType2) => {
+  MessageType2[MessageType2["Subscribe"] = 1] = "Subscribe";
+  MessageType2[MessageType2["Unsubscribe"] = 2] = "Unsubscribe";
+  MessageType2[MessageType2["Data"] = 3] = "Data";
+  MessageType2[MessageType2["Error"] = 4] = "Error";
+  MessageType2[MessageType2["Connected"] = 5] = "Connected";
+  return MessageType2;
+})(MessageType || {});
+var textEncoder = new TextEncoder();
+var textDecoder = new TextDecoder();
+function getValueSize(value) {
+  if (typeof value === "string") {
+    return textEncoder.encode(value).length;
+  } else if (typeof value === "number") {
+    return 8;
+  } else if (typeof value === "boolean") {
+    return 1;
+  } else if (value instanceof Uint8Array) {
+    return value.length;
+  }
+  return 0;
+}
+function encodeKeyValue(data) {
+  let totalSize = 2;
+  const fields = Object.entries(data);
+  for (const [key, value] of fields) {
+    const keyBytes = textEncoder.encode(key);
+    totalSize += 2;
+    totalSize += keyBytes.length;
+    totalSize += 1;
+    totalSize += 4;
+    totalSize += getValueSize(value);
+  }
+  const buffer = new Uint8Array(totalSize);
+  const view = new DataView(buffer.buffer);
+  let offset = 0;
+  view.setUint16(offset, fields.length, false);
+  offset += 2;
+  for (const [key, value] of fields) {
+    const keyBytes = textEncoder.encode(key);
+    view.setUint16(offset, keyBytes.length, false);
+    offset += 2;
+    buffer.set(keyBytes, offset);
+    offset += keyBytes.length;
+    if (typeof value === "string") {
+      buffer[offset] = 1 /* String */;
+      offset++;
+      const valueBytes = textEncoder.encode(value);
+      view.setUint32(offset, valueBytes.length, false);
+      offset += 4;
+      buffer.set(valueBytes, offset);
+      offset += valueBytes.length;
+    } else if (typeof value === "number") {
+      buffer[offset] = 2 /* Number */;
+      offset++;
+      view.setUint32(offset, 8, false);
+      offset += 4;
+      view.setFloat64(offset, value, false);
+      offset += 8;
+    } else if (typeof value === "boolean") {
+      buffer[offset] = 3 /* Boolean */;
+      offset++;
+      view.setUint32(offset, 1, false);
+      offset += 4;
+      buffer[offset] = value ? 1 : 0;
+      offset++;
+    } else if (value instanceof Uint8Array) {
+      buffer[offset] = 4 /* Bytes */;
+      offset++;
+      view.setUint32(offset, value.length, false);
+      offset += 4;
+      buffer.set(value, offset);
+      offset += value.length;
+    } else {
+      throw new Error(`Unsupported value type for key ${key}: ${typeof value}`);
+    }
+  }
+  return buffer;
+}
+function decodeKeyValue(data) {
+  if (data.length < 2) {
+    throw new Error("Data too short for key-value encoding");
+  }
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  const result = {};
+  let offset = 0;
+  const numFields = view.getUint16(offset, false);
+  offset += 2;
+  for (let i = 0; i < numFields; i++) {
+    if (offset + 2 > data.length) {
+      throw new Error(`Invalid key length at field ${i}`);
+    }
+    const keyLen = view.getUint16(offset, false);
+    offset += 2;
+    if (offset + keyLen > data.length) {
+      throw new Error(`Key data truncated at field ${i}`);
+    }
+    const key = textDecoder.decode(data.slice(offset, offset + keyLen));
+    offset += keyLen;
+    if (offset + 1 > data.length) {
+      throw new Error(`Invalid value type at field ${i}`);
+    }
+    const valueType = data[offset];
+    offset++;
+    if (offset + 4 > data.length) {
+      throw new Error(`Invalid value length at field ${i}`);
+    }
+    const valueLen = view.getUint32(offset, false);
+    offset += 4;
+    if (offset + valueLen > data.length) {
+      throw new Error(`Value data truncated at field ${i}`);
+    }
+    const valueData = data.slice(offset, offset + valueLen);
+    offset += valueLen;
+    switch (valueType) {
+      case 1 /* String */:
+        result[key] = textDecoder.decode(valueData);
+        break;
+      case 2 /* Number */:
+        if (valueData.length !== 8) {
+          throw new Error(`Invalid number length for field ${key}`);
+        }
+        const valueView = new DataView(valueData.buffer, valueData.byteOffset);
+        result[key] = valueView.getFloat64(0, false);
+        break;
+      case 3 /* Boolean */:
+        if (valueData.length !== 1) {
+          throw new Error(`Invalid boolean length for field ${key}`);
+        }
+        result[key] = valueData[0] !== 0;
+        break;
+      case 4 /* Bytes */:
+        result[key] = valueData;
+        break;
+      default:
+        throw new Error(`Unknown value type 0x${valueType.toString(16)} for field ${key}`);
+    }
+  }
+  return result;
+}
+function encodeBinaryMessage(message) {
+  let messageType;
+  let channel = "";
+  let msgType = "";
+  let data = {};
+  if (message.type === "subscribe") {
+    messageType = 1 /* Subscribe */;
+    channel = message.channel || "";
+    msgType = "subscribe";
+    data = {};
+  } else if (message.type === "unsubscribe") {
+    messageType = 2 /* Unsubscribe */;
+    channel = message.channel || "";
+    msgType = "unsubscribe";
+    data = {};
+  } else {
+    messageType = 3 /* Data */;
+    channel = message.channel || "";
+    msgType = message.type || "";
+    data = message.data || message;
+  }
+  const channelBytes = encodeUTF8(channel);
+  const msgTypeBytes = encodeUTF8(msgType);
+  let dataBytes;
+  if (data === void 0 || data === null) {
+    dataBytes = new Uint8Array(0);
+  } else if (typeof data === "string") {
+    dataBytes = encodeUTF8(data);
+  } else if (data instanceof Uint8Array) {
+    dataBytes = data;
+  } else if (typeof data === "object") {
+    dataBytes = encodeKeyValue(data);
+  } else {
+    throw new Error(`Unsupported data type: ${typeof data}`);
+  }
+  const totalSize = 1 + 2 + channelBytes.length + 2 + msgTypeBytes.length + 4 + dataBytes.length;
+  const buffer = new ArrayBuffer(totalSize);
+  const view = new DataView(buffer);
+  let offset = 0;
+  view.setUint8(offset, messageType);
+  offset += 1;
+  view.setUint16(offset, channelBytes.length, false);
+  offset += 2;
+  const uint8View = new Uint8Array(buffer);
+  uint8View.set(channelBytes, offset);
+  offset += channelBytes.length;
+  view.setUint16(offset, msgTypeBytes.length, false);
+  offset += 2;
+  uint8View.set(msgTypeBytes, offset);
+  offset += msgTypeBytes.length;
+  view.setUint32(offset, dataBytes.length, false);
+  offset += 4;
+  uint8View.set(dataBytes, offset);
+  return buffer;
+}
+function decodeBinaryMessage(buffer) {
+  const arrayBuffer = buffer instanceof Uint8Array ? buffer.buffer : buffer;
+  const view = new DataView(arrayBuffer);
+  const uint8View = new Uint8Array(arrayBuffer);
+  let offset = 0;
+  const messageType = view.getUint8(offset);
+  offset += 1;
+  const channelLength = view.getUint16(offset, false);
+  offset += 2;
+  const channelBytes = uint8View.slice(offset, offset + channelLength);
+  const channel = decodeUTF8(channelBytes);
+  offset += channelLength;
+  const msgTypeLength = view.getUint16(offset, false);
+  offset += 2;
+  const msgTypeBytes = uint8View.slice(offset, offset + msgTypeLength);
+  const msgType = decodeUTF8(msgTypeBytes);
+  offset += msgTypeLength;
+  const dataLength = view.getUint32(offset, false);
+  offset += 4;
+  const dataBytes = uint8View.slice(offset, offset + dataLength);
+  const shouldTryKeyValue = ["terminal:input", "terminal:resize", "file:changed", "terminal:output", "signal", "test"].includes(msgType);
+  let data;
+  if (dataBytes.length === 0) {
+    data = {};
+  } else if (shouldTryKeyValue) {
+    try {
+      data = decodeKeyValue(dataBytes);
+    } catch {
+      data = dataBytes;
+    }
+  } else {
+    data = dataBytes;
+  }
+  if (messageType === 1 /* Subscribe */ || messageType === 2 /* Unsubscribe */) {
+    return {
+      type: msgType,
+      channel
+    };
+  }
+  return {
+    type: msgType,
+    channel,
+    data
+  };
+}
+function encodeUTF8(str) {
+  if (typeof TextEncoder !== "undefined") {
+    const encoder = new TextEncoder();
+    return encoder.encode(str);
+  }
+  const utf8 = [];
+  for (let i = 0; i < str.length; i++) {
+    let charcode = str.charCodeAt(i);
+    if (charcode < 128) {
+      utf8.push(charcode);
+    } else if (charcode < 2048) {
+      utf8.push(192 | charcode >> 6, 128 | charcode & 63);
+    } else if (charcode < 55296 || charcode >= 57344) {
+      utf8.push(224 | charcode >> 12, 128 | charcode >> 6 & 63, 128 | charcode & 63);
+    } else {
+      i++;
+      charcode = 65536 + ((charcode & 1023) << 10 | str.charCodeAt(i) & 1023);
+      utf8.push(
+        240 | charcode >> 18,
+        128 | charcode >> 12 & 63,
+        128 | charcode >> 6 & 63,
+        128 | charcode & 63
+      );
+    }
+  }
+  return new Uint8Array(utf8);
+}
+function decodeUTF8(bytes) {
+  if (typeof TextDecoder !== "undefined") {
+    const decoder = new TextDecoder();
+    return decoder.decode(bytes);
+  }
+  let str = "";
+  let i = 0;
+  while (i < bytes.length) {
+    const c = bytes[i++];
+    if (c < 128) {
+      str += String.fromCharCode(c);
+    } else if (c < 224) {
+      str += String.fromCharCode((c & 31) << 6 | bytes[i++] & 63);
+    } else if (c < 240) {
+      str += String.fromCharCode((c & 15) << 12 | (bytes[i++] & 63) << 6 | bytes[i++] & 63);
+    } else {
+      const c2 = (c & 7) << 18 | (bytes[i++] & 63) << 12 | (bytes[i++] & 63) << 6 | bytes[i++] & 63;
+      const c3 = c2 - 65536;
+      str += String.fromCharCode(55296 | c3 >> 10, 56320 | c3 & 1023);
+    }
+  }
+  return str;
+}
+function isBinaryData(data) {
+  return data instanceof ArrayBuffer || data instanceof Uint8Array || data instanceof Blob;
+}
+async function blobToArrayBuffer(blob) {
+  if (blob.arrayBuffer) {
+    return blob.arrayBuffer();
+  }
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(reader.result);
+    reader.onerror = reject;
+    reader.readAsArrayBuffer(blob);
+  });
+}
+
+// src/client/websocket.ts
+var WebSocketManager = class {
+  constructor(config) {
+    this.ws = null;
+    this.eventHandlers = /* @__PURE__ */ new Map();
+    this.reconnectAttempts = 0;
+    this.reconnectTimer = null;
+    this.subscribedChannels = /* @__PURE__ */ new Set();
+    this.isManualClose = false;
+    this.config = {
+      url: config.url,
+      WebSocket: config.WebSocket,
+      autoReconnect: config.autoReconnect ?? true,
+      reconnectDelay: config.reconnectDelay ?? 1e3,
+      maxReconnectAttempts: config.maxReconnectAttempts ?? 5,
+      debug: config.debug ?? false,
+      protocol: config.protocol ?? "binary"
+    };
+  }
+  // ============================================================================
+  // Connection Management
+  // ============================================================================
+  /**
+   * Connect to WebSocket server
+   */
+  connect() {
+    return new Promise((resolve, reject) => {
+      try {
+        this.isManualClose = false;
+        this.log("Connecting to WebSocket URL:", this.config.url);
+        this.ws = new this.config.WebSocket(this.config.url);
+        this.ws.onopen = () => {
+          this.log("Connected to WebSocket server");
+          this.reconnectAttempts = 0;
+          if (this.subscribedChannels.size > 0) {
+            this.log("Resubscribing to channels:", Array.from(this.subscribedChannels));
+            this.subscribedChannels.forEach((channel) => {
+              this.sendRaw({ type: "subscribe", channel });
+            });
+          }
+          this.emit("open");
+          resolve();
+        };
+        this.ws.onmessage = async (event) => {
+          try {
+            let message;
+            if (this.config.protocol === "binary" && isBinaryData(event.data)) {
+              let buffer;
+              if (event.data instanceof Blob) {
+                buffer = await blobToArrayBuffer(event.data);
+              } else {
+                buffer = event.data;
+              }
+              message = decodeBinaryMessage(buffer);
+              this.log("Received binary message:", message);
+            } else {
+              message = JSON.parse(event.data);
+              this.log("Received JSON message:", message);
+            }
+            this.handleMessage(message);
+          } catch (error) {
+            this.log("Failed to parse message:", error);
+          }
+        };
+        this.ws.onerror = (error) => {
+          this.log("WebSocket error:", error);
+          this.emit("error", error);
+          reject(error);
+        };
+        this.ws.onclose = () => {
+          this.log("WebSocket connection closed");
+          this.emit("close");
+          if (this.config.autoReconnect && !this.isManualClose) {
+            this.attemptReconnect();
+          }
+        };
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+  /**
+   * Disconnect from WebSocket server
+   */
+  disconnect() {
+    this.isManualClose = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+  /**
+   * Check if WebSocket is connected
+   */
+  isConnected() {
+    return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+  }
+  /**
+   * Attempt to reconnect to WebSocket server
+   */
+  attemptReconnect() {
+    if (this.config.maxReconnectAttempts > 0 && this.reconnectAttempts >= this.config.maxReconnectAttempts) {
+      this.log("Max reconnection attempts reached");
+      this.emit("reconnect-failed");
+      return;
+    }
+    this.reconnectAttempts++;
+    this.log(`Reconnecting... (attempt ${this.reconnectAttempts})`);
+    this.reconnectTimer = setTimeout(() => {
+      this.connect().catch((error) => {
+        this.log("Reconnection failed:", error);
+      });
+    }, this.config.reconnectDelay);
+  }
+  // ============================================================================
+  // Channel Subscription
+  // ============================================================================
+  /**
+   * Subscribe to a channel
+   * @param channel - Channel name (e.g., 'terminal:term_abc123', 'watcher:watcher_xyz789', 'signals')
+   */
+  subscribe(channel) {
+    this.subscribedChannels.add(channel);
+    this.sendRaw({ type: "subscribe", channel });
+    this.log("Subscribed to channel:", channel);
+  }
+  /**
+   * Unsubscribe from a channel
+   */
+  unsubscribe(channel) {
+    this.subscribedChannels.delete(channel);
+    this.sendRaw({ type: "unsubscribe", channel });
+    this.log("Unsubscribed from channel:", channel);
+  }
+  /**
+   * Get list of subscribed channels
+   */
+  getSubscribedChannels() {
+    return Array.from(this.subscribedChannels);
+  }
+  // ============================================================================
+  // Message Sending
+  // ============================================================================
+  /**
+   * Send raw message to server
+   */
+  sendRaw(message) {
+    if (!this.isConnected()) {
+      throw new Error("WebSocket is not connected");
+    }
+    if (this.config.protocol === "binary") {
+      const buffer = encodeBinaryMessage(message);
+      this.ws.send(buffer);
+      this.log("Sent binary message:", message);
+    } else {
+      this.ws.send(JSON.stringify(message));
+      this.log("Sent JSON message:", message);
+    }
+  }
+  /**
+   * Send input to a terminal (sent as-is, not encoded)
+   */
+  sendTerminalInput(terminalId, input) {
+    this.sendRaw({
+      type: "terminal:input",
+      data: { terminal_id: terminalId, input }
+    });
+  }
+  /**
+   * Resize terminal window
+   */
+  resizeTerminal(terminalId, cols, rows) {
+    this.sendRaw({
+      type: "terminal:resize",
+      data: { terminal_id: terminalId, cols, rows }
+    });
+  }
+  /**
+   * Start a pending streaming command
+   * Used in two-phase streaming flow: HTTP request creates pending command,
+   * then this signal triggers execution after client has subscribed.
+   */
+  startCommand(cmdId) {
+    this.sendRaw({
+      type: "command:start",
+      data: { cmd_id: cmdId }
+    });
+  }
+  on(event, handler) {
+    if (!this.eventHandlers.has(event)) {
+      this.eventHandlers.set(event, /* @__PURE__ */ new Set());
+    }
+    this.eventHandlers.get(event).add(handler);
+  }
+  /**
+   * Unregister event handler
+   */
+  off(event, handler) {
+    const handlers = this.eventHandlers.get(event);
+    if (handlers) {
+      handlers.delete(handler);
+      if (handlers.size === 0) {
+        this.eventHandlers.delete(event);
+      }
+    }
+  }
+  /**
+   * Unregister all event handlers for an event
+   */
+  offAll(event) {
+    this.eventHandlers.delete(event);
+  }
+  /**
+   * Emit event to registered handlers
+   */
+  emit(event, data) {
+    const handlers = this.eventHandlers.get(event);
+    if (handlers) {
+      handlers.forEach((handler) => {
+        try {
+          handler(data);
+        } catch (error) {
+          this.log("Error in event handler:", error);
+        }
+      });
+    }
+  }
+  /**
+   * Handle incoming message
+   */
+  handleMessage(message) {
+    this.emit(message.type, message);
+    if ("channel" in message && message.channel) {
+      this.emit(message.channel, message);
+    }
+  }
+  // ============================================================================
+  // Utility Methods
+  // ============================================================================
+  /**
+   * Log debug message if debug mode is enabled
+   */
+  log(...args) {
+    if (this.config.debug) {
+      console.log("[WebSocketManager]", ...args);
+    }
+  }
+  /**
+   * Get current connection state
+   */
+  getState() {
+    if (!this.ws) return "closed";
+    switch (this.ws.readyState) {
+      case WebSocket.CONNECTING:
+        return "connecting";
+      case WebSocket.OPEN:
+        return "open";
+      case WebSocket.CLOSING:
+        return "closing";
+      case WebSocket.CLOSED:
+        return "closed";
+      default:
+        return "closed";
+    }
+  }
+  /**
+   * Get reconnection attempt count
+   */
+  getReconnectAttempts() {
+    return this.reconnectAttempts;
+  }
+};
+
+// src/client/resources/command.ts
+var Command = class {
+  constructor(data) {
+    this.id = data.cmdId;
+    this.terminalId = data.terminalId;
+    this.command = data.command;
+    this._status = data.status;
+    this._stdout = data.stdout;
+    this._stderr = data.stderr;
+    this._exitCode = data.exitCode;
+    this._durationMs = data.durationMs;
+    this._startedAt = data.startedAt;
+    this._finishedAt = data.finishedAt;
+  }
+  get status() {
+    return this._status;
+  }
+  get stdout() {
+    return this._stdout;
+  }
+  get stderr() {
+    return this._stderr;
+  }
+  get exitCode() {
+    return this._exitCode;
+  }
+  get durationMs() {
+    return this._durationMs;
+  }
+  get startedAt() {
+    return this._startedAt;
+  }
+  get finishedAt() {
+    return this._finishedAt;
+  }
+  /**
+   * Set the wait handler (called by TerminalCommands)
+   * @internal
+   */
+  setWaitHandler(handler) {
+    this.waitHandler = handler;
+  }
+  /**
+   * Set the retrieve handler (called by TerminalCommands)
+   * @internal
+   */
+  setRetrieveHandler(handler) {
+    this.retrieveHandler = handler;
+  }
+  /**
+   * Wait for the command to complete
+   * @param timeout - Optional timeout in seconds (0 = no timeout)
+   * @returns This command with updated status
+   */
+  async wait(timeout) {
+    if (!this.waitHandler) {
+      throw new Error("Wait handler not set");
+    }
+    const response = await this.waitHandler(timeout);
+    this.updateFromResponse(response);
+    return this;
+  }
+  /**
+   * Refresh the command status from the server
+   * @returns This command with updated status
+   */
+  async refresh() {
+    if (!this.retrieveHandler) {
+      throw new Error("Retrieve handler not set");
+    }
+    const response = await this.retrieveHandler();
+    this.updateFromResponse(response);
+    return this;
+  }
+  /**
+   * Update internal state from API response
+   */
+  updateFromResponse(response) {
+    this._status = response.data.status;
+    this._stdout = response.data.stdout;
+    this._stderr = response.data.stderr;
+    this._exitCode = response.data.exit_code;
+    this._durationMs = response.data.duration_ms;
+    this._finishedAt = response.data.finished_at;
+  }
+};
+
+// src/client/resources/terminal-command.ts
+var TerminalCommand = class {
+  constructor(terminalId, handlers) {
+    this.terminalId = terminalId;
+    this.runHandler = handlers.run;
+    this.listHandler = handlers.list;
+    this.retrieveHandler = handlers.retrieve;
+    this.waitHandler = handlers.wait;
+  }
+  /**
+   * Run a command in the terminal
+   * @param command - The command to execute
+   * @param options - Execution options
+   * @param options.background - If true, returns immediately without waiting for completion
+   * @returns Command object with results or status
+   */
+  async run(command, options) {
+    const response = await this.runHandler(command, options?.background);
+    const cmd = new Command({
+      cmdId: response.data.cmd_id || "",
+      terminalId: this.terminalId,
+      command: response.data.command,
+      status: response.data.status || (options?.background ? "running" : "completed"),
+      stdout: response.data.stdout,
+      stderr: response.data.stderr,
+      exitCode: response.data.exit_code,
+      durationMs: response.data.duration_ms,
+      startedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    cmd.setWaitHandler((timeout) => this.waitHandler(cmd.id, timeout));
+    cmd.setRetrieveHandler(() => this.retrieveHandler(cmd.id));
+    return cmd;
+  }
+  /**
+   * List all commands executed in this terminal
+   * @returns Array of Command objects
+   */
+  async list() {
+    const response = await this.listHandler();
+    return response.data.commands.map((item) => {
+      const cmd = new Command({
+        cmdId: item.cmd_id,
+        terminalId: this.terminalId,
+        command: item.command,
+        status: item.status,
+        stdout: "",
+        // Not included in list response
+        stderr: "",
+        // Not included in list response
+        exitCode: item.exit_code,
+        durationMs: item.duration_ms,
+        startedAt: item.started_at,
+        finishedAt: item.finished_at
+      });
+      cmd.setWaitHandler((timeout) => this.waitHandler(cmd.id, timeout));
+      cmd.setRetrieveHandler(() => this.retrieveHandler(cmd.id));
+      return cmd;
+    });
+  }
+  /**
+   * Retrieve a specific command by ID
+   * @param cmdId - The command ID
+   * @returns Command object with full details
+   */
+  async retrieve(cmdId) {
+    const response = await this.retrieveHandler(cmdId);
+    const cmd = new Command({
+      cmdId: response.data.cmd_id,
+      terminalId: this.terminalId,
+      command: response.data.command,
+      status: response.data.status,
+      stdout: response.data.stdout,
+      stderr: response.data.stderr,
+      exitCode: response.data.exit_code,
+      durationMs: response.data.duration_ms,
+      startedAt: response.data.started_at,
+      finishedAt: response.data.finished_at
+    });
+    cmd.setWaitHandler((timeout) => this.waitHandler(cmd.id, timeout));
+    cmd.setRetrieveHandler(() => this.retrieveHandler(cmd.id));
+    return cmd;
+  }
+};
+
+// src/client/terminal.ts
+function decodeBase64(str) {
+  if (typeof window !== "undefined" && typeof window.atob === "function") {
+    return window.atob(str);
+  } else if (typeof Buffer !== "undefined") {
+    return Buffer.from(str, "base64").toString("utf-8");
+  }
+  throw new Error("No base64 decoding available");
+}
+var TerminalInstance = class {
+  constructor(id, pty, status, channel, ws, encoding = "raw") {
+    this._eventHandlers = /* @__PURE__ */ new Map();
+    this._id = id;
+    this._pty = pty;
+    this._status = status === "active" ? "running" : status;
+    this._channel = channel;
+    this._ws = ws;
+    this._encoding = encoding;
+    this.command = new TerminalCommand(id, {
+      run: async (command, background) => {
+        if (!this._executeHandler) {
+          throw new Error("Execute handler not set");
+        }
+        return this._executeHandler(command, background);
+      },
+      list: async () => {
+        if (!this._listCommandsHandler) {
+          throw new Error("List commands handler not set");
+        }
+        return this._listCommandsHandler();
+      },
+      retrieve: async (cmdId) => {
+        if (!this._retrieveCommandHandler) {
+          throw new Error("Retrieve command handler not set");
+        }
+        return this._retrieveCommandHandler(cmdId);
+      },
+      wait: async (cmdId, timeout) => {
+        if (!this._waitCommandHandler) {
+          throw new Error("Wait command handler not set");
+        }
+        return this._waitCommandHandler(cmdId, timeout);
+      }
+    });
+    if (this._pty && this._ws && this._channel) {
+      this._ws.subscribe(this._channel);
+      this.setupWebSocketHandlers();
+    }
+  }
+  /**
+   * Set up WebSocket event handlers (PTY mode only)
+   */
+  setupWebSocketHandlers() {
+    if (!this._ws || !this._channel) {
+      return;
+    }
+    this._ws.on("terminal:output", (msg) => {
+      if (msg.channel === this._channel) {
+        const encoding = msg.data.encoding || this._encoding;
+        const output = encoding === "base64" ? decodeBase64(msg.data.output) : msg.data.output;
+        this.emit("output", output);
+      }
+    });
+    this._ws.on("terminal:error", (msg) => {
+      if (msg.channel === this._channel) {
+        this.emit("error", msg.data.error);
+      }
+    });
+    this._ws.on("terminal:destroyed", (msg) => {
+      if (msg.channel === this._channel) {
+        this._status = "stopped";
+        this.emit("destroyed");
+        this.cleanup();
+      }
+    });
+  }
+  /**
+   * Terminal ID
+   */
+  get id() {
+    return this._id;
+  }
+  /**
+   * Get terminal ID (deprecated, use .id property)
+   * @deprecated Use .id property instead
+   */
+  getId() {
+    return this._id;
+  }
+  /**
+   * Terminal status
+   */
+  get status() {
+    return this._status;
+  }
+  /**
+   * Get terminal status (deprecated, use .status property)
+   * @deprecated Use .status property instead
+   */
+  getStatus() {
+    return this._status;
+  }
+  /**
+   * Terminal channel (null for exec mode)
+   */
+  get channel() {
+    return this._channel;
+  }
+  /**
+   * Get terminal channel (deprecated, use .channel property)
+   * @deprecated Use .channel property instead
+   */
+  getChannel() {
+    return this._channel;
+  }
+  /**
+   * Whether this is a PTY terminal
+   */
+  get pty() {
+    return this._pty;
+  }
+  /**
+   * Get terminal PTY mode (deprecated, use .pty property)
+   * @deprecated Use .pty property instead
+   */
+  isPTY() {
+    return this._pty;
+  }
+  /**
+   * Check if terminal is running
+   */
+  isRunning() {
+    return this._status === "running";
+  }
+  /**
+   * Write input to the terminal (PTY mode only)
+   */
+  write(input) {
+    if (!this._pty) {
+      throw new Error("write() is only available for PTY terminals. Use commands.run() for exec mode terminals.");
+    }
+    if (!this._ws) {
+      throw new Error("WebSocket not available");
+    }
+    if (!this.isRunning()) {
+      console.warn('[Terminal] Warning: Terminal status is not "running", but attempting to write anyway. Status:', this._status);
+    }
+    this._ws.sendTerminalInput(this._id, input);
+  }
+  /**
+   * Resize terminal window (PTY mode only)
+   */
+  resize(cols, rows) {
+    if (!this._pty) {
+      throw new Error("resize() is only available for PTY terminals");
+    }
+    if (!this._ws) {
+      throw new Error("WebSocket not available");
+    }
+    if (!this.isRunning()) {
+      throw new Error("Terminal is not running");
+    }
+    this._ws.resizeTerminal(this._id, cols, rows);
+  }
+  /**
+   * Set execute command handler (called by Sandbox)
+   * @internal
+   */
+  setExecuteHandler(handler) {
+    this._executeHandler = handler;
+  }
+  /**
+   * Set list commands handler (called by Sandbox)
+   * @internal
+   */
+  setListCommandsHandler(handler) {
+    this._listCommandsHandler = handler;
+  }
+  /**
+   * Set retrieve command handler (called by Sandbox)
+   * @internal
+   */
+  setRetrieveCommandHandler(handler) {
+    this._retrieveCommandHandler = handler;
+  }
+  /**
+   * Set wait command handler (called by Sandbox)
+   * @internal
+   */
+  setWaitCommandHandler(handler) {
+    this._waitCommandHandler = handler;
+  }
+  /**
+   * Set destroy handler (called by Sandbox)
+   * @internal
+   */
+  setDestroyHandler(handler) {
+    this._destroyHandler = handler;
+  }
+  /**
+   * Execute a command in the terminal (deprecated, use command.run())
+   * @deprecated Use terminal.command.run() instead
+   */
+  async execute(command, options) {
+    if (!this._executeHandler) {
+      throw new Error("Execute handler not set");
+    }
+    return this._executeHandler(command, options?.background);
+  }
+  /**
+   * Destroy the terminal
+   */
+  async destroy() {
+    if (!this._destroyHandler) {
+      throw new Error("Destroy handler not set");
+    }
+    await this._destroyHandler();
+    this._status = "stopped";
+    this.cleanup();
+  }
+  /**
+   * Clean up resources
+   */
+  cleanup() {
+    if (this._ws && this._channel) {
+      this._ws.unsubscribe(this._channel);
+    }
+    this._eventHandlers.clear();
+  }
+  /**
+   * Register event handler
+   */
+  on(event, handler) {
+    if (!this._eventHandlers.has(event)) {
+      this._eventHandlers.set(event, /* @__PURE__ */ new Set());
+    }
+    this._eventHandlers.get(event).add(handler);
+  }
+  /**
+   * Unregister event handler
+   */
+  off(event, handler) {
+    const handlers = this._eventHandlers.get(event);
+    if (handlers) {
+      handlers.delete(handler);
+      if (handlers.size === 0) {
+        this._eventHandlers.delete(event);
+      }
+    }
+  }
+  /**
+   * Emit event to registered handlers
+   */
+  emit(event, ...args) {
+    const handlers = this._eventHandlers.get(event);
+    if (handlers) {
+      handlers.forEach((handler) => {
+        try {
+          handler(...args);
+        } catch (error) {
+          console.error("Error in terminal event handler:", error);
+        }
+      });
+    }
+  }
+};
 
-// src/errors.ts
-var ComputeError = class extends Error {
+// src/client/file-watcher.ts
+function decodeBase642(str) {
+  if (typeof window !== "undefined" && typeof window.atob === "function") {
+    return window.atob(str);
+  } else if (typeof Buffer !== "undefined") {
+    return Buffer.from(str, "base64").toString("utf-8");
+  }
+  throw new Error("No base64 decoding available");
+}
+var FileWatcher = class {
+  constructor(id, path, status, channel, includeContent, ignored, ws, encoding = "raw") {
+    this.eventHandlers = /* @__PURE__ */ new Map();
+    this.id = id;
+    this.path = path;
+    this.status = status;
+    this.channel = channel;
+    this.includeContent = includeContent;
+    this.ignored = ignored;
+    this.encoding = encoding;
+    this.ws = ws;
+    this.ws.subscribe(this.channel);
+    this.setupWebSocketHandlers();
+  }
+  /**
+   * Set up WebSocket event handlers
+   */
+  setupWebSocketHandlers() {
+    this.ws.on("file:changed", (msg) => {
+      if (msg.channel === this.channel) {
+        const encoding = msg.data.encoding || this.encoding;
+        const content = msg.data.content && encoding === "base64" ? decodeBase642(msg.data.content) : msg.data.content;
+        this.emit("change", {
+          event: msg.data.event,
+          path: msg.data.path,
+          content
+        });
+      }
+    });
+    this.ws.on("watcher:destroyed", (msg) => {
+      if (msg.channel === this.channel) {
+        this.status = "stopped";
+        this.emit("destroyed");
+        this.cleanup();
+      }
+    });
+  }
+  /**
+   * Get watcher ID
+   */
+  getId() {
+    return this.id;
+  }
+  /**
+   * Get watched path
+   */
+  getPath() {
+    return this.path;
+  }
+  /**
+   * Get watcher status
+   */
+  getStatus() {
+    return this.status;
+  }
+  /**
+   * Get watcher channel
+   */
+  getChannel() {
+    return this.channel;
+  }
+  /**
+   * Check if content is included in events
+   */
+  isIncludingContent() {
+    return this.includeContent;
+  }
+  /**
+   * Get ignored patterns
+   */
+  getIgnoredPatterns() {
+    return [...this.ignored];
+  }
+  /**
+   * Check if watcher is active
+   */
+  isActive() {
+    return this.status === "active";
+  }
+  /**
+   * Set destroy handler (called by client)
+   */
+  setDestroyHandler(handler) {
+    this.destroyWatcher = handler;
+  }
+  /**
+   * Destroy the watcher
+   */
+  async destroy() {
+    if (!this.destroyWatcher) {
+      throw new Error("Destroy handler not set");
+    }
+    await this.destroyWatcher();
+    this.cleanup();
+  }
+  /**
+   * Clean up resources
+   */
+  cleanup() {
+    this.ws.unsubscribe(this.channel);
+    this.eventHandlers.clear();
+  }
+  /**
+   * Register event handler
+   */
+  on(event, handler) {
+    if (!this.eventHandlers.has(event)) {
+      this.eventHandlers.set(event, /* @__PURE__ */ new Set());
+    }
+    this.eventHandlers.get(event).add(handler);
+  }
+  /**
+   * Unregister event handler
+   */
+  off(event, handler) {
+    const handlers = this.eventHandlers.get(event);
+    if (handlers) {
+      handlers.delete(handler);
+      if (handlers.size === 0) {
+        this.eventHandlers.delete(event);
+      }
+    }
+  }
+  /**
+   * Emit event to registered handlers
+   */
+  emit(event, ...args) {
+    const handlers = this.eventHandlers.get(event);
+    if (handlers) {
+      handlers.forEach((handler) => {
+        try {
+          handler(...args);
+        } catch (error) {
+          console.error("Error in file watcher event handler:", error);
+        }
+      });
+    }
+  }
+};
+
+// src/client/signal-service.ts
+var SignalService = class {
+  constructor(status, channel, ws) {
+    this.eventHandlers = /* @__PURE__ */ new Map();
+    this.status = status;
+    this.channel = channel;
+    this.ws = ws;
+    this.ws.subscribe(this.channel);
+    this.setupWebSocketHandlers();
+  }
+  /**
+   * Set up WebSocket event handlers
+   */
+  setupWebSocketHandlers() {
+    this.ws.on("signal", (msg) => {
+      if (msg.channel === this.channel) {
+        const event = {
+          signal: msg.data.signal,
+          ...msg.data.port && { port: msg.data.port },
+          ...msg.data.url && { url: msg.data.url },
+          ...msg.data.message && { message: msg.data.message }
+        };
+        if (msg.data.signal === "port" || msg.data.signal === "server-ready") {
+          this.emit("port", event);
+        } else if (msg.data.signal === "error") {
+          this.emit("error", event);
+        }
+        this.emit("signal", event);
+      }
+    });
+  }
+  /**
+   * Get service status
+   */
+  getStatus() {
+    return this.status;
+  }
+  /**
+   * Get service channel
+   */
+  getChannel() {
+    return this.channel;
+  }
+  /**
+   * Check if service is active
+   */
+  isActive() {
+    return this.status === "active";
+  }
+  /**
+   * Set stop handler (called by client)
+   */
+  setStopHandler(handler) {
+    this.stopService = handler;
+  }
+  /**
+   * Stop the signal service
+   */
+  async stop() {
+    if (!this.stopService) {
+      throw new Error("Stop handler not set");
+    }
+    await this.stopService();
+    this.cleanup();
+  }
+  /**
+   * Clean up resources
+   */
+  cleanup() {
+    this.status = "stopped";
+    this.ws.unsubscribe(this.channel);
+    this.eventHandlers.clear();
+  }
+  /**
+   * Register event handler
+   */
+  on(event, handler) {
+    if (!this.eventHandlers.has(event)) {
+      this.eventHandlers.set(event, /* @__PURE__ */ new Set());
+    }
+    this.eventHandlers.get(event).add(handler);
+  }
+  /**
+   * Unregister event handler
+   */
+  off(event, handler) {
+    const handlers = this.eventHandlers.get(event);
+    if (handlers) {
+      handlers.delete(handler);
+      if (handlers.size === 0) {
+        this.eventHandlers.delete(event);
+      }
+    }
+  }
+  /**
+   * Emit event to registered handlers
+   */
+  emit(event, ...args) {
+    const handlers = this.eventHandlers.get(event);
+    if (handlers) {
+      handlers.forEach((handler) => {
+        try {
+          handler(...args);
+        } catch (error) {
+          console.error("Error in signal service event handler:", error);
+        }
+      });
+    }
+  }
+};
+
+// src/client/index.ts
+import { escapeArgs, mkdir, test } from "@computesdk/cmd";
+
+// src/client/resources/terminal.ts
+var Terminal = class {
+  constructor(handlers) {
+    this.createHandler = handlers.create;
+    this.listHandler = handlers.list;
+    this.retrieveHandler = handlers.retrieve;
+    this.destroyHandler = handlers.destroy;
+  }
+  /**
+   * Create a new terminal session
+   *
+   * @param options - Terminal creation options
+   * @param options.shell - Shell to use (e.g., '/bin/bash') - PTY mode only
+   * @param options.encoding - Encoding: 'raw' (default) or 'base64' (binary-safe)
+   * @param options.pty - Terminal mode: true = PTY (interactive), false = exec (command tracking)
+   * @returns TerminalInstance
+   */
+  async create(options) {
+    return this.createHandler(options);
+  }
+  /**
+   * List all active terminals
+   * @returns Array of terminal responses
+   */
+  async list() {
+    return this.listHandler();
+  }
+  /**
+   * Retrieve a specific terminal by ID
+   * @param id - The terminal ID
+   * @returns Terminal instance
+   */
+  async retrieve(id) {
+    return this.retrieveHandler(id);
+  }
+  /**
+   * Destroy a terminal by ID
+   * @param id - The terminal ID
+   */
+  async destroy(id) {
+    return this.destroyHandler(id);
+  }
+};
+
+// src/client/resources/server.ts
+var Server = class {
+  constructor(handlers) {
+    this.startHandler = handlers.start;
+    this.listHandler = handlers.list;
+    this.retrieveHandler = handlers.retrieve;
+    this.stopHandler = handlers.stop;
+    this.deleteHandler = handlers.delete;
+    this.restartHandler = handlers.restart;
+    this.updateStatusHandler = handlers.updateStatus;
+    this.logsHandler = handlers.logs;
+  }
+  /**
+   * Start a new managed server with optional supervisor settings
+   *
+   * **Install Phase:**
+   * If `install` is provided, it runs blocking before `start` (e.g., "npm install").
+   * The server status will be `installing` during this phase.
+   *
+   * **Restart Policies:**
+   * - `never` (default): No automatic restart on exit
+   * - `on-failure`: Restart only on non-zero exit code
+   * - `always`: Always restart on exit (including exit code 0)
+   *
+   * **Graceful Shutdown:**
+   * When stopping a server, it first sends SIGTERM and waits for `stop_timeout_ms`
+   * before sending SIGKILL if the process hasn't exited.
+   *
+   * @param options - Server configuration
+   * @returns Server info
+   *
+   * @example
+   * ```typescript
+   * // Basic server
+   * const server = await sandbox.server.start({
+   *   slug: 'web',
+   *   start: 'npm run dev',
+   *   path: '/app',
+   * });
+   *
+   * // With install command
+   * const server = await sandbox.server.start({
+   *   slug: 'api',
+   *   install: 'npm install',
+   *   start: 'node server.js',
+   *   environment: { NODE_ENV: 'production' },
+   *   restart_policy: 'always',
+   *   max_restarts: 0, // unlimited
+   * });
+   * ```
+   */
+  async start(options) {
+    const response = await this.startHandler(options);
+    return response.data.server;
+  }
+  /**
+   * List all managed servers
+   * @returns Array of server info
+   */
+  async list() {
+    const response = await this.listHandler();
+    return response.data.servers;
+  }
+  /**
+   * Retrieve a specific server by slug
+   * @param slug - The server slug
+   * @returns Server info
+   */
+  async retrieve(slug) {
+    const response = await this.retrieveHandler(slug);
+    return response.data.server;
+  }
+  /**
+   * Stop a server by slug (non-destructive)
+   * @param slug - The server slug
+   */
+  async stop(slug) {
+    await this.stopHandler(slug);
+  }
+  /**
+   * Delete a server config by slug (stops + removes persistence)
+   * @param slug - The server slug
+   */
+  async delete(slug) {
+    await this.deleteHandler(slug);
+  }
+  /**
+   * Restart a server by slug
+   * @param slug - The server slug
+   * @returns Server info
+   */
+  async restart(slug) {
+    const response = await this.restartHandler(slug);
+    return response.data.server;
+  }
+  /**
+   * Update server status (internal use)
+   * @param slug - The server slug
+   * @param status - New status
+   */
+  async updateStatus(slug, status) {
+    await this.updateStatusHandler(slug, status);
+  }
+  /**
+   * Retrieve captured output (logs) for a managed server
+   * @param slug - The server slug
+   * @param options - Options for log retrieval
+   * @returns Server logs info
+   *
+   * @example
+   * ```typescript
+   * // Get combined logs (default)
+   * const logs = await sandbox.server.logs('api');
+   * console.log(logs.logs);
+   *
+   * // Get only stdout
+   * const stdout = await sandbox.server.logs('api', { stream: 'stdout' });
+   *
+   * // Get only stderr
+   * const stderr = await sandbox.server.logs('api', { stream: 'stderr' });
+   * ```
+   */
+  async logs(slug, options) {
+    const response = await this.logsHandler(slug, options);
+    return response.data;
+  }
+};
+
+// src/client/resources/watcher.ts
+var Watcher = class {
+  constructor(handlers) {
+    this.createHandler = handlers.create;
+    this.listHandler = handlers.list;
+    this.retrieveHandler = handlers.retrieve;
+    this.destroyHandler = handlers.destroy;
+  }
+  /**
+   * Create a new file watcher
+   * @param path - Path to watch
+   * @param options - Watcher options
+   * @param options.includeContent - Include file content in change events
+   * @param options.ignored - Patterns to ignore
+   * @param options.encoding - Encoding: 'raw' (default) or 'base64' (binary-safe)
+   * @returns FileWatcher instance
+   */
+  async create(path, options) {
+    return this.createHandler(path, options);
+  }
+  /**
+   * List all active file watchers
+   * @returns Array of watcher info
+   */
+  async list() {
+    const response = await this.listHandler();
+    return response.data.watchers;
+  }
+  /**
+   * Retrieve a specific watcher by ID
+   * @param id - The watcher ID
+   * @returns Watcher info
+   */
+  async retrieve(id) {
+    const response = await this.retrieveHandler(id);
+    return response.data;
+  }
+  /**
+   * Destroy a watcher by ID
+   * @param id - The watcher ID
+   */
+  async destroy(id) {
+    return this.destroyHandler(id);
+  }
+};
+
+// src/client/resources/session-token.ts
+var SessionToken = class {
+  constructor(handlers) {
+    this.createHandler = handlers.create;
+    this.listHandler = handlers.list;
+    this.retrieveHandler = handlers.retrieve;
+    this.revokeHandler = handlers.revoke;
+  }
+  /**
+   * Create a new session token (requires access token)
+   * @param options - Token configuration
+   * @param options.description - Description for the token
+   * @param options.expiresIn - Expiration time in seconds (default: 7 days)
+   * @returns Session token info including the token value
+   */
+  async create(options) {
+    const response = await this.createHandler(options);
+    return {
+      id: response.id,
+      token: response.token,
+      description: response.description,
+      createdAt: response.createdAt,
+      expiresAt: response.expiresAt
+    };
+  }
+  /**
+   * List all session tokens
+   * @returns Array of session token info
+   */
+  async list() {
+    const response = await this.listHandler();
+    return response.data.tokens.map((t) => ({
+      id: t.id,
+      description: t.description,
+      createdAt: t.created_at,
+      expiresAt: t.expires_at,
+      lastUsedAt: t.last_used_at
+    }));
+  }
+  /**
+   * Retrieve a specific session token by ID
+   * @param id - The token ID
+   * @returns Session token info
+   */
+  async retrieve(id) {
+    const response = await this.retrieveHandler(id);
+    return {
+      id: response.id,
+      description: response.description,
+      createdAt: response.createdAt,
+      expiresAt: response.expiresAt
+    };
+  }
+  /**
+   * Revoke a session token
+   * @param id - The token ID to revoke
+   */
+  async revoke(id) {
+    return this.revokeHandler(id);
+  }
+};
+
+// src/client/resources/magic-link.ts
+var MagicLink = class {
+  constructor(handlers) {
+    this.createHandler = handlers.create;
+  }
+  /**
+   * Create a magic link for browser authentication (requires access token)
+   *
+   * Magic links are one-time URLs that automatically create a session token
+   * and set it as a cookie in the user's browser.
+   *
+   * @param options - Magic link configuration
+   * @param options.redirectUrl - URL to redirect to after authentication
+   * @returns Magic link info including the URL
+   */
+  async create(options) {
+    const response = await this.createHandler(options);
+    return {
+      url: response.data.magic_url,
+      expiresAt: response.data.expires_at,
+      redirectUrl: response.data.redirect_url
+    };
+  }
+};
+
+// src/client/resources/signal.ts
+var Signal = class {
+  constructor(handlers) {
+    this.startHandler = handlers.start;
+    this.statusHandler = handlers.status;
+    this.stopHandler = handlers.stop;
+    this.emitPortHandler = handlers.emitPort;
+    this.emitErrorHandler = handlers.emitError;
+    this.emitServerReadyHandler = handlers.emitServerReady;
+  }
+  /**
+   * Start the signal service
+   * @returns SignalService instance with event handling
+   */
+  async start() {
+    return this.startHandler();
+  }
+  /**
+   * Get the signal service status
+   * @returns Signal service status info
+   */
+  async status() {
+    const response = await this.statusHandler();
+    return {
+      status: response.data.status,
+      channel: response.data.channel,
+      wsUrl: response.data.ws_url
+    };
+  }
+  /**
+   * Stop the signal service
+   */
+  async stop() {
+    return this.stopHandler();
+  }
+  /**
+   * Emit a port signal
+   * @param port - Port number
+   * @param type - Signal type ('open' or 'close')
+   * @param url - URL associated with the port
+   */
+  async emitPort(port, type, url) {
+    await this.emitPortHandler(port, type, url);
+  }
+  /**
+   * Emit an error signal
+   * @param message - Error message
+   */
+  async emitError(message) {
+    await this.emitErrorHandler(message);
+  }
+  /**
+   * Emit a server ready signal
+   * @param port - Port number
+   * @param url - Server URL
+   */
+  async emitServerReady(port, url) {
+    await this.emitServerReadyHandler(port, url);
+  }
+};
+
+// src/client/resources/file.ts
+var File = class {
+  constructor(handlers) {
+    this.createHandler = handlers.create;
+    this.listHandler = handlers.list;
+    this.retrieveHandler = handlers.retrieve;
+    this.destroyHandler = handlers.destroy;
+    this.batchWriteHandler = handlers.batchWrite;
+    this.existsHandler = handlers.exists;
+  }
+  /**
+   * Create a new file with optional content
+   * @param path - File path
+   * @param content - File content (optional)
+   * @returns File info
+   */
+  async create(path, content) {
+    const response = await this.createHandler(path, content);
+    return response.data.file;
+  }
+  /**
+   * List files at the specified path
+   * @param path - Directory path (default: '/')
+   * @returns Array of file info
+   */
+  async list(path = "/") {
+    const response = await this.listHandler(path);
+    return response.data.files;
+  }
+  /**
+   * Retrieve file content
+   * @param path - File path
+   * @returns File content as string
+   */
+  async retrieve(path) {
+    return this.retrieveHandler(path);
+  }
+  /**
+   * Destroy (delete) a file or directory
+   * @param path - File or directory path
+   */
+  async destroy(path) {
+    return this.destroyHandler(path);
+  }
+  /**
+   * Batch file operations (write or delete multiple files)
+   *
+   * Features:
+   * - Deduplication: Last operation wins per path
+   * - File locking: Prevents race conditions
+   * - Deterministic ordering: Alphabetical path sorting
+   * - Partial failure handling: Returns per-file results
+   *
+   * @param files - Array of file operations
+   * @returns Results for each file operation
+   */
+  async batchWrite(files) {
+    const response = await this.batchWriteHandler(files);
+    return response.data.results;
+  }
+  /**
+   * Check if a file exists
+   * @param path - File path
+   * @returns True if file exists
+   */
+  async exists(path) {
+    return this.existsHandler(path);
+  }
+};
+
+// src/client/resources/env.ts
+var Env = class {
+  constructor(handlers) {
+    this.retrieveHandler = handlers.retrieve;
+    this.updateHandler = handlers.update;
+    this.removeHandler = handlers.remove;
+    this.existsHandler = handlers.exists;
+  }
+  /**
+   * Retrieve environment variables from a file
+   * @param file - Path to the .env file (relative to sandbox root)
+   * @returns Key-value map of environment variables
+   */
+  async retrieve(file) {
+    const response = await this.retrieveHandler(file);
+    return response.data.variables;
+  }
+  /**
+   * Update (merge) environment variables in a file
+   * @param file - Path to the .env file (relative to sandbox root)
+   * @param variables - Key-value pairs to set
+   * @returns Keys that were updated
+   */
+  async update(file, variables) {
+    const response = await this.updateHandler(file, variables);
+    return response.data.keys;
+  }
+  /**
+   * Remove environment variables from a file
+   * @param file - Path to the .env file (relative to sandbox root)
+   * @param keys - Keys to remove
+   * @returns Keys that were removed
+   */
+  async remove(file, keys) {
+    const response = await this.removeHandler(file, keys);
+    return response.data.keys;
+  }
+  /**
+   * Check if an environment file exists
+   * @param file - Path to the .env file (relative to sandbox root)
+   * @returns True if file exists
+   */
+  async exists(file) {
+    return this.existsHandler(file);
+  }
+};
+
+// src/client/resources/auth.ts
+var Auth = class {
+  constructor(handlers) {
+    this.statusHandler = handlers.status;
+    this.infoHandler = handlers.info;
+  }
+  /**
+   * Check authentication status
+   * @returns Authentication status info
+   */
+  async status() {
+    const response = await this.statusHandler();
+    return {
+      authenticated: response.data.authenticated,
+      tokenType: response.data.token_type,
+      expiresAt: response.data.expires_at
+    };
+  }
+  /**
+   * Get authentication information and usage instructions
+   * @returns Authentication info
+   */
+  async info() {
+    const response = await this.infoHandler();
+    return {
+      message: response.data.message,
+      instructions: response.data.instructions,
+      endpoints: {
+        createSessionToken: response.data.endpoints.create_session_token,
+        listSessionTokens: response.data.endpoints.list_session_tokens,
+        getSessionToken: response.data.endpoints.get_session_token,
+        revokeSessionToken: response.data.endpoints.revoke_session_token,
+        createMagicLink: response.data.endpoints.create_magic_link,
+        authStatus: response.data.endpoints.auth_status,
+        authInfo: response.data.endpoints.auth_info
+      }
+    };
+  }
+};
+
+// src/client/resources/run.ts
+var Run = class {
+  constructor(handlers) {
+    this.codeHandler = handlers.code;
+    this.commandHandler = handlers.command;
+    this.waitHandler = handlers.wait;
+  }
+  /**
+   * Execute code with automatic language detection
+   *
+   * Supports: python, python3, node, javascript, js, bash, sh, ruby
+   *
+   * @param code - The code to execute
+   * @param options - Execution options
+   * @param options.language - Programming language (auto-detected if not specified)
+   * @returns Code execution result with output, exit code, and detected language
+   */
+  async code(code, options) {
+    return this.codeHandler(code, options);
+  }
+  /**
+   * Execute a shell command
+   *
+   * @param command - The command to execute
+   * @param options - Execution options
+   * @param options.shell - Shell to use (optional)
+   * @param options.background - Run in background (optional)
+   * @param options.cwd - Working directory for the command (optional)
+   * @param options.env - Environment variables (optional)
+   * @param options.waitForCompletion - If true (with background), wait for command to complete
+   * @returns Command execution result with stdout, stderr, exit code, and duration
+   */
+  async command(command, options) {
+    const result = await this.commandHandler(command, options);
+    if (options?.background && options?.waitForCompletion && result.cmdId && result.terminalId) {
+      if (!this.waitHandler) {
+        throw new Error("Wait handler not configured");
+      }
+      const waitOptions = typeof options.waitForCompletion === "object" ? options.waitForCompletion : void 0;
+      return this.waitHandler(result.terminalId, result.cmdId, waitOptions);
+    }
+    return result;
+  }
+  /**
+   * Wait for a background command to complete
+   *
+   * Uses the configured wait handler to block until the command
+   * is complete or fails (typically via server-side long-polling).
+   * Throws an error if the command fails or times out.
+   *
+   * @param terminalId - Terminal ID from background command result
+   * @param cmdId - Command ID from background command result
+   * @param options - Wait options passed to the handler
+   * @returns Command result with final status
+   * @throws Error if command fails or times out
+   */
+  async waitForCompletion(terminalId, cmdId, options) {
+    if (!this.waitHandler) {
+      throw new Error("Wait handler not configured");
+    }
+    return this.waitHandler(terminalId, cmdId, options);
+  }
+};
+
+// src/client/resources/child.ts
+var Child = class {
+  constructor(handlers) {
+    this.createHandler = handlers.create;
+    this.listHandler = handlers.list;
+    this.retrieveHandler = handlers.retrieve;
+    this.destroyHandler = handlers.destroy;
+  }
+  /**
+   * Create a new child sandbox
+   * @returns Child sandbox info including URL and subdomain
+   */
+  async create(options) {
+    return this.createHandler(options);
+  }
+  /**
+   * List all child sandboxes
+   * @returns Array of child sandbox info
+   */
+  async list() {
+    const response = await this.listHandler();
+    return response.sandboxes;
+  }
+  /**
+   * Retrieve a specific child sandbox by subdomain
+   * @param subdomain - The child subdomain (e.g., 'sandbox-12345')
+   * @returns Child sandbox info
+   */
+  async retrieve(subdomain) {
+    return this.retrieveHandler(subdomain);
+  }
+  /**
+   * Destroy (delete) a child sandbox
+   * @param subdomain - The child subdomain
+   * @param options - Destroy options
+   * @param options.deleteFiles - Whether to delete the child's files (default: false)
+   */
+  async destroy(subdomain, options) {
+    return this.destroyHandler(subdomain, options?.deleteFiles ?? false);
+  }
+};
+
+// src/client/resources/overlay.ts
+var Overlay = class {
+  constructor(handlers) {
+    this.createHandler = handlers.create;
+    this.listHandler = handlers.list;
+    this.retrieveHandler = handlers.retrieve;
+    this.destroyHandler = handlers.destroy;
+  }
+  /**
+   * Create a new overlay from a template directory
+   *
+   * The overlay copies files from the source directory into the target path
+   * for better isolation. Heavy directories (node_modules, .venv, etc.) are
+   * copied in the background. Use the `ignore` option to exclude files/directories.
+   *
+   * @param options - Overlay creation options
+   * @param options.source - Absolute path to source directory
+   * @param options.target - Relative path in sandbox
+   * @param options.ignore - Glob patterns to ignore (e.g., ["node_modules", "*.log"])
+   * @param options.strategy - Strategy to use ('copy' or 'smart')
+   * @param options.waitForCompletion - If true or options object, wait for background copy to complete
+   * @returns Overlay info with copy status
+   */
+  async create(options) {
+    const response = await this.createHandler(options);
+    const overlay = this.toOverlayInfo(response);
+    if (options.waitForCompletion) {
+      const waitOptions = typeof options.waitForCompletion === "object" ? options.waitForCompletion : void 0;
+      return this.waitForCompletion(overlay.id, waitOptions);
+    }
+    return overlay;
+  }
+  /**
+   * List all overlays for the current sandbox
+   * @returns Array of overlay info
+   */
+  async list() {
+    const response = await this.listHandler();
+    return response.overlays.map((o) => this.toOverlayInfo(o));
+  }
+  /**
+   * Retrieve a specific overlay by ID
+   *
+   * Useful for polling the copy status of an overlay.
+   *
+   * @param id - Overlay ID
+   * @returns Overlay info
+   */
+  async retrieve(id) {
+    const response = await this.retrieveHandler(id);
+    return this.toOverlayInfo(response);
+  }
+  /**
+   * Destroy (delete) an overlay
+   * @param id - Overlay ID
+   */
+  async destroy(id) {
+    return this.destroyHandler(id);
+  }
+  /**
+   * Wait for an overlay's background copy to complete
+   *
+   * Polls the overlay status with exponential backoff until the copy
+   * is complete or fails. Throws an error if the copy fails or times out.
+   *
+   * @param id - Overlay ID
+   * @param options - Polling options
+   * @returns Overlay info with final copy status
+   * @throws Error if copy fails or times out
+   */
+  async waitForCompletion(id, options = {}) {
+    const maxRetries = options.maxRetries ?? 60;
+    const initialDelayMs = options.initialDelayMs ?? 500;
+    const maxDelayMs = options.maxDelayMs ?? 5e3;
+    const backoffFactor = options.backoffFactor ?? 1.5;
+    let currentDelay = initialDelayMs;
+    for (let i = 0; i < maxRetries; i++) {
+      const overlay = await this.retrieve(id);
+      if (overlay.copyStatus === "complete") {
+        return overlay;
+      }
+      if (overlay.copyStatus === "failed") {
+        throw new Error(
+          `Overlay copy failed: ${overlay.copyError || "Unknown error"}
+Overlay ID: ${id}`
+        );
+      }
+      if (i < maxRetries - 1) {
+        await new Promise((resolve) => setTimeout(resolve, currentDelay));
+        currentDelay = Math.min(currentDelay * backoffFactor, maxDelayMs);
+      }
+    }
+    const finalOverlay = await this.retrieve(id);
+    throw new Error(
+      `Overlay copy timed out after ${maxRetries} attempts.
+Overlay ID: ${id}
+Current status: ${finalOverlay.copyStatus}
+
+Try increasing maxRetries or check if the source directory is very large.`
+    );
+  }
+  /**
+   * Convert API response to OverlayInfo
+   */
+  toOverlayInfo(response) {
+    return {
+      id: response.id,
+      source: response.source,
+      target: response.target,
+      strategy: this.validateStrategy(response.strategy),
+      createdAt: response.created_at,
+      stats: {
+        copiedFiles: response.stats.copied_files,
+        copiedDirs: response.stats.copied_dirs,
+        skipped: response.stats.skipped
+      },
+      copyStatus: this.validateCopyStatus(response.copy_status),
+      copyError: response.copy_error
+    };
+  }
+  /**
+   * Validate and return strategy, defaulting to 'copy' for unknown/missing values (legacy support)
+   */
+  validateStrategy(strategy) {
+    const validStrategies = ["copy", "smart"];
+    if (strategy && validStrategies.includes(strategy)) {
+      return strategy;
+    }
+    return "copy";
+  }
+  /**
+   * Validate and return copy status, defaulting to 'pending' for unknown values
+   */
+  validateCopyStatus(status) {
+    const validStatuses = ["pending", "in_progress", "complete", "failed"];
+    if (validStatuses.includes(status)) {
+      return status;
+    }
+    return "pending";
+  }
+};
+
+// src/client/types.ts
+var CommandExitError = class extends Error {
+  constructor(result) {
+    super(`Command exited with code ${result.exitCode}`);
+    this.result = result;
+    this.name = "CommandExitError";
+  }
+};
+function isCommandExitError(error) {
+  return typeof error === "object" && error !== null && "name" in error && error.name === "CommandExitError" && "result" in error;
+}
+
+// src/client/index.ts
+var MAX_TUNNEL_TIMEOUT_SECONDS = 300;
+var Sandbox = class {
+  constructor(config) {
+    this._token = null;
+    this._ws = null;
+    this._terminals = /* @__PURE__ */ new Map();
+    this.sandboxId = config.sandboxId;
+    this.provider = config.provider;
+    let sandboxUrlResolved = config.sandboxUrl;
+    let tokenFromUrl = null;
+    let sandboxUrlFromUrl = null;
+    if (typeof window !== "undefined" && window.location && typeof localStorage !== "undefined") {
+      const params = new URLSearchParams(window.location.search);
+      tokenFromUrl = params.get("session_token");
+      sandboxUrlFromUrl = params.get("sandbox_url");
+      let urlChanged = false;
+      if (tokenFromUrl) {
+        params.delete("session_token");
+        localStorage.setItem("session_token", tokenFromUrl);
+        urlChanged = true;
+      }
+      if (sandboxUrlFromUrl) {
+        params.delete("sandbox_url");
+        localStorage.setItem("sandbox_url", sandboxUrlFromUrl);
+        urlChanged = true;
+      }
+      if (urlChanged) {
+        const search = params.toString() ? `?${params.toString()}` : "";
+        const newUrl = `${window.location.pathname}${search}${window.location.hash}`;
+        window.history.replaceState({}, "", newUrl);
+      }
+      if (!config.sandboxUrl) {
+        sandboxUrlResolved = sandboxUrlFromUrl || localStorage.getItem("sandbox_url") || "";
+      }
+    }
+    this.config = {
+      sandboxUrl: (sandboxUrlResolved || "").replace(/\/$/, ""),
+      // Remove trailing slash
+      sandboxId: config.sandboxId || "",
+      provider: config.provider || "",
+      token: config.token || "",
+      headers: config.headers || {},
+      timeout: config.timeout || 3e4,
+      protocol: config.protocol || "binary",
+      metadata: config.metadata,
+      destroyHandler: config.destroyHandler
+    };
+    this.WebSocketImpl = config.WebSocket || globalThis.WebSocket;
+    if (!this.WebSocketImpl) {
+      throw new Error(
+        'WebSocket is not available. In Node.js, pass WebSocket implementation:\nimport WebSocket from "ws";\nnew Sandbox({ sandboxUrl: "...", WebSocket })'
+      );
+    }
+    if (config.token) {
+      this._token = config.token;
+    } else if (tokenFromUrl) {
+      this._token = tokenFromUrl;
+    } else if (typeof window !== "undefined" && typeof localStorage !== "undefined") {
+      this._token = localStorage.getItem("session_token");
+    }
+    this.filesystem = {
+      readFile: async (path) => this.readFile(path),
+      writeFile: async (path, content) => {
+        await this.writeFile(path, content);
+      },
+      mkdir: async (path) => {
+        await this.runCommand(escapeArgs(mkdir(path)));
+      },
+      readdir: async (path) => {
+        const response = await this.listFiles(path);
+        return response.data.files.map((f) => ({
+          name: f.name,
+          type: f.is_dir ? "directory" : "file",
+          size: f.size,
+          modified: new Date(f.modified_at)
+        }));
+      },
+      exists: async (path) => {
+        const result = await this.runCommand(escapeArgs(test.exists(path)));
+        return result.exitCode === 0;
+      },
+      remove: async (path) => {
+        await this.deleteFile(path);
+      },
+      overlay: new Overlay({
+        create: async (options) => this.createOverlay(options),
+        list: async () => this.listOverlays(),
+        retrieve: async (id) => this.getOverlay(id),
+        destroy: async (id) => this.deleteOverlay(id)
+      })
+    };
+    this.terminal = new Terminal({
+      create: async (options) => this.createTerminal(options),
+      list: async () => this.listTerminals(),
+      retrieve: async (id) => this.getTerminal(id),
+      destroy: async (id) => {
+        await this.request(`/terminals/${id}`, { method: "DELETE" });
+      }
+    });
+    this.run = new Run({
+      code: async (code, options) => {
+        const result = await this.runCodeRequest(code, options?.language);
+        return {
+          output: result.data.output,
+          exitCode: result.data.exit_code,
+          language: result.data.language
+        };
+      },
+      command: async (command, options) => {
+        const result = await this.runCommandRequest({
+          command,
+          shell: options?.shell,
+          background: options?.background,
+          cwd: options?.cwd,
+          env: options?.env
+        });
+        return {
+          stdout: result.data.stdout,
+          stderr: result.data.stderr,
+          exitCode: result.data.exit_code ?? 0,
+          durationMs: result.data.duration_ms ?? 0,
+          // Include cmdId and terminalId for background commands
+          cmdId: result.data.cmd_id,
+          terminalId: result.data.terminal_id,
+          status: result.data.status
+        };
+      },
+      wait: async (terminalId, cmdId, options) => {
+        return this.waitForCommandCompletion(terminalId, cmdId, options);
+      }
+    });
+    this.server = new Server({
+      start: async (options) => this.startServer(options),
+      list: async () => this.listServers(),
+      retrieve: async (slug) => this.getServer(slug),
+      stop: async (slug) => {
+        await this.stopServer(slug);
+      },
+      delete: async (slug) => {
+        await this.deleteServer(slug);
+      },
+      restart: async (slug) => this.restartServer(slug),
+      updateStatus: async (slug, status) => {
+        await this.updateServerStatus(slug, status);
+      },
+      logs: async (slug, options) => this.getServerLogs(slug, options)
+    });
+    this.watcher = new Watcher({
+      create: async (path, options) => this.createWatcher(path, options),
+      list: async () => this.listWatchers(),
+      retrieve: async (id) => this.getWatcher(id),
+      destroy: async (id) => {
+        await this.request(`/watchers/${id}`, { method: "DELETE" });
+      }
+    });
+    this.sessionToken = new SessionToken({
+      create: async (options) => this.createSessionToken(options),
+      list: async () => this.listSessionTokens(),
+      retrieve: async (id) => this.getSessionToken(id),
+      revoke: async (id) => this.revokeSessionToken(id)
+    });
+    this.magicLink = new MagicLink({
+      create: async (options) => this.createMagicLink(options)
+    });
+    this.signal = new Signal({
+      start: async () => this.startSignals(),
+      status: async () => this.getSignalStatus(),
+      stop: async () => {
+        await this.request("/signals/stop", { method: "POST" });
+      },
+      emitPort: async (port, type, url) => this.emitPortSignal(port, type, url),
+      emitError: async (message) => this.emitErrorSignal(message),
+      emitServerReady: async (port, url) => this.emitServerReadySignal(port, url)
+    });
+    this.file = new File({
+      create: async (path, content) => this.createFile(path, content),
+      list: async (path) => this.listFiles(path),
+      retrieve: async (path) => this.readFile(path),
+      destroy: async (path) => this.deleteFile(path),
+      batchWrite: async (files) => this.batchWriteFiles(files),
+      exists: async (path) => this.checkFileExists(path)
+    });
+    this.env = new Env({
+      retrieve: async (file) => this.getEnv(file),
+      update: async (file, variables) => this.setEnv(file, variables),
+      remove: async (file, keys) => this.deleteEnv(file, keys),
+      exists: async (file) => this.checkEnvFile(file)
+    });
+    this.auth = new Auth({
+      status: async () => this.getAuthStatus(),
+      info: async () => this.getAuthInfo()
+    });
+    this.child = new Child({
+      create: async (options) => this.createSandbox(options),
+      list: async () => this.listSandboxes(),
+      retrieve: async (subdomain) => this.getSandbox(subdomain),
+      destroy: async (subdomain, deleteFiles) => this.deleteSandbox(subdomain, deleteFiles)
+    });
+  }
+  /**
+   * Get or create internal WebSocket manager
+   */
+  async ensureWebSocket() {
+    if (!this._ws || this._ws.getState() === "closed") {
+      this._ws = new WebSocketManager({
+        url: this.getWebSocketUrl(),
+        WebSocket: this.WebSocketImpl,
+        autoReconnect: true,
+        debug: false,
+        protocol: this.config.protocol
+      });
+      await this._ws.connect();
+    }
+    return this._ws;
+  }
+  /**
+   * Create and configure a TerminalInstance from response data
+   */
+  async hydrateTerminal(data, ws) {
+    const terminal = new TerminalInstance(
+      data.id,
+      data.pty,
+      data.status,
+      data.channel || null,
+      ws || null,
+      data.encoding || "raw"
+    );
+    const terminalId = data.id;
+    terminal.setExecuteHandler(async (command, background) => {
+      return this.request(`/terminals/${terminalId}/execute`, {
+        method: "POST",
+        body: JSON.stringify({ command, background })
+      });
+    });
+    terminal.setListCommandsHandler(async () => {
+      return this.request(`/terminals/${terminalId}/commands`);
+    });
+    terminal.setRetrieveCommandHandler(async (cmdId) => {
+      return this.request(`/terminals/${terminalId}/commands/${cmdId}`);
+    });
+    terminal.setWaitCommandHandler(async (cmdId, timeout) => {
+      const params = timeout ? new URLSearchParams({ timeout: timeout.toString() }) : "";
+      const endpoint = `/terminals/${terminalId}/commands/${cmdId}/wait${params ? `?${params}` : ""}`;
+      return this.request(endpoint);
+    });
+    terminal.setDestroyHandler(async () => {
+      await this.request(`/terminals/${terminalId}`, {
+        method: "DELETE"
+      });
+      this._terminals.delete(terminalId);
+    });
+    return terminal;
+  }
+  // ============================================================================
+  // Private Helper Methods
+  // ============================================================================
+  async request(endpoint, options = {}) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+    try {
+      const headers = {
+        ...this.config.headers
+      };
+      if (options.body) {
+        headers["Content-Type"] = "application/json";
+      }
+      if (this._token) {
+        headers["Authorization"] = `Bearer ${this._token}`;
+      }
+      const response = await fetch(`${this.config.sandboxUrl}${endpoint}`, {
+        ...options,
+        headers: {
+          ...headers,
+          ...options.headers
+        },
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (response.status === 204) {
+        return void 0;
+      }
+      const text = await response.text();
+      let data;
+      try {
+        data = JSON.parse(text);
+      } catch (jsonError) {
+        throw new Error(
+          `Failed to parse JSON response from ${endpoint}: ${jsonError instanceof Error ? jsonError.message : String(jsonError)}
+Response body (first 200 chars): ${text.substring(0, 200)}${text.length > 200 ? "..." : ""}`
+        );
+      }
+      if (!response.ok) {
+        const error = data.error || response.statusText;
+        if (response.status === 403 && endpoint.startsWith("/auth/")) {
+          if (endpoint.includes("/session_tokens") || endpoint.includes("/magic-links")) {
+            throw new Error(
+              `Access token required. This operation requires an access token, not a session token.
+API request failed (${response.status}): ${error}`
+            );
+          }
+        }
+        throw new Error(`API request failed (${response.status}): ${error}`);
+      }
+      return data;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new Error(`Request timeout after ${this.config.timeout}ms`);
+      }
+      throw error;
+    }
+  }
+  // ============================================================================
+  // Health Check
+  // ============================================================================
+  /**
+   * Check service health
+   */
+  async health() {
+    return this.request("/health");
+  }
+  // ============================================================================
+  // Authentication
+  // ============================================================================
+  /**
+   * Create a session token (requires access token)
+   *
+   * Session tokens are delegated credentials that can authenticate API requests
+   * without exposing your access token. Only access tokens can create session tokens.
+   *
+   * @param options - Token configuration
+   * @throws {Error} 403 Forbidden if called with a session token
+   */
+  async createSessionToken(options) {
+    return this.request("/auth/session_tokens", {
+      method: "POST",
+      body: JSON.stringify(options || {})
+    });
+  }
+  /**
+   * List all session tokens (requires access token)
+   *
+   * @throws {Error} 403 Forbidden if called with a session token
+   */
+  async listSessionTokens() {
+    return this.request("/auth/session_tokens");
+  }
+  /**
+   * Get details of a specific session token (requires access token)
+   *
+   * @param tokenId - The token ID
+   * @throws {Error} 403 Forbidden if called with a session token
+   */
+  async getSessionToken(tokenId) {
+    return this.request(`/auth/session_tokens/${tokenId}`);
+  }
+  /**
+   * Revoke a session token (requires access token)
+   *
+   * @param tokenId - The token ID to revoke
+   * @throws {Error} 403 Forbidden if called with a session token
+   */
+  async revokeSessionToken(tokenId) {
+    return this.request(`/auth/session_tokens/${tokenId}`, {
+      method: "DELETE"
+    });
+  }
+  /**
+   * Generate a magic link for browser authentication (requires access token)
+   *
+   * Magic links are one-time URLs that automatically create a session token
+   * and set it as a cookie in the user's browser. This provides an easy way
+   * to authenticate users in browser-based applications.
+   *
+   * The generated link:
+   * - Expires after 5 minutes or first use (whichever comes first)
+   * - Automatically creates a new session token (7 day expiry)
+   * - Sets the session token as an HttpOnly cookie
+   * - Redirects to the specified URL
+   *
+   * @param options - Magic link configuration
+   * @throws {Error} 403 Forbidden if called with a session token
+   */
+  async createMagicLink(options) {
+    return this.request("/auth/magic-links", {
+      method: "POST",
+      body: JSON.stringify(options || {})
+    });
+  }
+  /**
+   * Check authentication status
+   * Does not require authentication
+   */
+  async getAuthStatus() {
+    return this.request("/auth/status");
+  }
+  /**
+   * Get authentication information and usage instructions
+   * Does not require authentication
+   */
+  async getAuthInfo() {
+    return this.request("/auth/info");
+  }
+  /**
+   * Set authentication token manually
+   * @param token - Access token or session token
+   */
+  setToken(token) {
+    this._token = token;
+  }
+  /**
+   * Get current authentication token
+   */
+  getToken() {
+    return this._token;
+  }
+  /**
+   * Get current sandbox URL
+   */
+  getSandboxUrl() {
+    return this.config.sandboxUrl;
+  }
+  // ============================================================================
+  // Command Execution
+  // ============================================================================
+  /**
+   * Execute a one-off command without creating a persistent terminal
+   * 
+   * @example
+   * ```typescript
+   * // Synchronous execution (waits for completion)
+   * const result = await sandbox.execute({ command: 'npm test' });
+   * console.log(result.data.exit_code);
+   * 
+   * // Background execution (returns immediately)
+   * const result = await sandbox.execute({ 
+   *   command: 'npm install',
+   *   background: true 
+   * });
+   * // Use result.data.terminal_id and result.data.cmd_id to track
+   * const cmd = await sandbox.getCommand(result.data.terminal_id!, result.data.cmd_id!);
+   * ```
+   */
+  async execute(options) {
+    return this.request("/execute", {
+      method: "POST",
+      body: JSON.stringify(options)
+    });
+  }
+  /**
+   * Execute code with automatic language detection (POST /run/code)
+   *
+   * @param code - The code to execute
+   * @param language - Programming language (optional - auto-detects if not specified)
+   * @returns Code execution result with output, exit code, and detected language
+   *
+   * @example
+   * ```typescript
+   * // Auto-detect language
+   * const result = await sandbox.runCodeRequest('print("Hello")');
+   * console.log(result.data.output); // "Hello\n"
+   * console.log(result.data.language); // "python"
+   *
+   * // Explicit language
+   * const result = await sandbox.runCodeRequest('console.log("Hi")', 'node');
+   * ```
+   */
+  async runCodeRequest(code, language) {
+    const body = { code };
+    if (language) {
+      body.language = language;
+    }
+    return this.request("/run/code", {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+  }
+  /**
+   * Execute a command and get the result
+   * Lower-level method that returns the raw API response
+   *
+   * @param options.command - Command to execute
+   * @param options.shell - Shell to use (optional)
+   * @param options.background - Run in background (optional)
+   * @param options.cwd - Working directory for the command (optional)
+   * @param options.env - Environment variables (optional)
+   * @returns Command execution result
+   *
+   * @example
+   * ```typescript
+   * const result = await sandbox.runCommandRequest({ command: 'ls -la' });
+   * console.log(result.data.stdout);
+   * ```
+   */
+  async runCommandRequest(options) {
+    return this.request("/run/command", {
+      method: "POST",
+      body: JSON.stringify(options)
+    });
+  }
+  // ============================================================================
+  // File Operations
+  // ============================================================================
+  /**
+   * List files at the specified path
+   */
+  async listFiles(path = "/") {
+    const params = new URLSearchParams({ path });
+    return this.request(`/files?${params}`);
+  }
+  /**
+   * Create a new file with optional content
+   */
+  async createFile(path, content) {
+    return this.request("/files", {
+      method: "POST",
+      body: JSON.stringify({ path, content })
+    });
+  }
+  /**
+   * Get file metadata (without content)
+   */
+  async getFile(path) {
+    return this.request(`/files/${this.encodeFilePath(path)}`);
+  }
+  /**
+   * Encode a file path for use in URLs
+   * Strips leading slash and encodes each segment separately to preserve path structure
+   */
+  encodeFilePath(path) {
+    const pathWithoutLeadingSlash = path.startsWith("/") ? path.slice(1) : path;
+    const segments = pathWithoutLeadingSlash.split("/");
+    return segments.map((s) => encodeURIComponent(s)).join("/");
+  }
+  /**
+   * Read file content
+   */
+  async readFile(path) {
+    const params = new URLSearchParams({ content: "true" });
+    const response = await this.request(
+      `/files/${this.encodeFilePath(path)}?${params}`
+    );
+    return response.data.content || "";
+  }
+  /**
+   * Write file content (creates or updates)
+   */
+  async writeFile(path, content) {
+    return this.request("/files", {
+      method: "POST",
+      body: JSON.stringify({ path, content })
+    });
+  }
+  /**
+   * Delete a file or directory
+   */
+  async deleteFile(path) {
+    return this.request(`/files/${this.encodeFilePath(path)}`, {
+      method: "DELETE"
+    });
+  }
+  /**
+   * Check if a file exists (HEAD request)
+   * @returns true if file exists, false otherwise
+   */
+  async checkFileExists(path) {
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+      const headers = {
+        ...this.config.headers
+      };
+      if (this._token) {
+        headers["Authorization"] = `Bearer ${this._token}`;
+      }
+      const response = await fetch(
+        `${this.config.sandboxUrl}/files/${this.encodeFilePath(path)}`,
+        {
+          method: "HEAD",
+          headers,
+          signal: controller.signal
+        }
+      );
+      clearTimeout(timeoutId);
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Batch file operations (write or delete multiple files)
+   *
+   * Features:
+   * - Deduplication: Last operation wins per path
+   * - File locking: Prevents race conditions
+   * - Deterministic ordering: Alphabetical path sorting
+   * - Partial failure handling: Returns 207 Multi-Status with per-file results
+   *
+   * @param files - Array of file operations
+   * @returns Results for each file operation
+   *
+   * @example
+   * ```typescript
+   * // Write multiple files
+   * const results = await sandbox.batchWriteFiles([
+   *   { path: '/app/file1.txt', operation: 'write', content: 'Hello' },
+   *   { path: '/app/file2.txt', operation: 'write', content: 'World' },
+   * ]);
+   *
+   * // Mixed operations (write and delete)
+   * const results = await sandbox.batchWriteFiles([
+   *   { path: '/app/new.txt', operation: 'write', content: 'New file' },
+   *   { path: '/app/old.txt', operation: 'delete' },
+   * ]);
+   * ```
+   */
+  async batchWriteFiles(files) {
+    return this.request("/files/batch", {
+      method: "POST",
+      body: JSON.stringify({ files })
+    });
+  }
+  // ============================================================================
+  // Filesystem Overlays
+  // ============================================================================
+  /**
+   * Create a new filesystem overlay from a template directory
+   *
+   * Overlays enable instant sandbox setup by symlinking template files first,
+   * then copying heavy directories (node_modules, .venv, etc.) in the background.
+   *
+   * @param options - Overlay creation options
+   * @param options.source - Absolute path to source directory (template)
+   * @param options.target - Relative path in sandbox where overlay will be mounted
+   * @returns Overlay response with copy status
+   *
+   * @example
+   * ```typescript
+   * // Prefer using sandbox.filesystem.overlay.create() for camelCase response
+   * const overlay = await sandbox.filesystem.overlay.create({
+   *   source: '/templates/nextjs',
+   *   target: 'project',
+   * });
+   * console.log(overlay.copyStatus); // 'pending' | 'in_progress' | 'complete' | 'failed'
+   * ```
+   */
+  async createOverlay(options) {
+    return this.request("/filesystem/overlays", {
+      method: "POST",
+      body: JSON.stringify(options)
+    });
+  }
+  /**
+   * List all filesystem overlays for the current sandbox
+   * @returns List of overlays with their copy status
+   */
+  async listOverlays() {
+    return this.request("/filesystem/overlays");
+  }
+  /**
+   * Get a specific filesystem overlay by ID
+   *
+   * Useful for polling the copy status of an overlay.
+   *
+   * @param id - Overlay ID
+   * @returns Overlay details with current copy status
+   */
+  async getOverlay(id) {
+    return this.request(`/filesystem/overlays/${id}`);
+  }
+  /**
+   * Delete a filesystem overlay
+   * @param id - Overlay ID
+   */
+  async deleteOverlay(id) {
+    return this.request(`/filesystem/overlays/${id}`, {
+      method: "DELETE"
+    });
+  }
+  // ============================================================================
+  // Terminal Management
+  // ============================================================================
+  /**
+   * Create a new persistent terminal session
+   * 
+   * Terminal Modes:
+   * - **PTY mode** (pty: true): Interactive shell with real-time WebSocket streaming
+   *   - Use for: Interactive shells, vim/nano, real-time output
+   *   - Methods: write(), resize(), on('output')
+   * 
+   * - **Exec mode** (pty: false, default): Command tracking with HTTP polling
+   *   - Use for: CI/CD, automation, command tracking, exit codes
+   *   - Methods: execute(), getCommand(), listCommands(), waitForCommand()
+   * 
+   * @example
+   * ```typescript
+   * // PTY mode - Interactive shell
+   * const pty = await sandbox.createTerminal({ pty: true, shell: '/bin/bash' });
+   * pty.on('output', (data) => console.log(data));
+   * pty.write('npm install\n');
+   * 
+   * // Exec mode - Command tracking
+   * const exec = await sandbox.createTerminal({ pty: false });
+   * const result = await exec.execute('npm test', { background: true });
+   * const cmd = await sandbox.waitForCommand(exec.getId(), result.data.cmd_id);
+   * console.log(cmd.data.exit_code);
+   * 
+   * // Backward compatible - creates PTY terminal
+   * const terminal = await sandbox.createTerminal('/bin/bash');
+   * ```
+   * 
+   * @param options - Terminal creation options
+   * @param options.shell - Shell to use (e.g., '/bin/bash', '/bin/sh') - PTY mode only
+   * @param options.encoding - Encoding for terminal I/O: 'raw' (default) or 'base64' (binary-safe)
+   * @param options.pty - Terminal mode: true = PTY (interactive shell), false = exec (command tracking, default)
+   * @returns Terminal instance with event handling
+   */
+  async createTerminal(shellOrOptions, encoding) {
+    let pty;
+    let shell;
+    let enc;
+    if (typeof shellOrOptions === "string") {
+      pty = true;
+      shell = shellOrOptions;
+      enc = encoding;
+    } else {
+      pty = shellOrOptions?.pty ?? false;
+      enc = shellOrOptions?.encoding;
+      shell = shellOrOptions?.shell;
+    }
+    const body = {};
+    if (shell) body.shell = shell;
+    if (enc) body.encoding = enc;
+    if (pty !== void 0) body.pty = pty;
+    const response = await this.request("/terminals", {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+    let ws = null;
+    if (response.data.pty) {
+      ws = await this.ensureWebSocket();
+      await new Promise((resolve) => {
+        const handler = (msg) => {
+          if (msg.data?.id === response.data.id) {
+            if (ws) ws.off("terminal:created", handler);
+            resolve();
+          }
+        };
+        if (ws) {
+          ws.on("terminal:created", handler);
+          setTimeout(() => {
+            if (ws) ws.off("terminal:created", handler);
+            resolve();
+          }, 5e3);
+        } else {
+          resolve();
+        }
+      });
+    }
+    const terminal = await this.hydrateTerminal(response.data, ws);
+    this._terminals.set(terminal.id, terminal);
+    return terminal;
+  }
+  /**
+   * List all active terminals (fetches from API)
+   */
+  async listTerminals() {
+    const response = await this.request("/terminals");
+    return response.data.terminals;
+  }
+  /**
+   * Get terminal by ID
+   */
+  async getTerminal(id) {
+    const cached = this._terminals.get(id);
+    if (cached) {
+      return cached;
+    }
+    const response = await this.request(`/terminals/${id}`);
+    let ws = null;
+    if (response.data.pty) {
+      ws = await this.ensureWebSocket();
+    }
+    const terminal = await this.hydrateTerminal(response.data, ws);
+    this._terminals.set(id, terminal);
+    return terminal;
+  }
+  // ============================================================================
+  // Command Tracking (Exec Mode Terminals)
+  // ============================================================================
+  /**
+   * List all commands executed in a terminal (exec mode only)
+   * @param terminalId - The terminal ID
+   * @returns List of all commands with their status
+   * @throws {Error} If terminal is in PTY mode (command tracking not available)
+   */
+  async listCommands(terminalId) {
+    return this.request(`/terminals/${terminalId}/commands`);
+  }
+  /**
+   * Get details of a specific command execution (exec mode only)
+   * @param terminalId - The terminal ID
+   * @param cmdId - The command ID
+   * @returns Command execution details including stdout, stderr, and exit code
+   * @throws {Error} If terminal is in PTY mode or command not found
+   */
+  async getCommand(terminalId, cmdId) {
+    return this.request(`/terminals/${terminalId}/commands/${cmdId}`);
+  }
+  /**
+   * Wait for a command to complete (HTTP long-polling, exec mode only)
+   * @param terminalId - The terminal ID
+   * @param cmdId - The command ID
+   * @param timeout - Optional timeout in seconds (0 = no timeout)
+   * @returns Command execution details when completed
+   * @throws {Error} If terminal is in PTY mode, command not found, or timeout occurs
+   */
+  async waitForCommand(terminalId, cmdId, timeout) {
+    const params = timeout ? new URLSearchParams({ timeout: timeout.toString() }) : "";
+    const endpoint = `/terminals/${terminalId}/commands/${cmdId}/wait${params ? `?${params}` : ""}`;
+    return this.request(endpoint);
+  }
+  /**
+   * Wait for a background command to complete using long-polling
+   *
+   * Uses the server's long-polling endpoint with configurable timeout.
+   * The tunnel supports up to 5 minutes (300 seconds) via X-Request-Timeout header.
+   *
+   * @param terminalId - The terminal ID
+   * @param cmdId - The command ID
+   * @param options - Wait options (timeoutSeconds, default 300)
+   * @returns Command result with final status
+   * @throws Error if command fails or times out
+   * @internal
+   */
+  async waitForCommandCompletion(terminalId, cmdId, options) {
+    const timeoutSeconds = options?.timeoutSeconds ?? MAX_TUNNEL_TIMEOUT_SECONDS;
+    const response = await this.waitForCommandWithTimeout(terminalId, cmdId, timeoutSeconds);
+    return {
+      stdout: response.data.stdout,
+      stderr: response.data.stderr,
+      exitCode: response.data.exit_code ?? 0,
+      durationMs: response.data.duration_ms ?? 0,
+      cmdId: response.data.cmd_id,
+      terminalId,
+      status: response.data.status
+    };
+  }
+  /**
+   * Wait for a command with extended timeout support
+   * Uses X-Request-Timeout header for tunnel timeout configuration
+   * @internal
+   */
+  async waitForCommandWithTimeout(terminalId, cmdId, timeoutSeconds) {
+    const params = new URLSearchParams({ timeout: timeoutSeconds.toString() });
+    const endpoint = `/terminals/${terminalId}/commands/${cmdId}/wait?${params}`;
+    const requestTimeout = Math.min(timeoutSeconds, MAX_TUNNEL_TIMEOUT_SECONDS);
+    return this.request(endpoint, {
+      headers: {
+        "X-Request-Timeout": requestTimeout.toString()
+      }
+    });
+  }
+  // ============================================================================
+  // File Watchers
+  // ============================================================================
+  /**
+   * Create a new file watcher with WebSocket integration
+   * @param path - Path to watch
+   * @param options - Watcher options
+   * @param options.includeContent - Include file content in change events
+   * @param options.ignored - Patterns to ignore
+   * @param options.encoding - Encoding for file content: 'raw' (default) or 'base64' (binary-safe)
+   * @returns FileWatcher instance with event handling
+   */
+  async createWatcher(path, options) {
+    const ws = await this.ensureWebSocket();
+    const response = await this.request("/watchers", {
+      method: "POST",
+      body: JSON.stringify({ path, ...options })
+    });
+    const watcher = new FileWatcher(
+      response.data.id,
+      response.data.path,
+      response.data.status,
+      response.data.channel,
+      response.data.includeContent,
+      response.data.ignored,
+      ws,
+      response.data.encoding || "raw"
+    );
+    watcher.setDestroyHandler(async () => {
+      await this.request(`/watchers/${response.data.id}`, {
+        method: "DELETE"
+      });
+    });
+    return watcher;
+  }
+  /**
+   * List all active file watchers (fetches from API)
+   */
+  async listWatchers() {
+    return this.request("/watchers");
+  }
+  /**
+   * Get file watcher by ID
+   */
+  async getWatcher(id) {
+    return this.request(`/watchers/${id}`);
+  }
+  // ============================================================================
+  // Signal Service
+  // ============================================================================
+  /**
+   * Start the signal service with WebSocket integration
+   * @returns SignalService instance with event handling
+   */
+  async startSignals() {
+    const ws = await this.ensureWebSocket();
+    const response = await this.request("/signals/start", {
+      method: "POST"
+    });
+    const signalService = new SignalService(
+      response.data.status,
+      response.data.channel,
+      ws
+    );
+    signalService.setStopHandler(async () => {
+      await this.request("/signals/stop", {
+        method: "POST"
+      });
+    });
+    return signalService;
+  }
+  /**
+   * Get the signal service status (fetches from API)
+   */
+  async getSignalStatus() {
+    return this.request("/signals/status");
+  }
+  /**
+   * Emit a port signal
+   */
+  async emitPortSignal(port, type, url) {
+    return this.request("/signals/port", {
+      method: "POST",
+      body: JSON.stringify({ port, type, url })
+    });
+  }
+  /**
+   * Emit a port signal (alternative endpoint using path parameters)
+   */
+  async emitPortSignalAlt(port, type) {
+    return this.request(`/signals/port/${port}/${type}`, {
+      method: "POST"
+    });
+  }
+  /**
+   * Emit an error signal
+   */
+  async emitErrorSignal(message) {
+    return this.request("/signals/error", {
+      method: "POST",
+      body: JSON.stringify({ message })
+    });
+  }
+  /**
+   * Emit a server ready signal
+   */
+  async emitServerReadySignal(port, url) {
+    return this.request("/signals/server-ready", {
+      method: "POST",
+      body: JSON.stringify({ port, url })
+    });
+  }
+  // ============================================================================
+  // Environment Variables
+  // ============================================================================
+  /**
+   * Get environment variables from a .env file
+   * @param file - Path to the .env file (relative to sandbox root)
+   */
+  async getEnv(file) {
+    const params = new URLSearchParams({ file });
+    return this.request(`/env?${params}`);
+  }
+  /**
+   * Set (merge) environment variables in a .env file
+   * @param file - Path to the .env file (relative to sandbox root)
+   * @param variables - Key-value pairs to set
+   */
+  async setEnv(file, variables) {
+    const params = new URLSearchParams({ file });
+    return this.request(`/env?${params}`, {
+      method: "POST",
+      body: JSON.stringify({ variables })
+    });
+  }
+  /**
+   * Delete environment variables from a .env file
+   * @param file - Path to the .env file (relative to sandbox root)
+   * @param keys - Keys to delete
+   */
+  async deleteEnv(file, keys) {
+    const params = new URLSearchParams({ file });
+    return this.request(`/env?${params}`, {
+      method: "DELETE",
+      body: JSON.stringify({ keys })
+    });
+  }
+  /**
+   * Check if an environment file exists (HEAD request)
+   * @param file - Path to the .env file (relative to sandbox root)
+   * @returns true if file exists, false otherwise
+   */
+  async checkEnvFile(file) {
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+      const headers = {
+        ...this.config.headers
+      };
+      if (this._token) {
+        headers["Authorization"] = `Bearer ${this._token}`;
+      }
+      const params = new URLSearchParams({ file });
+      const response = await fetch(`${this.config.sandboxUrl}/env?${params}`, {
+        method: "HEAD",
+        headers,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+  // ============================================================================
+  // Server Management
+  // ============================================================================
+  /**
+   * List all managed servers
+   */
+  async listServers() {
+    return this.request("/servers");
+  }
+  /**
+   * Start a new managed server with optional supervisor settings
+   *
+   * @param options - Server configuration
+   * @param options.slug - Unique server identifier
+   * @param options.install - Install command (optional, runs blocking before start, e.g., "npm install")
+   * @param options.start - Command to start the server (e.g., "npm run dev")
+   * @param options.path - Working directory (optional)
+   * @param options.env_file - Path to .env file relative to path (optional)
+   * @param options.environment - Inline environment variables (merged with env_file if both provided)
+   * @param options.port - Requested port (preallocated before start)
+   * @param options.strict_port - If true, fail instead of auto-incrementing when port is taken
+   * @param options.autostart - Auto-start on daemon boot (default: true)
+   * @param options.overlay - Inline overlay to create before starting
+   * @param options.overlays - Additional overlays to create before starting
+   * @param options.depends_on - Overlay IDs this server depends on
+   * @param options.restart_policy - When to automatically restart: 'never' (default), 'on-failure', 'always'
+   * @param options.max_restarts - Maximum restart attempts, 0 = unlimited (default: 0)
+   * @param options.restart_delay_ms - Delay between restart attempts in milliseconds (default: 1000)
+   * @param options.stop_timeout_ms - Graceful shutdown timeout in milliseconds (default: 10000)
+   *
+   * @example
+   * ```typescript
+   * // Basic server
+   * await sandbox.startServer({
+   *   slug: 'web',
+   *   start: 'npm run dev',
+   *   path: '/app',
+   * });
+   *
+   * // With install command and supervisor settings
+   * await sandbox.startServer({
+   *   slug: 'api',
+   *   install: 'npm install',
+   *   start: 'node server.js',
+   *   path: '/app',
+   *   environment: { NODE_ENV: 'production', PORT: '3000' },
+   *   restart_policy: 'on-failure',
+   *   max_restarts: 5,
+   *   restart_delay_ms: 2000,
+   *   stop_timeout_ms: 5000,
+   * });
+   *
+   * // With inline overlay dependencies
+   * await sandbox.startServer({
+   *   slug: 'web',
+   *   start: 'npm run dev',
+   *   path: '/app',
+   *   overlay: {
+   *     source: '/templates/nextjs',
+   *     target: 'app',
+   *     strategy: 'smart',
+   *   },
+   * });
+   * ```
+   */
+  async startServer(options) {
+    return this.request("/servers", {
+      method: "POST",
+      body: JSON.stringify(options)
+    });
+  }
+  /**
+   * Get information about a specific server
+   * @param slug - Server slug
+   */
+  async getServer(slug) {
+    return this.request(`/servers/${encodeURIComponent(slug)}`);
+  }
+  /**
+   * Stop a managed server (non-destructive)
+   * @param slug - Server slug
+   */
+  async stopServer(slug) {
+    return this.request(
+      `/servers/${encodeURIComponent(slug)}/stop`,
+      {
+        method: "POST"
+      }
+    );
+  }
+  /**
+   * Delete a managed server configuration
+   * @param slug - Server slug
+   */
+  async deleteServer(slug) {
+    await this.request(`/servers/${encodeURIComponent(slug)}`, {
+      method: "DELETE"
+    });
+  }
+  /**
+   * Restart a managed server
+   * @param slug - Server slug
+   */
+  async restartServer(slug) {
+    return this.request(
+      `/servers/${encodeURIComponent(slug)}/restart`,
+      {
+        method: "POST"
+      }
+    );
+  }
+  /**
+   * Get logs for a managed server
+   * @param slug - Server slug
+   * @param options - Options for log retrieval
+   */
+  async getServerLogs(slug, options) {
+    const params = new URLSearchParams();
+    if (options?.stream) {
+      params.set("stream", options.stream);
+    }
+    const queryString = params.toString();
+    return this.request(
+      `/servers/${encodeURIComponent(slug)}/logs${queryString ? `?${queryString}` : ""}`
+    );
+  }
+  /**
+   * Update server status (internal use)
+   * @param slug - Server slug
+   * @param status - New server status
+   */
+  async updateServerStatus(slug, status) {
+    return this.request(
+      `/servers/${encodeURIComponent(slug)}/status`,
+      {
+        method: "PATCH",
+        body: JSON.stringify({ status })
+      }
+    );
+  }
+  // ============================================================================
+  // Ready Management
+  // ============================================================================
+  /**
+   * Get readiness status for autostarted servers and overlays
+   */
+  async ready() {
+    const response = await this.request("/ready");
+    return {
+      ready: response.ready,
+      servers: response.servers ?? [],
+      overlays: response.overlays ?? []
+    };
+  }
+  // ============================================================================
+  // Sandbox Management
+  // ============================================================================
+  /**
+   * Create a new sandbox environment
+   */
+  async createSandbox(options) {
+    return this.request("/sandboxes", {
+      method: "POST",
+      body: JSON.stringify(options || {})
+    });
+  }
+  /**
+   * List all sandboxes
+   */
+  async listSandboxes() {
+    return this.request("/sandboxes");
+  }
+  /**
+   * Get sandbox details
+   */
+  async getSandbox(subdomain) {
+    return this.request(`/sandboxes/${subdomain}`);
+  }
+  /**
+   * Delete a sandbox
+   */
+  async deleteSandbox(subdomain, deleteFiles = false) {
+    const params = new URLSearchParams({ delete_files: String(deleteFiles) });
+    return this.request(`/sandboxes/${subdomain}?${params}`, {
+      method: "DELETE"
+    });
+  }
+  // ============================================================================
+  // WebSocket Connection (Internal)
+  // ============================================================================
   /**
-   * Create a new ComputeError
-   * 
-   * @param message Error message
-   * @param provider Provider identifier
-   * @param sandboxId Optional sandbox identifier
+   * Get WebSocket URL for real-time communication
+   * @private
    */
-  constructor(message, provider, sandboxId) {
-    super(message);
-    this.name = this.constructor.name;
-    this.provider = provider;
-    this.sandboxId = sandboxId;
-    Object.setPrototypeOf(this, new.target.prototype);
+  getWebSocketUrl() {
+    const wsProtocol = this.config.sandboxUrl.startsWith("https") ? "wss" : "ws";
+    const url = this.config.sandboxUrl.replace(/^https?:/, `${wsProtocol}:`);
+    const params = new URLSearchParams();
+    if (this._token) {
+      params.set("token", this._token);
+    }
+    params.set("protocol", this.config.protocol || "binary");
+    const queryString = params.toString();
+    return `${url}/ws${queryString ? `?${queryString}` : ""}`;
   }
-};
-var ExecutionError = class extends ComputeError {
+  // ============================================================================
+  // Sandbox Interface Implementation
+  // ============================================================================
   /**
-   * Create a new ExecutionError
-   * 
-   * @param message Error message
-   * @param provider Provider identifier
-   * @param exitCode Exit code from the execution
-   * @param sandboxId Optional sandbox identifier
-   */
-  constructor(message, provider, exitCode, sandboxId) {
-    super(message, provider, sandboxId);
-    /** Error code */
-    this.code = "EXECUTION_ERROR";
-    /** Execution errors are generally not retryable */
-    this.isRetryable = false;
-    this.exitCode = exitCode;
+   * Execute code in the sandbox (convenience method)
+   *
+   * Delegates to sandbox.run.code() - prefer using that directly for new code.
+   *
+   * @param code - The code to execute
+   * @param language - Programming language (auto-detected if not specified)
+   * @returns Code execution result
+   */
+  async runCode(code, language) {
+    return this.run.code(code, language ? { language } : void 0);
   }
-};
-var TimeoutError = class extends ComputeError {
   /**
-   * Create a new TimeoutError
+   * Execute shell command in the sandbox
+   *
+   * Sends clean command string to server - no preprocessing or shell wrapping.
+   * The server handles shell invocation, working directory, and backgrounding.
+   *
+   * @param command - The command to execute (raw string, e.g., "npm install")
+   * @param options - Execution options
+   * @param options.background - Run in background (server uses goroutines)
+   * @param options.cwd - Working directory (server uses cmd.Dir)
+   * @param options.env - Environment variables (server uses cmd.Env)
+   * @param options.onStdout - Callback for streaming stdout data
+   * @param options.onStderr - Callback for streaming stderr data
+   * @returns Command execution result
+   * 
+   * @example
+   * ```typescript
+   * // Simple command
+   * await sandbox.runCommand('ls -la')
    * 
-   * @param message Error message
-   * @param provider Provider identifier
-   * @param timeoutMs Timeout duration in milliseconds
-   * @param sandboxId Optional sandbox identifier
-   */
-  constructor(message, provider, timeoutMs, sandboxId) {
-    super(message, provider, sandboxId);
-    /** Error code */
-    this.code = "TIMEOUT_ERROR";
-    /** Timeout errors may be retryable with a longer timeout */
-    this.isRetryable = true;
-    this.timeoutMs = timeoutMs;
+   * // With working directory
+   * await sandbox.runCommand('npm install', { cwd: '/app' })
+   * 
+   * // Background with env vars
+   * await sandbox.runCommand('node server.js', { 
+   *   background: true, 
+   *   env: { PORT: '3000' } 
+   * })
+   * 
+   * // With streaming output
+   * await sandbox.runCommand('npm install', {
+   *   onStdout: (data) => console.log(data),
+   *   onStderr: (data) => console.error(data),
+   * })
+   * ```
+   */
+  async runCommand(command, options) {
+    const hasStreamingCallbacks = options?.onStdout || options?.onStderr;
+    if (!hasStreamingCallbacks) {
+      return this.run.command(command, options);
+    }
+    const ws = await this.ensureWebSocket();
+    const result = await this.runCommandRequest({
+      command,
+      stream: true,
+      cwd: options?.cwd,
+      env: options?.env
+    });
+    const { cmd_id, channel } = result.data;
+    if (!cmd_id || !channel) {
+      throw new Error("Server did not return streaming channel info");
+    }
+    ws.subscribe(channel);
+    let stdout = "";
+    let stderr = "";
+    let exitCode = 0;
+    let resolvePromise = null;
+    const cleanup = () => {
+      ws.off("command:stdout", handleStdout);
+      ws.off("command:stderr", handleStderr);
+      ws.off("command:exit", handleExit);
+      ws.unsubscribe(channel);
+    };
+    const handleStdout = (msg) => {
+      if (msg.channel === channel && msg.data.cmd_id === cmd_id) {
+        stdout += msg.data.output;
+        options?.onStdout?.(msg.data.output);
+      }
+    };
+    const handleStderr = (msg) => {
+      if (msg.channel === channel && msg.data.cmd_id === cmd_id) {
+        stderr += msg.data.output;
+        options?.onStderr?.(msg.data.output);
+      }
+    };
+    const handleExit = (msg) => {
+      if (msg.channel === channel && msg.data.cmd_id === cmd_id) {
+        exitCode = msg.data.exit_code;
+        cleanup();
+        if (resolvePromise) {
+          resolvePromise({ stdout, stderr, exitCode, durationMs: 0 });
+        }
+      }
+    };
+    ws.on("command:stdout", handleStdout);
+    ws.on("command:stderr", handleStderr);
+    ws.on("command:exit", handleExit);
+    ws.startCommand(cmd_id);
+    if (options?.background) {
+      return {
+        stdout: "",
+        stderr: "",
+        exitCode: 0,
+        durationMs: 0
+      };
+    }
+    return new Promise((resolve) => {
+      resolvePromise = resolve;
+    });
   }
-};
-var ProviderError = class extends ComputeError {
   /**
-   * Create a new ProviderError
-   * 
-   * @param message Error message
-   * @param provider Provider identifier
-   * @param originalError Optional original error from the provider
-   * @param sandboxId Optional sandbox identifier
-   */
-  constructor(message, provider, originalError, sandboxId) {
-    super(message, provider, sandboxId);
-    /** Error code */
-    this.code = "PROVIDER_ERROR";
-    /** Provider errors may be retryable */
-    this.isRetryable = true;
-    this.originalError = originalError;
+   * Get server information
+   * Returns details about the server including auth status, main subdomain, sandbox count, and version
+   */
+  async getServerInfo() {
+    return this.request("/info");
   }
-};
-var ConfigurationError = class extends ComputeError {
   /**
-   * Create a new ConfigurationError
-   * 
-   * @param message Error message
-   * @param provider Provider identifier
-   * @param sandboxId Optional sandbox identifier
+   * Get sandbox information
    */
-  constructor(message, provider, sandboxId) {
-    super(message, provider, sandboxId);
-    /** Error code */
-    this.code = "CONFIGURATION_ERROR";
-    /** Configuration errors are not retryable without changes */
-    this.isRetryable = false;
+  async getInfo() {
+    return {
+      id: this.sandboxId || "",
+      provider: this.provider || "",
+      runtime: "node",
+      status: "running",
+      createdAt: /* @__PURE__ */ new Date(),
+      timeout: this.config.timeout,
+      metadata: this.config.metadata
+    };
   }
-};
-var AuthenticationError = class extends ComputeError {
   /**
-   * Create a new AuthenticationError
-   * 
-   * @param message Error message
-   * @param provider Provider identifier
-   * @param sandboxId Optional sandbox identifier
+   * Get URL for accessing sandbox on a specific port (Sandbox interface method)
    */
-  constructor(message, provider, sandboxId) {
-    super(message, provider, sandboxId);
-    /** Error code */
-    this.code = "AUTHENTICATION_ERROR";
-    /** Authentication errors are not retryable without new credentials */
-    this.isRetryable = false;
+  async getUrl(options) {
+    const protocol = options.protocol || "https";
+    const url = new URL(this.config.sandboxUrl);
+    const parts = url.hostname.split(".");
+    const subdomain = parts[0];
+    const baseDomain = parts.slice(1).join(".");
+    const previewDomain = baseDomain.replace("sandbox.computesdk.com", "preview.computesdk.com");
+    return `${protocol}://${subdomain}-${options.port}.${previewDomain}`;
+  }
+  /**
+   * Get provider instance
+   * Note: Not available when using Sandbox directly - only available through gateway provider
+   */
+  getProvider() {
+    throw new Error(
+      "getProvider() is not available on Sandbox. This method is only available when using provider sandboxes through the gateway."
+    );
   }
-};
-var ProviderUnavailableError = class extends ComputeError {
   /**
-   * Create a new ProviderUnavailableError
+   * Get native provider instance
+   * Returns the Sandbox itself since this IS the sandbox implementation
+   */
+  getInstance() {
+    return this;
+  }
+  /**
+   * Destroy the sandbox (Sandbox interface method)
    * 
-   * @param message Error message
-   * @param provider Provider identifier
-   * @param sandboxId Optional sandbox identifier
+   * If a destroyHandler was provided (e.g., from gateway), calls it to destroy
+   * the sandbox on the backend. Otherwise, only disconnects the WebSocket.
+   */
+  async destroy() {
+    await this.disconnect();
+    if (this.config.destroyHandler) {
+      await this.config.destroyHandler();
+    }
+  }
+  /**
+   * Disconnect WebSocket
+   *
+   * Note: This only disconnects the WebSocket. Terminals, watchers, and signals
+   * will continue running on the server until explicitly destroyed via their
+   * respective destroy() methods or the DELETE endpoints.
    */
-  constructor(message, provider, sandboxId) {
-    super(message, provider, sandboxId);
-    /** Error code */
-    this.code = "PROVIDER_UNAVAILABLE";
-    /** Provider unavailability may be temporary */
-    this.isRetryable = true;
+  async disconnect() {
+    if (this._ws) {
+      this._ws.disconnect();
+      this._ws = null;
+    }
+    this._terminals.clear();
   }
 };
 
-// src/config.ts
-var DEFAULT_TIMEOUT = 3e5;
-var ENV_KEYS = {
-  E2B: "E2B_API_KEY",
-  VERCEL: "VERCEL_TOKEN",
-  DAYTONA: "DAYTONA_API_KEY"
+// src/setup.ts
+var encodeBase64 = (value) => {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(value, "utf8").toString("base64");
+  }
+  if (typeof btoa !== "undefined" && typeof TextEncoder !== "undefined") {
+    const bytes = new TextEncoder().encode(value);
+    let binary = "";
+    for (const byte of bytes) {
+      binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+  }
+  throw new Error("Base64 encoding is not supported in this environment.");
+};
+var buildSetupPayload = (options) => {
+  const overlays = options.overlays?.map((overlay) => {
+    const { source, target, ignore, strategy } = overlay;
+    return {
+      source,
+      target,
+      ignore,
+      strategy
+    };
+  });
+  const servers = options.servers;
+  return {
+    overlays: overlays?.length ? overlays : void 0,
+    servers: servers?.length ? servers : void 0
+  };
+};
+var encodeSetupPayload = (options) => {
+  const payload = buildSetupPayload(options);
+  return encodeBase64(JSON.stringify(payload));
+};
+
+// src/provider-config.ts
+var PROVIDER_AUTH = {
+  e2b: [["E2B_API_KEY"]],
+  modal: [["MODAL_TOKEN_ID", "MODAL_TOKEN_SECRET"]],
+  railway: [["RAILWAY_API_KEY", "RAILWAY_PROJECT_ID", "RAILWAY_ENVIRONMENT_ID"]],
+  render: [["RENDER_API_KEY", "RENDER_OWNER_ID"]],
+  daytona: [["DAYTONA_API_KEY"]],
+  vercel: [
+    ["VERCEL_OIDC_TOKEN"],
+    ["VERCEL_TOKEN", "VERCEL_TEAM_ID", "VERCEL_PROJECT_ID"]
+  ],
+  runloop: [["RUNLOOP_API_KEY"]],
+  cloudflare: [["CLOUDFLARE_API_TOKEN", "CLOUDFLARE_ACCOUNT_ID"]],
+  codesandbox: [["CSB_API_KEY"]],
+  blaxel: [["BL_API_KEY", "BL_WORKSPACE"]],
+  namespace: [["NSC_TOKEN"]]
 };
-function detectAvailableProviders() {
-  const available = [];
-  const env = typeof process !== "undefined" ? process.env : {};
-  if (env[ENV_KEYS.E2B]) {
-    available.push("e2b");
+var PROVIDER_NAMES = Object.keys(PROVIDER_AUTH);
+var PROVIDER_HEADERS = {
+  e2b: {
+    apiKey: "X-E2B-API-Key"
+  },
+  modal: {
+    tokenId: "X-Modal-Token-Id",
+    tokenSecret: "X-Modal-Token-Secret"
+  },
+  railway: {
+    apiToken: "X-Railway-API-Key",
+    projectId: "X-Railway-Project-ID",
+    environmentId: "X-Railway-Environment-ID"
+  },
+  render: {
+    apiKey: "X-Render-API-Key",
+    ownerId: "X-Render-Owner-ID"
+  },
+  daytona: {
+    apiKey: "X-Daytona-API-Key"
+  },
+  vercel: {
+    oidcToken: "X-Vercel-OIDC-Token",
+    token: "X-Vercel-Token",
+    teamId: "X-Vercel-Team-Id",
+    projectId: "X-Vercel-Project-Id"
+  },
+  runloop: {
+    apiKey: "X-Runloop-API-Key"
+  },
+  cloudflare: {
+    apiToken: "X-Cloudflare-API-Token",
+    accountId: "X-Cloudflare-Account-Id"
+  },
+  codesandbox: {
+    apiKey: "X-CSB-API-Key"
+  },
+  blaxel: {
+    apiKey: "X-Blaxel-API-Key",
+    workspace: "X-Blaxel-Workspace"
+  },
+  namespace: {
+    token: "X-Namespace-Token"
   }
-  if (env[ENV_KEYS.VERCEL]) {
-    available.push("vercel");
+};
+var PROVIDER_ENV_MAP = {
+  e2b: {
+    E2B_API_KEY: "apiKey"
+  },
+  modal: {
+    MODAL_TOKEN_ID: "tokenId",
+    MODAL_TOKEN_SECRET: "tokenSecret"
+  },
+  railway: {
+    RAILWAY_API_KEY: "apiToken",
+    RAILWAY_PROJECT_ID: "projectId",
+    RAILWAY_ENVIRONMENT_ID: "environmentId"
+  },
+  render: {
+    RENDER_API_KEY: "apiKey",
+    RENDER_OWNER_ID: "ownerId"
+  },
+  daytona: {
+    DAYTONA_API_KEY: "apiKey"
+  },
+  vercel: {
+    VERCEL_OIDC_TOKEN: "oidcToken",
+    VERCEL_TOKEN: "token",
+    VERCEL_TEAM_ID: "teamId",
+    VERCEL_PROJECT_ID: "projectId"
+  },
+  runloop: {
+    RUNLOOP_API_KEY: "apiKey"
+  },
+  cloudflare: {
+    CLOUDFLARE_API_TOKEN: "apiToken",
+    CLOUDFLARE_ACCOUNT_ID: "accountId"
+  },
+  codesandbox: {
+    CSB_API_KEY: "apiKey"
+  },
+  blaxel: {
+    BL_API_KEY: "apiKey",
+    BL_WORKSPACE: "workspace"
+  },
+  namespace: {
+    NSC_TOKEN: "token"
   }
-  if (env[ENV_KEYS.DAYTONA]) {
-    available.push("daytona");
+};
+var PROVIDER_DASHBOARD_URLS = {
+  e2b: "https://e2b.dev/dashboard",
+  modal: "https://modal.com/settings",
+  railway: "https://railway.app/account/tokens",
+  render: "https://dashboard.render.com/account",
+  daytona: "https://daytona.io/dashboard",
+  vercel: "https://vercel.com/account/tokens",
+  runloop: "https://runloop.ai/dashboard",
+  cloudflare: "https://dash.cloudflare.com/profile/api-tokens",
+  codesandbox: "https://codesandbox.io/dashboard/settings",
+  blaxel: "https://blaxel.ai/dashboard",
+  namespace: "https://cloud.namespace.so"
+};
+function isValidProvider(name) {
+  return name in PROVIDER_AUTH;
+}
+function buildProviderHeaders(provider, config) {
+  const headers = {};
+  const headerMap = PROVIDER_HEADERS[provider];
+  for (const [configKey, headerName] of Object.entries(headerMap)) {
+    const value = config[configKey];
+    if (value) {
+      headers[headerName] = value;
+    }
   }
-  return available;
+  return headers;
 }
-function autoSelectProvider() {
-  const available = detectAvailableProviders();
-  return available.length > 0 ? available[0] : void 0;
+function getProviderConfigFromEnv(provider) {
+  const config = {};
+  const envMap = PROVIDER_ENV_MAP[provider];
+  for (const [envVar, configKey] of Object.entries(envMap)) {
+    const value = process.env[envVar];
+    if (value) {
+      config[configKey] = value;
+    }
+  }
+  return config;
 }
-function normalizeContainerConfig(container) {
-  if (!container) {
-    return void 0;
+function isProviderAuthComplete(provider) {
+  const authOptions = PROVIDER_AUTH[provider];
+  for (const option of authOptions) {
+    const allPresent = option.every((envVar) => !!process.env[envVar]);
+    if (allPresent) return true;
   }
-  if (typeof container === "string") {
-    return { image: container };
+  return false;
+}
+function getMissingEnvVars(provider) {
+  const authOptions = PROVIDER_AUTH[provider];
+  let bestOption = null;
+  for (const option of authOptions) {
+    const missing = [];
+    let presentCount = 0;
+    for (const envVar of option) {
+      if (process.env[envVar]) {
+        presentCount++;
+      } else {
+        missing.push(envVar);
+      }
+    }
+    if (missing.length === 0) return [];
+    if (!bestOption || presentCount > bestOption.presentCount) {
+      bestOption = { presentCount, missing };
+    }
   }
-  if (!container.image) {
-    throw new ConfigurationError("Container configuration must include an image", "config");
+  return bestOption?.missing ?? [];
+}
+
+// src/constants.ts
+var GATEWAY_URL = "https://gateway.computesdk.com";
+var PROVIDER_PRIORITY = [
+  "e2b",
+  "railway",
+  "render",
+  "daytona",
+  "modal",
+  "runloop",
+  "vercel",
+  "cloudflare",
+  "codesandbox",
+  "blaxel",
+  "namespace"
+];
+var PROVIDER_ENV_VARS = {
+  e2b: ["E2B_API_KEY"],
+  railway: ["RAILWAY_API_KEY", "RAILWAY_PROJECT_ID", "RAILWAY_ENVIRONMENT_ID"],
+  render: ["RENDER_API_KEY", "RENDER_OWNER_ID"],
+  daytona: ["DAYTONA_API_KEY"],
+  modal: ["MODAL_TOKEN_ID", "MODAL_TOKEN_SECRET"],
+  runloop: ["RUNLOOP_API_KEY"],
+  vercel: ["VERCEL_TOKEN", "VERCEL_TEAM_ID", "VERCEL_PROJECT_ID"],
+  cloudflare: ["CLOUDFLARE_API_TOKEN", "CLOUDFLARE_ACCOUNT_ID"],
+  codesandbox: ["CSB_API_KEY"],
+  blaxel: ["BL_API_KEY", "BL_WORKSPACE"],
+  namespace: ["NSC_TOKEN"]
+};
+
+// src/auto-detect.ts
+function isGatewayModeEnabled() {
+  return !!(typeof process !== "undefined" && process.env?.COMPUTESDK_API_KEY);
+}
+function hasProviderEnv(provider) {
+  if (typeof process === "undefined") return false;
+  const requiredVars = PROVIDER_ENV_VARS[provider];
+  if (!requiredVars) return false;
+  return requiredVars.every((varName) => !!process.env?.[varName]);
+}
+function getProviderEnvStatus(provider) {
+  const requiredVars = PROVIDER_ENV_VARS[provider];
+  if (typeof process === "undefined" || !requiredVars) {
+    return { provider, present: [], missing: requiredVars ? [...requiredVars] : [], isComplete: false };
   }
-  return container;
+  const present = requiredVars.filter((varName) => !!process.env?.[varName]);
+  const missing = requiredVars.filter((varName) => !process.env?.[varName]);
+  return {
+    provider,
+    present: [...present],
+    missing: [...missing],
+    isComplete: missing.length === 0
+  };
 }
-function getDefaultRuntime(provider, runtime) {
-  if (runtime) {
-    return runtime;
+function detectProvider() {
+  if (typeof process === "undefined") return null;
+  const explicit = process.env.COMPUTESDK_PROVIDER?.toLowerCase();
+  if (explicit && hasProviderEnv(explicit)) {
+    return explicit;
   }
-  switch (provider) {
-    case "e2b":
-      return "python";
-    case "vercel":
-      return "node";
-    case "daytona":
-      return "python";
-    default:
-      return "node";
+  if (explicit && !hasProviderEnv(explicit)) {
+    console.warn(
+      `\u26A0\uFE0F  COMPUTESDK_PROVIDER is set to "${explicit}" but required credentials are missing.
+   Required: ${PROVIDER_ENV_VARS[explicit]?.join(", ") || "unknown"}
+   Falling back to auto-detection...`
+    );
+  }
+  for (const provider of PROVIDER_PRIORITY) {
+    if (hasProviderEnv(provider)) {
+      return provider;
+    }
   }
+  return null;
 }
-function validateProviderApiKey(provider) {
-  let envKey;
+function getProviderHeaders(provider) {
+  if (typeof process === "undefined") return {};
+  const headers = {};
   switch (provider) {
     case "e2b":
-      envKey = ENV_KEYS.E2B;
+      if (process.env.E2B_API_KEY) {
+        headers["X-E2B-API-Key"] = process.env.E2B_API_KEY;
+      }
       break;
-    case "vercel":
-      envKey = ENV_KEYS.VERCEL;
+    case "railway":
+      if (process.env.RAILWAY_API_KEY) {
+        headers["X-Railway-API-Key"] = process.env.RAILWAY_API_KEY;
+      }
+      if (process.env.RAILWAY_PROJECT_ID) {
+        headers["X-Railway-Project-ID"] = process.env.RAILWAY_PROJECT_ID;
+      }
+      if (process.env.RAILWAY_ENVIRONMENT_ID) {
+        headers["X-Railway-Environment-ID"] = process.env.RAILWAY_ENVIRONMENT_ID;
+      }
       break;
     case "daytona":
-      envKey = ENV_KEYS.DAYTONA;
+      if (process.env.DAYTONA_API_KEY) {
+        headers["X-Daytona-API-Key"] = process.env.DAYTONA_API_KEY;
+      }
+      break;
+    case "modal":
+      if (process.env.MODAL_TOKEN_ID) {
+        headers["X-Modal-Token-ID"] = process.env.MODAL_TOKEN_ID;
+      }
+      if (process.env.MODAL_TOKEN_SECRET) {
+        headers["X-Modal-Token-Secret"] = process.env.MODAL_TOKEN_SECRET;
+      }
+      break;
+    case "runloop":
+      if (process.env.RUNLOOP_API_KEY) {
+        headers["X-Runloop-API-Key"] = process.env.RUNLOOP_API_KEY;
+      }
+      break;
+    case "vercel":
+      if (process.env.VERCEL_TOKEN) {
+        headers["X-Vercel-Token"] = process.env.VERCEL_TOKEN;
+      }
+      if (process.env.VERCEL_TEAM_ID) {
+        headers["X-Vercel-Team-ID"] = process.env.VERCEL_TEAM_ID;
+      }
+      if (process.env.VERCEL_PROJECT_ID) {
+        headers["X-Vercel-Project-ID"] = process.env.VERCEL_PROJECT_ID;
+      }
+      break;
+    case "cloudflare":
+      if (process.env.CLOUDFLARE_API_TOKEN) {
+        headers["X-Cloudflare-API-Token"] = process.env.CLOUDFLARE_API_TOKEN;
+      }
+      if (process.env.CLOUDFLARE_ACCOUNT_ID) {
+        headers["X-Cloudflare-Account-ID"] = process.env.CLOUDFLARE_ACCOUNT_ID;
+      }
+      break;
+    case "codesandbox":
+      if (process.env.CSB_API_KEY) {
+        headers["X-CodeSandbox-API-Key"] = process.env.CSB_API_KEY;
+      }
+      break;
+    case "blaxel":
+      if (process.env.BL_API_KEY) {
+        headers["X-Blaxel-API-Key"] = process.env.BL_API_KEY;
+      }
+      if (process.env.BL_WORKSPACE) {
+        headers["X-Blaxel-Workspace"] = process.env.BL_WORKSPACE;
+      }
+      break;
+    case "namespace":
+      if (process.env.NSC_TOKEN) {
+        headers["X-Namespace-Token"] = process.env.NSC_TOKEN;
+      }
       break;
-    case "auto":
-      return;
-    // Will be handled by auto-selection
-    default:
-      throw new ConfigurationError(`Unknown provider: ${provider}`, "config");
-  }
-  const env = typeof process !== "undefined" ? process.env : {};
-  if (!env[envKey]) {
-    const available = detectAvailableProviders();
-    const suggestions = available.length > 0 ? `Available providers: ${available.join(", ")}` : `No provider API keys found. Set ${Object.values(ENV_KEYS).join(" or ")} environment variables.`;
-    throw new ConfigurationError(
-      `Missing API key for provider '${provider}'. ${suggestions}`,
-      provider
-    );
   }
+  return headers;
 }
-function normalizeSandboxConfig(config) {
-  const normalized = {
-    provider: config?.provider || "auto",
-    timeout: config?.timeout || DEFAULT_TIMEOUT
+function autoConfigureCompute() {
+  if (!isGatewayModeEnabled()) {
+    return null;
+  }
+  const provider = detectProvider();
+  if (!provider) {
+    const detectionResults = PROVIDER_PRIORITY.map((p) => getProviderEnvStatus(p));
+    const statusLines = detectionResults.map((result) => {
+      const status = result.isComplete ? "\u2705" : result.present.length > 0 ? "\u26A0\uFE0F " : "\u274C";
+      const ratio = `${result.present.length}/${result.present.length + result.missing.length}`;
+      let line = `  ${status} ${result.provider.padEnd(12)} ${ratio} credentials`;
+      if (result.present.length > 0 && result.missing.length > 0) {
+        line += ` (missing: ${result.missing.join(", ")})`;
+      }
+      return line;
+    });
+    throw new Error(
+      `COMPUTESDK_API_KEY is set but no provider detected.
+
+Provider detection results:
+` + statusLines.join("\n") + `
+
+To fix this, set one of the following:
+
+  E2B:        export E2B_API_KEY=xxx
+  Railway:    export RAILWAY_API_KEY=xxx RAILWAY_PROJECT_ID=xxx RAILWAY_ENVIRONMENT_ID=xxx
+  Daytona:    export DAYTONA_API_KEY=xxx
+  Modal:      export MODAL_TOKEN_ID=xxx MODAL_TOKEN_SECRET=xxx
+  Runloop:    export RUNLOOP_API_KEY=xxx
+  Vercel:     export VERCEL_TOKEN=xxx VERCEL_TEAM_ID=xxx VERCEL_PROJECT_ID=xxx
+  Cloudflare: export CLOUDFLARE_API_TOKEN=xxx CLOUDFLARE_ACCOUNT_ID=xxx
+  CodeSandbox: export CSB_API_KEY=xxx
+  Blaxel:     export BL_API_KEY=xxx BL_WORKSPACE=xxx
+  Namespace:  export NSC_TOKEN=xxx
+
+Or set COMPUTESDK_PROVIDER to specify explicitly:
+  export COMPUTESDK_PROVIDER=e2b
+
+Docs: https://computesdk.com/docs/quickstart`
+    );
+  }
+  const gatewayUrl = process.env.COMPUTESDK_GATEWAY_URL || GATEWAY_URL;
+  const computesdkApiKey = process.env.COMPUTESDK_API_KEY;
+  const providerHeaders = getProviderHeaders(provider);
+  try {
+    new URL(gatewayUrl);
+  } catch (error) {
+    throw new Error(
+      `Invalid gateway URL: "${gatewayUrl}"
+
+The URL must be a valid HTTP/HTTPS URL.
+Check your COMPUTESDK_GATEWAY_URL environment variable.`
+    );
+  }
+  if (process.env.COMPUTESDK_DEBUG) {
+    console.log(`\u2728 ComputeSDK: Auto-detected ${provider} provider`);
+    console.log(`\u{1F310} Gateway: ${gatewayUrl}`);
+    console.log(`\u{1F511} Provider headers:`, Object.keys(providerHeaders).join(", "));
+  }
+  const config = {
+    apiKey: computesdkApiKey,
+    gatewayUrl,
+    provider,
+    providerHeaders
   };
-  if (normalized.provider === "auto") {
-    const autoProvider = autoSelectProvider();
-    if (!autoProvider) {
-      throw new ConfigurationError(
-        `No provider API keys found. Set one of the following environment variables: ${Object.values(ENV_KEYS).join(", ")}`,
-        "config"
-      );
+  return config;
+}
+
+// src/explicit-config.ts
+function buildProviderHeaders2(config) {
+  const headers = {};
+  const provider = config.provider;
+  const headerMap = PROVIDER_HEADERS[provider];
+  const providerConfig = config[provider];
+  if (!providerConfig || !headerMap) return headers;
+  for (const [configKey, headerName] of Object.entries(headerMap)) {
+    const value = providerConfig[configKey];
+    if (value) {
+      headers[headerName] = value;
     }
-    normalized.provider = autoProvider;
-  } else {
-    validateProviderApiKey(normalized.provider);
   }
-  if (config?.runtime) {
-    normalized.runtime = config.runtime;
-  } else if (!config?.container) {
-    normalized.runtime = getDefaultRuntime(normalized.provider);
+  return headers;
+}
+function validateProviderConfig(config) {
+  const provider = config.provider;
+  const authOptions = PROVIDER_AUTH[provider];
+  const providerConfig = config[provider];
+  const dashboardUrl = PROVIDER_DASHBOARD_URLS[provider];
+  if (!authOptions) {
+    throw new Error(`Unknown provider: ${provider}`);
   }
-  if (config?.container) {
-    normalized.container = normalizeContainerConfig(config.container);
+  for (const option of authOptions) {
+    const allPresent = option.every((envVar) => {
+      const configField = envVarToConfigField(provider, envVar);
+      return providerConfig?.[configField];
+    });
+    if (allPresent) return;
   }
-  return normalized;
-}
+  const configExample = buildConfigExample(provider, authOptions);
+  throw new Error(
+    `Missing ${provider} configuration. When using provider: '${provider}', you must provide:
+${configExample}
 
-// src/utils.ts
-async function executeSandbox(params) {
-  return await params.sandbox.execute(params.code, params.runtime);
+Get your credentials at: ${dashboardUrl}`
+  );
 }
-async function runCode(params) {
-  return await params.sandbox.runCode(params.code, params.runtime);
+function envVarToConfigField(provider, envVar) {
+  return PROVIDER_ENV_MAP[provider]?.[envVar] ?? envVar.toLowerCase();
 }
-async function runCommand(params) {
-  return await params.sandbox.runCommand(params.command, params.args);
+function buildConfigExample(provider, authOptions) {
+  if (authOptions.length === 1) {
+    const fields = authOptions[0].map((envVar) => {
+      const field = envVarToConfigField(provider, envVar);
+      return `${field}: '...'`;
+    });
+    return `  ${provider}: { ${fields.join(", ")} }`;
+  }
+  const options = authOptions.map((option, i) => {
+    const fields = option.map((envVar) => {
+      const field = envVarToConfigField(provider, envVar);
+      return `${field}: '...'`;
+    });
+    return `  Option ${i + 1}:
+    ${provider}: { ${fields.join(", ")} }`;
+  });
+  return options.join("\n\n");
+}
+function createConfigFromExplicit(config) {
+  const computesdkApiKey = config.computesdkApiKey || config.apiKey;
+  if (!computesdkApiKey) {
+    throw new Error(
+      `Missing ComputeSDK API key. Set 'computesdkApiKey' in your config.
+
+Example:
+  compute.setConfig({
+    provider: 'e2b',
+    computesdkApiKey: process.env.COMPUTESDK_API_KEY,
+    e2b: { apiKey: process.env.E2B_API_KEY }
+  })
+
+Get your API key at: https://computesdk.com/dashboard`
+    );
+  }
+  validateProviderConfig(config);
+  const providerHeaders = buildProviderHeaders2(config);
+  return {
+    apiKey: computesdkApiKey,
+    gatewayUrl: config.gatewayUrl || GATEWAY_URL,
+    provider: config.provider,
+    providerHeaders,
+    requestTimeoutMs: config.requestTimeoutMs,
+    WebSocket: config.WebSocket
+  };
 }
-async function retry(fn, options = {}) {
-  const {
-    maxAttempts = 3,
-    delay = 1e3,
-    backoff = 2,
-    onRetry
-  } = options;
-  let lastError;
-  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+
+// src/compute-daemon/lifecycle.ts
+async function waitForComputeReady(client, options = {}) {
+  const maxRetries = options.maxRetries ?? 30;
+  const initialDelayMs = options.initialDelayMs ?? 500;
+  const maxDelayMs = options.maxDelayMs ?? 5e3;
+  const backoffFactor = options.backoffFactor ?? 1.5;
+  let lastError = null;
+  let currentDelay = initialDelayMs;
+  for (let i = 0; i < maxRetries; i++) {
     try {
-      return await fn();
+      await client.health();
+      if (process.env.COMPUTESDK_DEBUG) {
+        console.log(`[Lifecycle] Sandbox ready after ${i + 1} attempt${i === 0 ? "" : "s"}`);
+      }
+      return;
     } catch (error) {
       lastError = error instanceof Error ? error : new Error(String(error));
-      if (attempt === maxAttempts - 1) {
-        throw lastError;
-      }
-      if (onRetry) {
-        onRetry(lastError, attempt + 1);
+      if (i === maxRetries - 1) {
+        throw new Error(
+          `Sandbox failed to become ready after ${maxRetries} attempts.
+Last error: ${lastError.message}
+
+Possible causes:
+  1. Sandbox failed to start (check provider dashboard for errors)
+  2. Network connectivity issues between your app and the sandbox
+  3. Sandbox is taking longer than expected to initialize
+  4. Invalid sandbox URL or authentication credentials
+
+Troubleshooting:
+  - Check sandbox logs in your provider dashboard
+  - Verify your network connection
+  - Try increasing maxRetries if initialization is slow
+  - Enable debug mode: export COMPUTESDK_DEBUG=1`
+        );
       }
-      const currentDelay = delay * Math.pow(backoff, attempt);
       await new Promise((resolve) => setTimeout(resolve, currentDelay));
+      currentDelay = Math.min(currentDelay * backoffFactor, maxDelayMs);
     }
   }
-  throw lastError;
 }
 
-// src/registry.ts
-function createComputeRegistry(providers) {
-  if (!providers || Object.keys(providers).length === 0) {
-    throw new ConfigurationError("Provider registry requires at least one provider", "registry");
+// src/compute.ts
+async function gatewayFetch(url, config, options = {}) {
+  const timeout = config.requestTimeoutMs ?? 3e4;
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+  try {
+    const response = await fetch(url, {
+      ...options,
+      signal: controller.signal,
+      headers: {
+        "Content-Type": "application/json",
+        "X-ComputeSDK-API-Key": config.apiKey,
+        "X-Provider": config.provider,
+        ...config.providerHeaders,
+        ...options.headers
+      }
+    });
+    clearTimeout(timeoutId);
+    if (!response.ok) {
+      if (response.status === 404) {
+        return { success: false };
+      }
+      const errorText = await response.text().catch(() => response.statusText);
+      let errorMessage = `Gateway API error: ${errorText}`;
+      if (response.status === 401) {
+        errorMessage = `Invalid ComputeSDK API key. Check your COMPUTESDK_API_KEY environment variable.`;
+      } else if (response.status === 403) {
+        errorMessage = `Access forbidden. Your API key may not have permission to use provider "${config.provider}".`;
+      }
+      throw new Error(errorMessage);
+    }
+    return await response.json();
+  } catch (error) {
+    clearTimeout(timeoutId);
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new Error(`Request timed out after ${timeout}ms`);
+    }
+    throw error;
   }
-  function sandbox(id) {
-    const parts = id.split(":");
-    if (parts.length < 1) {
-      throw new ConfigurationError(`Invalid sandbox ID format: ${id}`, "registry");
+}
+async function waitForSandboxStatus(config, endpoint, body, options = {}) {
+  const maxWaitMs = options.maxWaitMs ?? 6e4;
+  const initialDelayMs = 500;
+  const maxDelayMs = 2e3;
+  const backoffFactor = 1.5;
+  const startTime = Date.now();
+  let currentDelay = initialDelayMs;
+  while (Date.now() - startTime < maxWaitMs) {
+    const result = await gatewayFetch(endpoint, config, {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+    if (!result.success || !result.data) {
+      return result;
     }
-    const providerName = parts[0];
-    const providerFactory = providers[providerName];
-    if (!providerFactory) {
-      const availableProviders = Object.keys(providers).join(", ");
-      throw new ConfigurationError(
-        `Provider '${providerName}' not found in registry. Available providers: ${availableProviders}`,
-        "registry"
-      );
+    if (result.data.status !== "creating") {
+      return result;
     }
-    if (parts.length === 1) {
-      return providerFactory();
-    } else if (parts.length === 2) {
-      const runtimeOrImage = parts[1];
-      if (isRuntime(runtimeOrImage)) {
-        return providerFactory({ runtime: runtimeOrImage });
-      }
-      return providerFactory({ container: { image: runtimeOrImage } });
-    } else {
-      const containerImage = parts.slice(1).join(":");
-      return providerFactory({ container: { image: containerImage } });
+    if (process.env.COMPUTESDK_DEBUG) {
+      console.log(`[Compute] Sandbox still creating, waiting ${currentDelay}ms...`);
     }
+    await new Promise((resolve) => setTimeout(resolve, currentDelay));
+    currentDelay = Math.min(currentDelay * backoffFactor, maxDelayMs);
   }
-  return { sandbox };
-}
-function isRuntime(value) {
-  return ["node", "python"].includes(value);
+  throw new Error(
+    `Sandbox is still being created after ${maxWaitMs}ms. This may indicate the sandbox failed to start. Check your provider dashboard.`
+  );
 }
-
-// src/providers/base.ts
-import { v4 as uuidv4 } from "uuid";
-var BaseProvider = class {
-  /**
-   * Create a new base provider
-   * 
-   * @param provider Provider identifier
-   * @param timeout Execution timeout in milliseconds
-   */
-  constructor(provider, timeout) {
-    /** Specification version */
-    this.specificationVersion = "v1";
-    this.provider = provider;
-    this.sandboxId = uuidv4();
-    this.timeout = timeout;
+var ComputeManager = class {
+  constructor() {
+    this.config = null;
+    this.autoConfigured = false;
+    this.sandbox = {
+      /**
+       * Create a new sandbox
+       *
+       * @example
+       * ```typescript
+       * const sandbox = await compute.sandbox.create({
+       *   directory: '/custom/path',
+       *   overlays: [
+       *     {
+       *       source: '/templates/nextjs',
+       *       target: 'app',
+       *       strategy: 'smart',
+       *     },
+       *   ],
+       *   servers: [
+       *     {
+       *       slug: 'web',
+       *       start: 'npm run dev',
+       *       path: '/app',
+       *     },
+       *   ],
+       * });
+       * ```
+       */
+      create: async (options) => {
+        const config = this.getGatewayConfig();
+        const result = await gatewayFetch(`${config.gatewayUrl}/v1/sandboxes`, config, {
+          method: "POST",
+          body: JSON.stringify(options || {})
+        });
+        if (!result.success || !result.data) {
+          throw new Error(`Gateway returned invalid response`);
+        }
+        const { sandboxId, url, token, provider, metadata, name, namespace, overlays, servers } = result.data;
+        const sandbox = new Sandbox({
+          sandboxUrl: url,
+          sandboxId,
+          provider,
+          token: token || config.apiKey,
+          metadata: {
+            ...metadata,
+            ...name && { name },
+            ...namespace && { namespace },
+            ...overlays && { overlays },
+            ...servers && { servers }
+          },
+          WebSocket: config.WebSocket || globalThis.WebSocket,
+          destroyHandler: async () => {
+            await gatewayFetch(`${config.gatewayUrl}/v1/sandboxes/${sandboxId}`, config, {
+              method: "DELETE"
+            });
+          }
+        });
+        await waitForComputeReady(sandbox);
+        return sandbox;
+      },
+      /**
+       * Get an existing sandbox by ID
+       */
+      getById: async (sandboxId) => {
+        const config = this.getGatewayConfig();
+        const result = await gatewayFetch(`${config.gatewayUrl}/v1/sandboxes/${sandboxId}`, config);
+        if (!result.success || !result.data) {
+          return null;
+        }
+        const { url, token, provider, metadata } = result.data;
+        const sandbox = new Sandbox({
+          sandboxUrl: url,
+          sandboxId,
+          provider,
+          token: token || config.apiKey,
+          metadata,
+          WebSocket: config.WebSocket || globalThis.WebSocket,
+          destroyHandler: async () => {
+            await gatewayFetch(`${config.gatewayUrl}/v1/sandboxes/${sandboxId}`, config, {
+              method: "DELETE"
+            });
+          }
+        });
+        await waitForComputeReady(sandbox);
+        return sandbox;
+      },
+      /**
+       * List all active sandboxes
+       */
+      list: async () => {
+        throw new Error(
+          "The gateway does not support listing sandboxes. Use getById() with a known sandbox ID instead."
+        );
+      },
+      /**
+       * Destroy a sandbox
+       */
+      destroy: async (sandboxId) => {
+        const config = this.getGatewayConfig();
+        await gatewayFetch(`${config.gatewayUrl}/v1/sandboxes/${sandboxId}`, config, {
+          method: "DELETE"
+        });
+      },
+      /**
+       * Find existing or create new sandbox by (namespace, name)
+       */
+      findOrCreate: async (options) => {
+        const config = this.getGatewayConfig();
+        const { name, namespace, ...restOptions } = options;
+        const result = await waitForSandboxStatus(
+          config,
+          `${config.gatewayUrl}/v1/sandboxes/find-or-create`,
+          {
+            namespace: namespace || "default",
+            name,
+            ...restOptions
+          }
+        );
+        if (!result.success || !result.data) {
+          throw new Error(`Gateway returned invalid response`);
+        }
+        const { sandboxId, url, token, provider, metadata } = result.data;
+        const sandbox = new Sandbox({
+          sandboxUrl: url,
+          sandboxId,
+          provider,
+          token: token || config.apiKey,
+          metadata: {
+            ...metadata,
+            name: result.data.name,
+            namespace: result.data.namespace
+          },
+          WebSocket: config.WebSocket || globalThis.WebSocket,
+          destroyHandler: async () => {
+            await gatewayFetch(`${config.gatewayUrl}/v1/sandboxes/${sandboxId}`, config, {
+              method: "DELETE"
+            });
+          }
+        });
+        await waitForComputeReady(sandbox);
+        return sandbox;
+      },
+      /**
+       * Find existing sandbox by (namespace, name) without creating
+       */
+      find: async (options) => {
+        const config = this.getGatewayConfig();
+        const result = await waitForSandboxStatus(
+          config,
+          `${config.gatewayUrl}/v1/sandboxes/find`,
+          {
+            namespace: options.namespace || "default",
+            name: options.name
+          }
+        );
+        if (!result.success || !result.data) {
+          return null;
+        }
+        const { sandboxId, url, token, provider, metadata, name, namespace } = result.data;
+        const sandbox = new Sandbox({
+          sandboxUrl: url,
+          sandboxId,
+          provider,
+          token: token || config.apiKey,
+          metadata: {
+            ...metadata,
+            name,
+            namespace
+          },
+          WebSocket: config.WebSocket || globalThis.WebSocket,
+          destroyHandler: async () => {
+            await gatewayFetch(`${config.gatewayUrl}/v1/sandboxes/${sandboxId}`, config, {
+              method: "DELETE"
+            });
+          }
+        });
+        await waitForComputeReady(sandbox);
+        return sandbox;
+      },
+      /**
+       * Extend sandbox timeout/expiration
+       */
+      extendTimeout: async (sandboxId, options) => {
+        const config = this.getGatewayConfig();
+        const duration = options?.duration ?? 9e5;
+        await gatewayFetch(`${config.gatewayUrl}/v1/sandboxes/${sandboxId}/extend`, config, {
+          method: "POST",
+          body: JSON.stringify({ duration })
+        });
+      }
+    };
   }
   /**
-   * Execute code in the sandbox
-   * 
-   * @param code Code to execute
-   * @param runtime Optional runtime to use
-   * @returns Execution result
+   * Lazy auto-configure from environment if not explicitly configured
    */
-  async execute(code, runtime) {
-    const startTime = Date.now();
-    try {
-      const timeoutPromise = new Promise((_, reject) => {
-        setTimeout(() => {
-          reject(new TimeoutError(
-            `Execution timed out after ${this.timeout}ms`,
-            this.provider,
-            this.timeout,
-            this.sandboxId
-          ));
-        }, this.timeout);
-      });
-      const result = await Promise.race([
-        this.doExecute(code, runtime),
-        timeoutPromise
-      ]);
-      const executionTime = Date.now() - startTime;
-      return {
-        ...result,
-        executionTime,
-        sandboxId: this.sandboxId,
-        provider: this.provider
-      };
-    } catch (error) {
-      if (error instanceof Error && error.name.includes("Error") && "code" in error) {
-        throw error;
-      }
-      throw new ProviderError(
-        `Execution failed: ${error instanceof Error ? error.message : String(error)}`,
-        this.provider,
-        error instanceof Error ? error : void 0,
-        this.sandboxId
-      );
+  ensureConfigured() {
+    if (this.config) return;
+    if (this.autoConfigured) return;
+    const config = autoConfigureCompute();
+    this.autoConfigured = true;
+    if (config) {
+      this.config = config;
     }
   }
   /**
-   * Kill the sandbox
-   * 
-   * @returns Promise that resolves when the sandbox is killed
+   * Get gateway config, throwing if not configured
    */
-  async kill() {
-    try {
-      await this.doKill();
-    } catch (error) {
-      throw new ProviderError(
-        `Failed to kill sandbox: ${error instanceof Error ? error.message : String(error)}`,
-        this.provider,
-        error instanceof Error ? error : void 0,
-        this.sandboxId
+  getGatewayConfig() {
+    this.ensureConfigured();
+    if (!this.config) {
+      throw new Error(
+        `No ComputeSDK configuration found.
+
+Options:
+1. Zero-config: Set COMPUTESDK_API_KEY and provider credentials (e.g., E2B_API_KEY)
+2. Explicit: Call compute.setConfig({ provider: "e2b", computesdkApiKey: "...", e2b: { apiKey: "..." } })
+3. Use provider directly: import { e2b } from '@computesdk/e2b'
+
+Docs: https://computesdk.com/docs/quickstart`
       );
     }
+    return this.config;
   }
   /**
-   * Get information about the sandbox
+   * Explicitly configure the compute singleton
    * 
-   * @returns Sandbox information
-   */
-  async getInfo() {
-    try {
-      return await this.doGetInfo();
-    } catch (error) {
-      throw new ProviderError(
-        `Failed to get sandbox info: ${error instanceof Error ? error.message : String(error)}`,
-        this.provider,
-        error instanceof Error ? error : void 0,
-        this.sandboxId
-      );
-    }
-  }
-  /**
-   * Execute code in a runtime environment
+   * @example
+   * ```typescript
+   * import { compute } from 'computesdk';
    * 
-   * @param code Code to execute
-   * @param runtime Optional runtime to use
-   * @returns Execution result
-   */
-  async runCode(code, runtime) {
-    const startTime = Date.now();
-    try {
-      const timeoutPromise = new Promise((_, reject) => {
-        setTimeout(() => {
-          reject(new TimeoutError(
-            `Code execution timed out after ${this.timeout}ms`,
-            this.provider,
-            this.timeout,
-            this.sandboxId
-          ));
-        }, this.timeout);
-      });
-      const result = await Promise.race([
-        this.doRunCode ? this.doRunCode(code, runtime) : this.doExecute(code, runtime),
-        timeoutPromise
-      ]);
-      const executionTime = Date.now() - startTime;
-      return {
-        ...result,
-        executionTime,
-        sandboxId: this.sandboxId,
-        provider: this.provider
-      };
-    } catch (error) {
-      if (error instanceof Error && error.name.includes("Error") && "code" in error) {
-        throw error;
-      }
-      throw new ProviderError(
-        `Code execution failed: ${error instanceof Error ? error.message : String(error)}`,
-        this.provider,
-        error instanceof Error ? error : void 0,
-        this.sandboxId
-      );
-    }
-  }
-  /**
-   * Execute shell commands
+   * compute.setConfig({
+   *   provider: 'e2b',
+   *   apiKey: 'computesdk_xxx',
+   *   e2b: { apiKey: 'e2b_xxx' }
+   * });
    * 
-   * @param command Command to execute
-   * @param args Command arguments
-   * @returns Execution result
+   * const sandbox = await compute.sandbox.create();
+   * ```
    */
-  async runCommand(command, args = []) {
-    const startTime = Date.now();
-    try {
-      const timeoutPromise = new Promise((_, reject) => {
-        setTimeout(() => {
-          reject(new TimeoutError(
-            `Command execution timed out after ${this.timeout}ms`,
-            this.provider,
-            this.timeout,
-            this.sandboxId
-          ));
-        }, this.timeout);
-      });
-      const result = await Promise.race([
-        this.doRunCommand ? this.doRunCommand(command, args) : this.doExecute(`${command} ${args.join(" ")}`, "node"),
-        timeoutPromise
-      ]);
-      const executionTime = Date.now() - startTime;
-      return {
-        ...result,
-        executionTime,
-        sandboxId: this.sandboxId,
-        provider: this.provider
-      };
-    } catch (error) {
-      if (error instanceof Error && error.name.includes("Error") && "code" in error) {
-        throw error;
-      }
-      throw new ProviderError(
-        `Command execution failed: ${error instanceof Error ? error.message : String(error)}`,
-        this.provider,
-        error instanceof Error ? error : void 0,
-        this.sandboxId
-      );
-    }
-  }
-};
-var BaseFileSystem = class {
-  constructor(provider, sandboxId) {
-    this.provider = provider;
-    this.sandboxId = sandboxId;
-  }
-  async readFile(path) {
-    try {
-      return await this.doReadFile(path);
-    } catch (error) {
-      throw new ProviderError(
-        `Failed to read file: ${error instanceof Error ? error.message : String(error)}`,
-        this.provider,
-        error instanceof Error ? error : void 0,
-        this.sandboxId
-      );
-    }
-  }
-  async writeFile(path, content) {
-    try {
-      await this.doWriteFile(path, content);
-    } catch (error) {
-      throw new ProviderError(
-        `Failed to write file: ${error instanceof Error ? error.message : String(error)}`,
-        this.provider,
-        error instanceof Error ? error : void 0,
-        this.sandboxId
-      );
-    }
-  }
-  async mkdir(path) {
-    try {
-      await this.doMkdir(path);
-    } catch (error) {
-      throw new ProviderError(
-        `Failed to create directory: ${error instanceof Error ? error.message : String(error)}`,
-        this.provider,
-        error instanceof Error ? error : void 0,
-        this.sandboxId
-      );
-    }
-  }
-  async readdir(path) {
-    try {
-      return await this.doReaddir(path);
-    } catch (error) {
-      throw new ProviderError(
-        `Failed to read directory: ${error instanceof Error ? error.message : String(error)}`,
-        this.provider,
-        error instanceof Error ? error : void 0,
-        this.sandboxId
-      );
-    }
-  }
-  async exists(path) {
-    try {
-      return await this.doExists(path);
-    } catch (error) {
-      return false;
-    }
-  }
-  async remove(path) {
-    try {
-      await this.doRemove(path);
-    } catch (error) {
-      throw new ProviderError(
-        `Failed to remove: ${error instanceof Error ? error.message : String(error)}`,
-        this.provider,
-        error instanceof Error ? error : void 0,
-        this.sandboxId
-      );
-    }
+  setConfig(config) {
+    const gatewayConfig = createConfigFromExplicit(config);
+    this.config = gatewayConfig;
+    this.autoConfigured = false;
   }
 };
-var BaseTerminal = class {
-  constructor(provider, sandboxId) {
-    this.provider = provider;
-    this.sandboxId = sandboxId;
-  }
-  async create(options) {
-    try {
-      return await this.doCreate(options);
-    } catch (error) {
-      throw new ProviderError(
-        `Failed to create terminal: ${error instanceof Error ? error.message : String(error)}`,
-        this.provider,
-        error instanceof Error ? error : void 0,
-        this.sandboxId
-      );
-    }
-  }
-  async list() {
-    try {
-      return await this.doList();
-    } catch (error) {
-      throw new ProviderError(
-        `Failed to list terminals: ${error instanceof Error ? error.message : String(error)}`,
-        this.provider,
-        error instanceof Error ? error : void 0,
-        this.sandboxId
-      );
-    }
-  }
-};
-
-// src/sdk.ts
-var ComputeSDK = class {
-  /**
-   * Create a new sandbox with the specified configuration
-   * 
-   * @param config Optional sandbox configuration
-   * @returns Configured sandbox instance
-   */
-  static createSandbox(config) {
-    const normalizedConfig = normalizeSandboxConfig(config);
-    const providerName = normalizedConfig.provider;
-    try {
-      const providerPackage = `@computesdk/${providerName}`;
-      const provider = __require(providerPackage);
-      const factory = provider[providerName];
-      if (!factory) {
-        throw new ConfigurationError(
-          `Provider package ${providerPackage} does not export a '${providerName}' function`,
-          "sdk"
-        );
-      }
-      return factory(normalizedConfig);
-    } catch (error) {
-      if (error instanceof ConfigurationError) {
-        throw error;
-      }
-      if (error.code === "MODULE_NOT_FOUND") {
-        throw new ConfigurationError(
-          `Provider '${providerName}' not installed. Run: npm install @computesdk/${providerName}`,
-          "sdk"
-        );
+var singletonInstance = new ComputeManager();
+function computeFactory(config) {
+  const gatewayConfig = createConfigFromExplicit(config);
+  const manager = new ComputeManager();
+  manager["config"] = gatewayConfig;
+  return manager;
+}
+var compute = new Proxy(
+  computeFactory,
+  {
+    get(_target, prop, _receiver) {
+      const singleton = singletonInstance;
+      const value = singleton[prop];
+      if (typeof value === "function") {
+        return value.bind(singletonInstance);
       }
-      throw new ConfigurationError(
-        `Failed to load provider '${providerName}': ${error.message}`,
-        "sdk"
-      );
+      return value;
+    },
+    apply(_target, _thisArg, args) {
+      return computeFactory(args[0]);
     }
   }
-  /**
-   * Detect available providers based on environment variables
-   * 
-   * @returns Array of available provider types
-   */
-  static detectProviders() {
-    return detectAvailableProviders();
-  }
-};
-
-// src/index.ts
-var index_default = ComputeSDK;
+);
 export {
-  AuthenticationError,
-  BaseFileSystem,
-  BaseProvider,
-  BaseTerminal,
-  ComputeError,
-  ComputeSDK,
-  ConfigurationError,
-  DEFAULT_TIMEOUT,
-  ENV_KEYS,
-  ExecutionError,
-  ProviderError,
-  ProviderUnavailableError,
-  TimeoutError,
-  autoSelectProvider,
-  createComputeRegistry,
-  index_default as default,
-  detectAvailableProviders,
-  executeSandbox,
-  getDefaultRuntime,
-  normalizeContainerConfig,
-  normalizeSandboxConfig,
-  retry,
-  runCode,
-  runCommand,
-  validateProviderApiKey
+  CommandExitError,
+  FileWatcher,
+  GATEWAY_URL,
+  Sandbox as GatewaySandbox,
+  MessageType,
+  PROVIDER_AUTH,
+  PROVIDER_DASHBOARD_URLS,
+  PROVIDER_ENV_MAP,
+  PROVIDER_ENV_VARS,
+  PROVIDER_HEADERS,
+  PROVIDER_NAMES,
+  PROVIDER_PRIORITY,
+  Sandbox,
+  SignalService,
+  TerminalInstance,
+  autoConfigureCompute,
+  buildProviderHeaders,
+  buildSetupPayload,
+  compute,
+  decodeBinaryMessage,
+  detectProvider,
+  encodeBinaryMessage,
+  encodeSetupPayload,
+  getMissingEnvVars,
+  getProviderConfigFromEnv,
+  getProviderHeaders,
+  isCommandExitError,
+  isGatewayModeEnabled,
+  isProviderAuthComplete,
+  isValidProvider
 };
 //# sourceMappingURL=index.mjs.map