instavm 0.16.0 → 0.17.0

package/dist/index.mjs

@@ -31,6 +31,11 @@ var QuotaExceededError = class extends InstaVMError {
     super(message, { ...options, statusCode: 402 });
   }
 };
+var ForbiddenError = class extends InstaVMError {
+  constructor(message = "Forbidden", options) {
+    super(message, { ...options, statusCode: 403 });
+  }
+};
 var NetworkError = class extends InstaVMError {
   constructor(message = "Network error", options) {
     super(message, options);
@@ -125,11 +130,17 @@ async function withRetry(fn, options) {
   throw lastError;
 }
 
+// src/version.ts
+var INSTAVM_JS_SDK_VERSION = "0.17.0";
+
 // src/client/HTTPClient.ts
 var HTTPClient = class {
   get apiKey() {
     return this.config.apiKey;
   }
+  get baseURL() {
+    return this.config.baseURL;
+  }
   constructor(config) {
     this.config = config;
     this.client = axios.create({
@@ -137,7 +148,7 @@ var HTTPClient = class {
       timeout: config.timeout,
       headers: {
         "Content-Type": "application/json",
-        "User-Agent": "instavm-js-sdk/0.16.0"
+        "User-Agent": `instavm-js-sdk/${INSTAVM_JS_SDK_VERSION}`
       }
     });
     this.setupInterceptors();
@@ -170,6 +181,11 @@ var HTTPClient = class {
               statusCode: status,
               response: data
             });
+          case 403:
+            throw new ForbiddenError(message, {
+              statusCode: status,
+              response: data
+            });
           case 429: {
             const retryAfter = parseInt(
               axiosError.response?.headers["retry-after"] || "60"
@@ -523,12 +539,24 @@ var BrowserSession = class extends EventEmitter {
    */
   async scroll(options = {}) {
     this.ensureActive();
+    if (!options.selector && options.x == null && options.y == null) {
+      throw new BrowserInteractionError(
+        "At least one of 'selector', 'x', or 'y' must be provided for scrolling."
+      );
+    }
     const requestData = {
       session_id: this.sessionId,
-      x: options.x || 0,
-      y: options.y || 500,
       behavior: options.behavior || "auto"
     };
+    if (options.selector) {
+      requestData.selector = options.selector;
+    }
+    if (options.x != null) {
+      requestData.x = options.x;
+    }
+    if (options.y != null) {
+      requestData.y = options.y;
+    }
     try {
       await this.httpClient.post(
         "/v1/browser/interactions/scroll",
@@ -575,11 +603,13 @@ var BrowserSession = class extends EventEmitter {
   async extractElements(selector, attributes = ["text"], options = {}) {
     this.ensureActive();
     const requestData = {
-      selector,
       attributes,
       session_id: this.sessionId,
       max_results: options.maxResults || 100
     };
+    if (selector) {
+      requestData.selector = selector;
+    }
     try {
       const response = await this.httpClient.post(
         "/v1/browser/interactions/extract",
@@ -646,6 +676,29 @@ var BrowserSession = class extends EventEmitter {
       );
     }
   }
+  /**
+   * Wait for a string condition (parity with Python ``wait_for``).
+   */
+  async waitFor(condition, selector, timeout = 3e4) {
+    this.ensureActive();
+    const requestData = {
+      session_id: this.sessionId,
+      condition,
+      timeout
+    };
+    if (selector) {
+      requestData.selector = selector;
+    }
+    try {
+      return await this.httpClient.post("/v1/browser/interactions/wait", requestData);
+    } catch (error) {
+      const errorMessage = getErrorMessage(error);
+      if (errorMessage.includes("timeout")) {
+        throw new BrowserTimeoutError(`Wait condition timeout: ${condition}`, { cause: error });
+      }
+      throw new BrowserInteractionError(`Wait failed: ${errorMessage}`, { cause: error });
+    }
+  }
   /**
    * Wait for a condition
    */
@@ -715,12 +768,45 @@ var BrowserSession = class extends EventEmitter {
   }
 };
 
+// src/utils/path.ts
+function encodePathSegment(value) {
+  const segment = String(value);
+  if (segment === "." || segment === "..") {
+    throw new Error("Path traversal not allowed in path segment");
+  }
+  return encodeURIComponent(segment);
+}
+function encodePathSegments(path2) {
+  const segments = path2.replace(/^\/+/, "").split("/").filter((segment) => segment.length > 0 && segment !== ".");
+  if (segments.some((segment) => segment === "..")) {
+    throw new Error("Path traversal not allowed in proxy path");
+  }
+  return segments.map((segment) => encodeURIComponent(segment)).join("/");
+}
+
 // src/client/BrowserManager.ts
 var BrowserManager = class {
-  constructor(httpClient, local = false) {
+  constructor(httpClient, local = false, getClient) {
     this.activeSessions = /* @__PURE__ */ new Map();
+    this._defaultBrowserSessionId = null;
+    this._defaultSessionPromise = null;
     this.httpClient = httpClient;
     this.local = local;
+    this.getClient = getClient;
+  }
+  async ensureDefaultBrowserSessionId() {
+    if (this._defaultBrowserSessionId) {
+      return this._defaultBrowserSessionId;
+    }
+    if (!this._defaultSessionPromise) {
+      this._defaultSessionPromise = this.createSession().catch((err) => {
+        this._defaultSessionPromise = null;
+        throw err;
+      });
+    }
+    const session = await this._defaultSessionPromise;
+    this._defaultBrowserSessionId = session.sessionId;
+    return this._defaultBrowserSessionId;
   }
   /**
    * Create a new browser session
@@ -737,10 +823,7 @@ var BrowserManager = class {
       user_agent: options.userAgent
     };
     try {
-      const response = await this.httpClient.post(
-        "/v1/browser/sessions/",
-        requestData
-      );
+      const response = await this.httpClient.post("/v1/browser/sessions/", requestData);
       if (!response.session_id) {
         throw new BrowserSessionError("No session ID returned from server");
       }
@@ -748,14 +831,17 @@ var BrowserManager = class {
       this.activeSessions.set(response.session_id, session);
       session.on("close", () => {
         this.activeSessions.delete(response.session_id);
+        if (this._defaultBrowserSessionId === response.session_id) {
+          this._defaultBrowserSessionId = null;
+          this._defaultSessionPromise = null;
+        }
       });
       return session;
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
-      throw new BrowserSessionError(
-        `Failed to create browser session: ${errorMessage}`,
-        { cause: error }
-      );
+      throw new BrowserSessionError(`Failed to create browser session: ${errorMessage}`, {
+        cause: error
+      });
     }
   }
   /**
@@ -763,9 +849,8 @@ var BrowserManager = class {
    */
   async getSession(sessionId) {
     try {
-      const response = await this.httpClient.get(
-        `/v1/browser/sessions/${sessionId}`
-      );
+      const safe = encodePathSegment(sessionId);
+      const response = await this.httpClient.get(`/v1/browser/sessions/${safe}`);
       return {
         sessionId: response.session_id,
         status: response.status || "active",
@@ -776,10 +861,7 @@ var BrowserManager = class {
       };
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
-      throw new BrowserSessionError(
-        `Failed to get session info: ${errorMessage}`,
-        { cause: error }
-      );
+      throw new BrowserSessionError(`Failed to get session info: ${errorMessage}`, { cause: error });
     }
   }
   /**
@@ -788,10 +870,11 @@ var BrowserManager = class {
   async listSessions() {
     try {
       const response = await this.httpClient.get("/v1/browser/sessions/");
-      if (!Array.isArray(response.sessions)) {
+      const sessions = Array.isArray(response) ? response : response?.sessions;
+      if (!Array.isArray(sessions)) {
         return [];
       }
-      return response.sessions.map((session) => ({
+      return sessions.map((session) => ({
         sessionId: session.session_id,
         status: session.status || "active",
         createdAt: session.created_at,
@@ -801,52 +884,62 @@ var BrowserManager = class {
       }));
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
-      throw new BrowserSessionError(
-        `Failed to list sessions: ${errorMessage}`,
-        { cause: error }
-      );
+      throw new BrowserSessionError(`Failed to list sessions: ${errorMessage}`, { cause: error });
     }
   }
-  /**
-   * Get a locally tracked session
-   */
   getLocalSession(sessionId) {
     return this.activeSessions.get(sessionId);
   }
-  /**
-   * Get all locally tracked sessions
-   */
+  attachSession(sessionId) {
+    const existing = this.activeSessions.get(sessionId);
+    if (existing) {
+      return existing;
+    }
+    const session = new BrowserSession(sessionId, this.httpClient);
+    this.activeSessions.set(sessionId, session);
+    session.on("close", () => {
+      this.activeSessions.delete(sessionId);
+      if (this._defaultBrowserSessionId === sessionId) {
+        this._defaultBrowserSessionId = null;
+        this._defaultSessionPromise = null;
+      }
+    });
+    return session;
+  }
   getLocalSessions() {
     return Array.from(this.activeSessions.values());
   }
-  /**
-   * Close all active sessions
-   */
   async closeAllSessions() {
     const sessions = Array.from(this.activeSessions.values());
-    await Promise.allSettled(
-      sessions.map((session) => session.close())
-    );
+    await Promise.allSettled(sessions.map((session) => session.close()));
     this.activeSessions.clear();
+    this._defaultBrowserSessionId = null;
+    this._defaultSessionPromise = null;
   }
   /**
-   * Navigate to a URL (local mode support - no session required)
+   * Navigate to a URL (local: no session; cloud: auto default browser session)
    */
   async navigate(url, options = {}) {
     if (!this.local) {
-      throw new UnsupportedOperationError(
-        "navigate() without session is only supported in local mode. In cloud mode, create a session first."
-      );
+      const client = this.getClient?.();
+      if (!client) {
+        throw new UnsupportedOperationError("BrowserManager is missing InstaVM client reference.");
+      }
+      const sid = await this.ensureDefaultBrowserSessionId();
+      const raw = await client.browserNavigate(url, sid, options.waitTimeout ?? 3e4);
+      return {
+        success: raw.success !== false,
+        url: raw.url || url,
+        title: raw.title,
+        status: raw.status
+      };
     }
     const requestData = {
       url,
       wait_timeout: options.waitTimeout || 3e4
     };
     try {
-      const response = await this.httpClient.post(
-        "/v1/browser/interactions/navigate",
-        requestData
-      );
+      const response = await this.httpClient.post("/v1/browser/interactions/navigate", requestData);
       return {
         success: response.success !== false,
         url: response.url || url,
@@ -855,20 +948,112 @@ var BrowserManager = class {
       };
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
-      throw new BrowserNavigationError(
-        `Navigation failed: ${errorMessage}`,
-        { cause: error }
-      );
+      throw new BrowserNavigationError(`Navigation failed: ${errorMessage}`, { cause: error });
+    }
+  }
+  async click(selector, sessionId, force = false, timeout = 3e4) {
+    if (!this.local) {
+      const client = this.getClient?.();
+      if (!client) {
+        throw new UnsupportedOperationError("BrowserManager is missing InstaVM client reference.");
+      }
+      const sid = sessionId ?? await this.ensureDefaultBrowserSessionId();
+      await client.browserClick(selector, sid, force, timeout);
+      return;
+    }
+    throw new UnsupportedOperationError("click() without session is only supported in cloud mode via InstaVM.");
+  }
+  async type(selector, text, sessionId, delay = 100, timeout = 3e4) {
+    if (!this.local) {
+      const client = this.getClient?.();
+      if (!client) {
+        throw new UnsupportedOperationError("BrowserManager is missing InstaVM client reference.");
+      }
+      const sid = sessionId ?? await this.ensureDefaultBrowserSessionId();
+      await client.browserType(selector, text, sid, delay, timeout);
+      return;
     }
+    throw new UnsupportedOperationError("type() requires cloud mode with InstaVM client.");
+  }
+  async fill(selector, value, sessionId, timeout = 3e4) {
+    if (!this.local) {
+      const client = this.getClient?.();
+      if (!client) {
+        throw new UnsupportedOperationError("BrowserManager is missing InstaVM client reference.");
+      }
+      const sid = sessionId ?? await this.ensureDefaultBrowserSessionId();
+      await client.browserFill(selector, value, sid, timeout);
+      return;
+    }
+    throw new UnsupportedOperationError("fill() requires cloud mode with InstaVM client.");
+  }
+  async scroll(options = {}) {
+    if (!this.local) {
+      const client = this.getClient?.();
+      if (!client) {
+        throw new UnsupportedOperationError("BrowserManager is missing InstaVM client reference.");
+      }
+      const sid = options.sessionId ?? await this.ensureDefaultBrowserSessionId();
+      await client.browserScroll(sid, options.selector ?? null, options.x ?? null, options.y ?? null);
+      return;
+    }
+    throw new UnsupportedOperationError("scroll() cloud convenience requires InstaVM client.");
+  }
+  async waitFor(condition, selector, sessionId, timeout = 3e4) {
+    if (!this.local) {
+      const client = this.getClient?.();
+      if (!client) {
+        throw new UnsupportedOperationError("BrowserManager is missing InstaVM client reference.");
+      }
+      const sid = sessionId ?? await this.ensureDefaultBrowserSessionId();
+      return client.browserWait(condition, sid, selector ?? null, timeout);
+    }
+    throw new UnsupportedOperationError("waitFor() requires cloud mode with InstaVM client.");
+  }
+  async extractElements(selector, sessionId, attributes, options = {}) {
+    if (!this.local) {
+      const client = this.getClient?.();
+      if (!client) {
+        throw new UnsupportedOperationError("BrowserManager is missing InstaVM client reference.");
+      }
+      const sid = sessionId ?? await this.ensureDefaultBrowserSessionId();
+      const attrs = attributes ?? ["text"];
+      const result = await client.browserExtractElements(sid, selector ?? null, attrs);
+      if (options.maxResults !== void 0 && Array.isArray(result)) {
+        return result.slice(0, options.maxResults);
+      }
+      return result;
+    }
+    throw new UnsupportedOperationError("extractElements() requires cloud mode with InstaVM client.");
   }
   /**
-   * Extract LLM-friendly content (local mode support - no session required)
+   * Extract LLM-friendly content (local: URL required; cloud: optional session)
    */
   async extractContent(options = {}) {
     if (!this.local) {
-      throw new UnsupportedOperationError(
-        "extractContent() without session is only supported in local mode. In cloud mode, create a session first."
+      const client = this.getClient?.();
+      if (!client) {
+        throw new UnsupportedOperationError("BrowserManager is missing InstaVM client reference.");
+      }
+      let sid = options.sessionId;
+      if (!sid) {
+        sid = await this.ensureDefaultBrowserSessionId();
+      }
+      const raw = await client.browserExtractContent(
+        sid,
+        options.url ?? null,
+        options.includeInteractive !== false,
+        options.includeAnchors !== false,
+        options.maxAnchors ?? 50
       );
+      return {
+        readableContent: {
+          ...raw.readable_content || {},
+          content: raw.readable_content?.content || ""
+        },
+        interactiveElements: raw.interactive_elements,
+        contentAnchors: raw.content_anchors
+      };
     }
     if (!options.url) {
       throw new BrowserInteractionError("url is required in local mode");
@@ -880,10 +1065,7 @@ var BrowserManager = class {
       max_anchors: options.maxAnchors ?? 50
     };
     try {
-      const response = await this.httpClient.post(
-        "/v1/browser/interactions/content",
-        requestData
-      );
+      const response = await this.httpClient.post("/v1/browser/interactions/content", requestData);
       return {
         readableContent: {
           ...response.readable_content || {},
@@ -894,36 +1076,33 @@ var BrowserManager = class {
       };
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
-      throw new BrowserInteractionError(
-        `Content extraction failed: ${errorMessage}`,
-        { cause: error }
-      );
+      throw new BrowserInteractionError(`Content extraction failed: ${errorMessage}`, { cause: error });
     }
   }
   /**
-   * Clean up resources
+   * Closes the default browser session if one was created for cloud convenience.
    */
+  async close() {
+    if (!this._defaultBrowserSessionId) {
+      return;
+    }
+    const sid = this._defaultBrowserSessionId;
+    const session = this.activeSessions.get(sid);
+    if (session) {
+      try {
+        await session.close();
+      } catch {
+      }
+    }
+    this._defaultBrowserSessionId = null;
+    this._defaultSessionPromise = null;
+  }
   async dispose() {
+    await this.close();
     await this.closeAllSessions();
   }
 };
 
-// src/utils/path.ts
-function encodePathSegment(value) {
-  const segment = String(value);
-  if (segment === "." || segment === "..") {
-    throw new Error("Path traversal not allowed in path segment");
-  }
-  return encodeURIComponent(segment);
-}
-function encodePathSegments(path2) {
-  const segments = path2.replace(/^\/+/, "").split("/").filter((segment) => segment.length > 0 && segment !== ".");
-  if (segments.some((segment) => segment === "..")) {
-    throw new Error("Path traversal not allowed in proxy path");
-  }
-  return segments.map((segment) => encodeURIComponent(segment)).join("/");
-}
-
 // src/client/VMsManager.ts
 var VMsManager = class {
   constructor(httpClient, local = false) {
@@ -1622,60 +1801,760 @@ var VolumesManager = class {
   }
 };
 
-// src/client/InstaVM.ts
-import FormData2 from "form-data";
-var InstaVM = class {
-  constructor(apiKey, options = {}) {
-    this._sessionId = null;
-    this._vmUsed = false;
-    this.local = options.local || false;
-    this.timeout = options.timeout || 3e5;
-    this.memory_mb = options.memory_mb;
-    this.cpu_count = options.cpu_count;
-    this.metadata = options.metadata;
-    this.env = options.env;
-    if (!this.local && !apiKey) {
-      throw new AuthenticationError("API key is required for cloud mode");
+// src/client/TapesManager.ts
+var TapesManager = class {
+  constructor(httpClient, local = false) {
+    this.httpClient = httpClient;
+    this.local = local;
+  }
+  ensureCloud(operation) {
+    if (this.local) {
+      throw new UnsupportedOperationError(
+        `${operation} is not supported in local mode.`
+      );
     }
-    const config = {
-      baseURL: this.local ? options.localURL || "http://coderunner.local:8222" : options.baseURL || "https://api.instavm.io",
-      timeout: this.timeout,
-      maxRetries: options.maxRetries || 3,
-      retryDelay: options.retryDelay || 1e3,
-      apiKey: apiKey || ""
+  }
+  authHeaders() {
+    return { "X-API-Key": this.httpClient.apiKey };
+  }
+  async start(sessionId, options = {}) {
+    this.ensureCloud("Tape start");
+    const safe = encodePathSegment(sessionId);
+    return this.httpClient.post(
+      `/v1/sessions/${safe}/tape/start`,
+      {
+        record_egress_content: options.recordEgressContent ?? false,
+        record_fs: options.recordFs ?? true,
+        retention_days: options.retentionDays ?? 7
+      },
+      this.authHeaders()
+    );
+  }
+  async stop(tapeId) {
+    this.ensureCloud("Tape stop");
+    const safe = encodePathSegment(tapeId);
+    return this.httpClient.post(
+      `/v1/tapes/${safe}/stop`,
+      void 0,
+      this.authHeaders()
+    );
+  }
+  async list(query = {}) {
+    this.ensureCloud("Tape listing");
+    const params = {
+      limit: query.limit ?? 50,
+      offset: query.offset ?? 0
     };
-    this.httpClient = new HTTPClient(config);
-    this.browser = new BrowserManager(this.httpClient, this.local);
-    this.vms = new VMsManager(this.httpClient, this.local);
-    this.snapshots = new SnapshotsManager(this.httpClient, this.local);
-    this.shares = new SharesManager(this.httpClient, this.local, () => this._sessionId);
-    this.customDomains = new CustomDomainsManager(this.httpClient, this.local);
-    this.computerUse = new ComputerUseManager(this.httpClient, this.local);
-    this.apiKeys = new APIKeysManager(this.httpClient, this.local);
-    this.audit = new AuditManager(this.httpClient, this.local);
-    this.webhooks = new WebhooksManager(this.httpClient, this.local);
-    this.volumes = new VolumesManager(this.httpClient, this.local);
+    if (query.sessionId !== void 0) params.session_id = query.sessionId;
+    if (query.vmId !== void 0) params.vm_id = query.vmId;
+    if (query.status !== void 0) params.status = query.status;
+    const result = await this.httpClient.get(
+      "/v1/tapes",
+      params,
+      this.authHeaders()
+    );
+    return Array.isArray(result) ? result : [];
   }
-  /**
-   * Ensure operation is not called in local mode
-   */
-  ensureNotLocal(operationName) {
+  async get(tapeId) {
+    this.ensureCloud("Tape lookup");
+    const safe = encodePathSegment(tapeId);
+    return this.httpClient.get(
+      `/v1/tapes/${safe}`,
+      void 0,
+      this.authHeaders()
+    );
+  }
+  async events(tapeId, query = {}) {
+    this.ensureCloud("Tape events");
+    const safe = encodePathSegment(tapeId);
+    const params = { limit: query.limit ?? 200 };
+    if (query.afterStep !== void 0) params.after_step = query.afterStep;
+    if (query.kind !== void 0) params.kind = query.kind;
+    const result = await this.httpClient.get(
+      `/v1/tapes/${safe}/events`,
+      params,
+      this.authHeaders()
+    );
+    return Array.isArray(result) ? result : [];
+  }
+  async appendEvent(tapeId, kind, options = {}) {
+    this.ensureCloud("Tape append event");
+    const safe = encodePathSegment(tapeId);
+    const body = { kind, payload: options.payload || {} };
+    if (options.stepId !== void 0) body.step_id = options.stepId;
+    if (options.parentStepId !== void 0) body.parent_step_id = options.parentStepId;
+    if (options.checkpointId !== void 0) body.checkpoint_id = options.checkpointId;
+    return this.httpClient.post(
+      `/v1/tapes/${safe}/events`,
+      body,
+      this.authHeaders()
+    );
+  }
+  async lanes(tapeId) {
+    this.ensureCloud("Tape lanes");
+    const safe = encodePathSegment(tapeId);
+    return this.httpClient.get(
+      `/v1/tapes/${safe}/lanes`,
+      void 0,
+      this.authHeaders()
+    );
+  }
+  async diff(tapeId, fromStep, toStep) {
+    this.ensureCloud("Tape diff");
+    const safe = encodePathSegment(tapeId);
+    return this.httpClient.get(
+      `/v1/tapes/${safe}/diff`,
+      { from: fromStep, to: toStep },
+      this.authHeaders()
+    );
+  }
+  async branch(tapeId, atStep, options = {}) {
+    this.ensureCloud("Tape branch");
+    const safe = encodePathSegment(tapeId);
+    return this.httpClient.post(
+      `/v1/tapes/${safe}/branch`,
+      { at_step: atStep, mode: options.mode || "live" },
+      this.authHeaders()
+    );
+  }
+  async delete(tapeId) {
+    this.ensureCloud("Tape deletion");
+    const safe = encodePathSegment(tapeId);
+    return this.httpClient.delete(
+      `/v1/tapes/${safe}`,
+      this.authHeaders()
+    );
+  }
+  async export(tapeId) {
+    this.ensureCloud("Tape export");
+    const safe = encodePathSegment(tapeId);
+    return this.httpClient.get(
+      `/v1/tapes/${safe}/export`,
+      void 0,
+      this.authHeaders()
+    );
+  }
+};
+
+// src/client/VaultsManager.ts
+var VaultsManager = class {
+  constructor(httpClient, local = false) {
+    this.httpClient = httpClient;
+    this.local = local;
+  }
+  ensureCloud() {
     if (this.local) {
       throw new UnsupportedOperationError(
-        `${operationName} is not supported in local mode. This operation is only available when using the cloud API.`
+        "Vault management is not supported in local mode."
       );
     }
   }
-  /**
-   * Execute code synchronously
-   *
-   * @param command - Command to execute
-   * @param options - Execution options
-   * @param options.timeout - Request timeout in milliseconds (used for HTTP request timeout and sent to API in seconds)
-   * @returns Execution result
-   */
-  async execute(command, options = {}) {
-    let sessionId = options.sessionId || this._sessionId;
+  auth() {
+    return { "X-API-Key": this.httpClient.apiKey };
+  }
+  async list() {
+    this.ensureCloud();
+    const result = await this.httpClient.get("/v1/vaults", void 0, this.auth());
+    if (Array.isArray(result)) return result;
+    return result?.vaults || [];
+  }
+  async create(name, description) {
+    this.ensureCloud();
+    const body = { name };
+    if (description !== void 0) body.description = description;
+    return this.httpClient.post("/v1/vaults", body, this.auth());
+  }
+  async get(vaultId) {
+    this.ensureCloud();
+    return this.httpClient.get(
+      `/v1/vaults/${encodePathSegment(vaultId)}`,
+      void 0,
+      this.auth()
+    );
+  }
+  async update(vaultId, updates) {
+    this.ensureCloud();
+    const body = {};
+    if (updates.name !== void 0) body.name = updates.name;
+    if (updates.description !== void 0) body.description = updates.description;
+    return this.httpClient.patch(
+      `/v1/vaults/${encodePathSegment(vaultId)}`,
+      body,
+      this.auth()
+    );
+  }
+  async delete(vaultId) {
+    this.ensureCloud();
+    return this.httpClient.delete(
+      `/v1/vaults/${encodePathSegment(vaultId)}`,
+      this.auth()
+    );
+  }
+  async discover(vaultId) {
+    this.ensureCloud();
+    return this.httpClient.get(
+      `/v1/vaults/${encodePathSegment(vaultId)}/discover`,
+      void 0,
+      this.auth()
+    );
+  }
+  async listCredentials(vaultId) {
+    this.ensureCloud();
+    const result = await this.httpClient.get(
+      `/v1/vaults/${encodePathSegment(vaultId)}/credentials`,
+      void 0,
+      this.auth()
+    );
+    if (Array.isArray(result)) return result;
+    return result?.credentials || [];
+  }
+  async addCredential(vaultId, name, value, options = {}) {
+    this.ensureCloud();
+    const body = {
+      name,
+      value,
+      credential_type: options.credentialType ?? "api_key"
+    };
+    if (options.description !== void 0) body.description = options.description;
+    return this.httpClient.post(
+      `/v1/vaults/${encodePathSegment(vaultId)}/credentials`,
+      body,
+      this.auth()
+    );
+  }
+  async rotateCredential(vaultId, credentialId, value) {
+    this.ensureCloud();
+    return this.httpClient.post(
+      `/v1/vaults/${encodePathSegment(vaultId)}/credentials/${encodePathSegment(credentialId)}/rotate`,
+      { value },
+      this.auth()
+    );
+  }
+  async deleteCredential(vaultId, credentialId) {
+    this.ensureCloud();
+    return this.httpClient.delete(
+      `/v1/vaults/${encodePathSegment(vaultId)}/credentials/${encodePathSegment(credentialId)}`,
+      this.auth()
+    );
+  }
+  async listServices(vaultId) {
+    this.ensureCloud();
+    const result = await this.httpClient.get(
+      `/v1/vaults/${encodePathSegment(vaultId)}/services`,
+      void 0,
+      this.auth()
+    );
+    if (Array.isArray(result)) return result;
+    return result?.services || [];
+  }
+  async addService(vaultId, host, authConfig, options = {}) {
+    this.ensureCloud();
+    const body = {
+      host,
+      auth_config: authConfig,
+      enabled: options.enabled ?? true
+    };
+    if (options.description !== void 0) body.description = options.description;
+    return this.httpClient.post(
+      `/v1/vaults/${encodePathSegment(vaultId)}/services`,
+      body,
+      this.auth()
+    );
+  }
+  async addServicesFromTemplates(vaultId, templateIds) {
+    this.ensureCloud();
+    return this.httpClient.post(
+      `/v1/vaults/${encodePathSegment(vaultId)}/services:from_template`,
+      { template_ids: templateIds },
+      this.auth()
+    );
+  }
+  async deleteService(vaultId, serviceId) {
+    this.ensureCloud();
+    return this.httpClient.delete(
+      `/v1/vaults/${encodePathSegment(vaultId)}/services/${encodePathSegment(serviceId)}`,
+      this.auth()
+    );
+  }
+  async getCatalog() {
+    this.ensureCloud();
+    const result = await this.httpClient.get(
+      "/v1/vaults/catalog",
+      void 0,
+      this.auth()
+    );
+    if (Array.isArray(result)) return result;
+    return result?.templates || [];
+  }
+  async getRequestLogs(vaultId, limit = 100) {
+    this.ensureCloud();
+    const result = await this.httpClient.get(
+      `/v1/vaults/${encodePathSegment(vaultId)}/request-logs`,
+      { limit },
+      this.auth()
+    );
+    if (Array.isArray(result)) return result;
+    return result?.logs || result?.request_logs || [];
+  }
+};
+
+// src/client/PTYManager.ts
+var PTYManager = class {
+  constructor(httpClient, local, getBaseURL) {
+    this.httpClient = httpClient;
+    this.local = local;
+    this.getBaseURL = getBaseURL;
+  }
+  ensureCloud() {
+    if (this.local) {
+      throw new UnsupportedOperationError(
+        "PTY management is not supported in local mode."
+      );
+    }
+  }
+  auth() {
+    return { "X-API-Key": this.httpClient.apiKey };
+  }
+  buildPayload(options) {
+    const payload = {
+      cols: options.cols ?? 80,
+      rows: options.rows ?? 24
+    };
+    if (options.command !== void 0) payload.shell = options.command;
+    if (options.ptyId !== void 0) payload.id = options.ptyId;
+    return payload;
+  }
+  buildWsUrl(path2) {
+    const trimmedBase = this.getBaseURL().replace(/\/+$/, "");
+    const base = trimmedBase.replace(/^http:\/\//, "ws://").replace(/^https:\/\//, "wss://");
+    const apiKey = encodeURIComponent(this.httpClient.apiKey || "");
+    return `${base}${path2}?api_key=${apiKey}`;
+  }
+  // -- Session-scoped --------------------------------------------------------
+  async create(sessionId, options = {}) {
+    this.ensureCloud();
+    return this.httpClient.post(
+      `/v1/sessions/${encodePathSegment(sessionId)}/pty/sessions`,
+      this.buildPayload(options),
+      this.auth()
+    );
+  }
+  async list(sessionId) {
+    this.ensureCloud();
+    const result = await this.httpClient.get(
+      `/v1/sessions/${encodePathSegment(sessionId)}/pty/sessions`,
+      void 0,
+      this.auth()
+    );
+    if (Array.isArray(result)) return result;
+    return result?.sessions || [];
+  }
+  async get(sessionId, ptyId) {
+    this.ensureCloud();
+    return this.httpClient.get(
+      `/v1/sessions/${encodePathSegment(sessionId)}/pty/sessions/${encodePathSegment(ptyId)}`,
+      void 0,
+      this.auth()
+    );
+  }
+  async resize(sessionId, ptyId, cols, rows) {
+    this.ensureCloud();
+    return this.httpClient.post(
+      `/v1/sessions/${encodePathSegment(sessionId)}/pty/sessions/${encodePathSegment(ptyId)}/resize`,
+      { cols, rows },
+      this.auth()
+    );
+  }
+  async kill(sessionId, ptyId) {
+    this.ensureCloud();
+    return this.httpClient.delete(
+      `/v1/sessions/${encodePathSegment(sessionId)}/pty/sessions/${encodePathSegment(ptyId)}`,
+      this.auth()
+    );
+  }
+  wsUrl(sessionId, ptyId) {
+    return this.buildWsUrl(
+      `/v1/sessions/${encodePathSegment(sessionId)}/pty/${encodePathSegment(ptyId)}/connect`
+    );
+  }
+  // -- VM-scoped (docker exec -it pattern) -----------------------------------
+  async createForVm(vmId, options = {}) {
+    this.ensureCloud();
+    return this.httpClient.post(
+      `/v1/vms/${encodePathSegment(vmId)}/pty/sessions`,
+      this.buildPayload(options),
+      this.auth()
+    );
+  }
+  async listForVm(vmId) {
+    this.ensureCloud();
+    const result = await this.httpClient.get(
+      `/v1/vms/${encodePathSegment(vmId)}/pty/sessions`,
+      void 0,
+      this.auth()
+    );
+    if (Array.isArray(result)) return result;
+    return result?.sessions || [];
+  }
+  async getForVm(vmId, ptyId) {
+    this.ensureCloud();
+    return this.httpClient.get(
+      `/v1/vms/${encodePathSegment(vmId)}/pty/sessions/${encodePathSegment(ptyId)}`,
+      void 0,
+      this.auth()
+    );
+  }
+  async resizeForVm(vmId, ptyId, cols, rows) {
+    this.ensureCloud();
+    return this.httpClient.post(
+      `/v1/vms/${encodePathSegment(vmId)}/pty/sessions/${encodePathSegment(ptyId)}/resize`,
+      { cols, rows },
+      this.auth()
+    );
+  }
+  async killForVm(vmId, ptyId) {
+    this.ensureCloud();
+    return this.httpClient.delete(
+      `/v1/vms/${encodePathSegment(vmId)}/pty/sessions/${encodePathSegment(ptyId)}`,
+      this.auth()
+    );
+  }
+  wsUrlForVm(vmId, ptyId) {
+    return this.buildWsUrl(
+      `/v1/vms/${encodePathSegment(vmId)}/pty/${encodePathSegment(ptyId)}/connect`
+    );
+  }
+};
+
+// src/client/RecordingsManager.ts
+import fs2 from "fs";
+import { stat, unlink } from "fs/promises";
+import { pipeline } from "stream/promises";
+import axios2 from "axios";
+var RecordingsManager = class {
+  constructor(httpClient, local, getBaseURL) {
+    this.httpClient = httpClient;
+    this.local = local;
+    this.getBaseURL = getBaseURL;
+  }
+  ensureCloud() {
+    if (this.local) {
+      throw new UnsupportedOperationError(
+        "Recording management is not supported in local mode."
+      );
+    }
+  }
+  auth() {
+    return { "X-API-Key": this.httpClient.apiKey };
+  }
+  sdkHeaders() {
+    return { "User-Agent": `instavm-js-sdk/${INSTAVM_JS_SDK_VERSION}` };
+  }
+  async list(query = {}) {
+    this.ensureCloud();
+    const params = {
+      limit: query.limit ?? 50,
+      offset: query.offset ?? 0
+    };
+    if (query.sessionId !== void 0) params.session_id = query.sessionId;
+    if (query.status !== void 0) params.status = query.status;
+    const result = await this.httpClient.get("/v1/recordings", params, this.auth());
+    return Array.isArray(result) ? result : [];
+  }
+  async get(recordingId) {
+    this.ensureCloud();
+    return this.httpClient.get(
+      `/v1/recordings/${encodePathSegment(recordingId)}`,
+      void 0,
+      this.auth()
+    );
+  }
+  /**
+   * Resolve the presigned download URL for a recording without following the
+   * 302 redirect. The returned URL is short-lived and pre-authorised.
+   */
+  async getDownloadUrl(recordingId) {
+    this.ensureCloud();
+    const url = `${this.getBaseURL().replace(/\/+$/, "")}/v1/recordings/${encodePathSegment(recordingId)}/download`;
+    const response = await axios2.request({
+      method: "GET",
+      url,
+      headers: {
+        ...this.auth(),
+        ...this.sdkHeaders()
+      },
+      maxRedirects: 0,
+      validateStatus: (status) => status >= 200 && status < 400
+    });
+    if ([301, 302, 303, 307, 308].includes(response.status)) {
+      const location = response.headers?.location || response.headers?.Location;
+      if (!location) {
+        throw new InstaVMError("Recording download response missing Location header");
+      }
+      return location;
+    }
+    throw new InstaVMError(
+      `Server did not redirect to a presigned URL (status=${response.status})`
+    );
+  }
+  /**
+   * Stream a recording to a local file using the presigned URL. The S3 URL
+   * must NOT carry our X-API-Key header — fetch it with a clean axios call.
+   */
+  async download(recordingId, outputPath) {
+    this.ensureCloud();
+    const presignedUrl = await this.getDownloadUrl(recordingId);
+    const response = await axios2.request({
+      method: "GET",
+      url: presignedUrl,
+      responseType: "stream",
+      headers: this.sdkHeaders()
+    });
+    const writer = fs2.createWriteStream(outputPath);
+    try {
+      await pipeline(response.data, writer);
+    } catch (error) {
+      await unlink(outputPath).catch(() => void 0);
+      throw error;
+    }
+    const fileStat = await stat(outputPath);
+    return { recordingId, path: outputPath, bytes: fileStat.size };
+  }
+  async delete(recordingId) {
+    this.ensureCloud();
+    return this.httpClient.delete(
+      `/v1/recordings/${encodePathSegment(recordingId)}`,
+      this.auth()
+    );
+  }
+};
+
+// src/client/CreditsManager.ts
+var CreditsManager = class {
+  constructor(httpClient, local = false) {
+    this.httpClient = httpClient;
+    this.local = local;
+  }
+  ensureCloud() {
+    if (this.local) {
+      throw new UnsupportedOperationError(
+        "Credits API is not supported in local mode."
+      );
+    }
+  }
+  auth() {
+    return { "X-API-Key": this.httpClient.apiKey };
+  }
+  async allocation() {
+    this.ensureCloud();
+    return this.httpClient.get(
+      "/v1/credits/allocation",
+      void 0,
+      this.auth()
+    );
+  }
+  async usage(period = "current_month", options = {}) {
+    this.ensureCloud();
+    const params = { period, limit: options.limit ?? 100 };
+    if (options.usageType !== void 0) params.usage_type = options.usageType;
+    const result = await this.httpClient.get("/v1/credits/usage", params, this.auth());
+    return Array.isArray(result) ? result : [];
+  }
+  async summary(period = "current_month") {
+    this.ensureCloud();
+    return this.httpClient.get(
+      "/v1/credits/summary",
+      { period },
+      this.auth()
+    );
+  }
+  async check(usageType, requiredCredits) {
+    this.ensureCloud();
+    return this.httpClient.get(
+      "/v1/credits/check",
+      { usage_type: usageType, required_credits: requiredCredits },
+      this.auth()
+    );
+  }
+  async rates() {
+    this.ensureCloud();
+    return this.httpClient.get(
+      "/v1/credits/rates",
+      void 0,
+      this.auth()
+    );
+  }
+  async usageTrends(period = "30d", granularity = "daily") {
+    this.ensureCloud();
+    return this.httpClient.get(
+      "/v1/credits/usage/trends",
+      { period, granularity },
+      this.auth()
+    );
+  }
+  async usageForecast() {
+    this.ensureCloud();
+    return this.httpClient.get(
+      "/v1/credits/usage/forecasting",
+      void 0,
+      this.auth()
+    );
+  }
+};
+
+// src/client/TapeContext.ts
+var TapeContext = class {
+  constructor(tapes, sessionId, startOpts) {
+    this.tapes = tapes;
+    this.sessionId = sessionId;
+    this.startOpts = startOpts;
+    this.info = null;
+  }
+  get id() {
+    return this.info?.id;
+  }
+  async start() {
+    if (!this.sessionId) {
+      throw new SessionError("Session ID not set. Please create a session first.");
+    }
+    this.info = await this.tapes.start(this.sessionId, this.startOpts);
+  }
+  async stop() {
+    if (!this.info?.id) {
+      return;
+    }
+    this.info = await this.tapes.stop(this.info.id);
+  }
+  async [Symbol.asyncDispose]() {
+    await this.stop();
+  }
+};
+
+// src/client/ToolCallRecorder.ts
+var ToolCallRecorder = class {
+  constructor(tapes, tapeId) {
+    this.tapes = tapes;
+    this.tapeId = tapeId;
+  }
+  async event(kind, payload, stepId) {
+    return this.tapes.appendEvent(this.tapeId, kind, {
+      payload: payload || {},
+      stepId
+    });
+  }
+  span(name, payload) {
+    return new ToolCallSpan(this, name, payload || {});
+  }
+};
+var ToolCallSpan = class {
+  constructor(recorder, name, startPayload) {
+    this.recorder = recorder;
+    this.name = name;
+    this.startPayload = startPayload;
+    this.endPayload = {};
+  }
+  attach(payload) {
+    Object.assign(this.endPayload, payload);
+  }
+  async enter() {
+    const result = await this.recorder.event("tool_call_start", {
+      name: this.name,
+      ...this.startPayload
+    });
+    this.stepId = result.step_id;
+  }
+  async exit(err) {
+    const payload = {
+      name: this.name,
+      ok: err === void 0 || err === null,
+      ...this.endPayload
+    };
+    if (err) {
+      payload.error = err instanceof Error ? err.message : String(err);
+    }
+    await this.recorder.event("tool_call_end", payload, this.stepId);
+  }
+};
+
+// src/client/InstaVM.ts
+import FormData2 from "form-data";
+var InstaVM = class {
+  constructor(apiKey, options = {}) {
+    this._sessionId = null;
+    this._vmUsed = false;
+    this.local = options.local || false;
+    this.timeout = options.timeout || 3e5;
+    this.memory_mb = options.memory_mb;
+    this.cpu_count = options.cpu_count;
+    this.metadata = options.metadata;
+    this.env = options.env;
+    this._autoStartSession = options.auto_start_session !== false;
+    if (!this.local && !apiKey) {
+      throw new AuthenticationError("API key is required for cloud mode");
+    }
+    const config = {
+      baseURL: this.local ? options.localURL || "http://coderunner.local:8222" : options.baseURL || "https://api.instavm.io",
+      timeout: this.timeout,
+      maxRetries: options.maxRetries || 3,
+      retryDelay: options.retryDelay || 1e3,
+      apiKey: apiKey || ""
+    };
+    this.httpClient = new HTTPClient(config);
+    this.browser = new BrowserManager(this.httpClient, this.local, () => this);
+    this.vms = new VMsManager(this.httpClient, this.local);
+    this.snapshots = new SnapshotsManager(this.httpClient, this.local);
+    this.shares = new SharesManager(this.httpClient, this.local, () => this._sessionId);
+    this.customDomains = new CustomDomainsManager(this.httpClient, this.local);
+    this.computerUse = new ComputerUseManager(this.httpClient, this.local);
+    this.apiKeys = new APIKeysManager(this.httpClient, this.local);
+    this.audit = new AuditManager(this.httpClient, this.local);
+    this.webhooks = new WebhooksManager(this.httpClient, this.local);
+    this.volumes = new VolumesManager(this.httpClient, this.local);
+    this.tapes = new TapesManager(this.httpClient, this.local);
+    this.vaults = new VaultsManager(this.httpClient, this.local);
+    this.pty = new PTYManager(this.httpClient, this.local, () => this.httpClient.baseURL);
+    this.recordings = new RecordingsManager(this.httpClient, this.local, () => this.httpClient.baseURL);
+    this.credits = new CreditsManager(this.httpClient, this.local);
+    if (this._autoStartSession && !this.local && apiKey) {
+      this.sessionBootstrap = this.createSession();
+      void this.sessionBootstrap.catch(() => void 0);
+    }
+  }
+  async awaitSessionBootstrap() {
+    if (this.sessionBootstrap) {
+      try {
+        await this.sessionBootstrap;
+      } finally {
+        this.sessionBootstrap = void 0;
+      }
+    }
+  }
+  /**
+   * Ensure operation is not called in local mode
+   */
+  ensureNotLocal(operationName) {
+    if (this.local) {
+      throw new UnsupportedOperationError(
+        `${operationName} is not supported in local mode. This operation is only available when using the cloud API.`
+      );
+    }
+  }
+  authHeaders() {
+    return { "X-API-Key": this.httpClient.apiKey };
+  }
+  /**
+   * Execute code synchronously
+   *
+   * @param command - Command to execute
+   * @param options - Execution options
+   * @param options.timeout - Request timeout in milliseconds (used for HTTP request timeout and sent to API in seconds)
+   * @returns Execution result
+   */
+  async execute(command, options = {}) {
+    if (!this.local) {
+      await this.awaitSessionBootstrap();
+    }
+    let sessionId = options.sessionId || this._sessionId;
     if (!this.local && !sessionId) {
       sessionId = await this.createSession();
     }
@@ -1728,6 +2607,7 @@ var InstaVM = class {
    */
   async executeAsync(command, options = {}) {
     this.ensureNotLocal("Async execution");
+    await this.awaitSessionBootstrap();
     let sessionId = options.sessionId || this._sessionId;
     if (!sessionId) {
       sessionId = await this.createSession();
@@ -1814,6 +2694,7 @@ var InstaVM = class {
    */
   async upload(files, options = {}) {
     this.ensureNotLocal("File upload");
+    await this.awaitSessionBootstrap();
     const sessionId = options.sessionId || this._sessionId;
     if (!sessionId) {
       throw new SessionError("Session ID not set. Please create a session first using createSession().");
@@ -1880,7 +2761,7 @@ var InstaVM = class {
         "/v1/sessions/session",
         requestBody
       );
-      if (response.session_id) {
+      if (response && response.session_id) {
         this._sessionId = response.session_id;
         return response.session_id;
       }
@@ -1946,10 +2827,11 @@ var InstaVM = class {
     if (port !== void 0) {
       params.port = port;
     }
+    const safeSid = encodePathSegment(targetSessionId);
     return this.httpClient.get(
-      `/v1/sessions/app-url/${targetSessionId}`,
+      `/v1/sessions/app-url/${safeSid}`,
       params,
-      { "X-API-Key": this.httpClient.apiKey }
+      this.authHeaders()
     );
   }
   /**
@@ -1983,10 +2865,11 @@ var InstaVM = class {
       throw new SessionError("No active session to get usage for");
     }
     try {
+      const safeSid = encodePathSegment(targetSessionId);
       const response = await this.httpClient.get(
-        `/v1/sessions/usage/${targetSessionId}`,
+        `/v1/sessions/usage/${safeSid}`,
         void 0,
-        { "X-API-Key": this.httpClient.apiKey }
+        this.authHeaders()
       );
       return {
         sessionsUsed: response.sessions_used || 0,
@@ -2022,12 +2905,429 @@ var InstaVM = class {
     if (!targetSessionId) {
       throw new SessionError("Session ID not set. Please create a session first.");
     }
+    const safeSid = encodePathSegment(targetSessionId);
     return this.httpClient.get(
-      `/v1/sessions/status/${targetSessionId}`,
+      `/v1/sessions/status/${safeSid}`,
       void 0,
-      { "X-API-Key": this.httpClient.apiKey }
+      this.authHeaders()
     );
   }
+  /**
+   * Get session record details from ``GET /v1/sessions/session/{session_id}`` (Python: ``get_session_info``).
+   */
+  async getSessionInfo(sessionId) {
+    this.ensureNotLocal("Session management");
+    const sid = sessionId || this._sessionId;
+    if (!sid) {
+      throw new SessionError("Session ID not set. Please create a session first.");
+    }
+    try {
+      const safeSid = encodePathSegment(sid);
+      const result = await this.httpClient.get(
+        `/v1/sessions/session/${safeSid}`,
+        void 0,
+        this.authHeaders()
+      );
+      if (typeof result !== "object" || result === null) {
+        throw new SessionError("Failed to get session info: non-JSON response");
+      }
+      return result;
+    } catch (error) {
+      if (error instanceof InstaVMError) {
+        throw error;
+      }
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new SessionError(`Failed to get session info: ${errorMessage}`, { cause: error });
+    }
+  }
+  /**
+   * Day-wise usage breakdown from ``GET /v1/users/me/usage-breakdown`` (Python: ``get_usage_breakdown``).
+   */
+  async getUsageBreakdown(options = {}) {
+    this.ensureNotLocal("Usage breakdown lookup");
+    const params = { days: options.days ?? 30 };
+    if (options.startDate !== void 0) {
+      params.start_date = options.startDate;
+    }
+    if (options.endDate !== void 0) {
+      params.end_date = options.endDate;
+    }
+    try {
+      const result = await this.httpClient.get(
+        "/v1/users/me/usage-breakdown",
+        params,
+        this.authHeaders()
+      );
+      if (typeof result !== "object" || result === null) {
+        throw new InstaVMError("Failed to fetch usage breakdown: non-JSON response");
+      }
+      return result;
+    } catch (error) {
+      if (error instanceof InstaVMError) {
+        throw error;
+      }
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new InstaVMError(`Failed to fetch usage breakdown: ${errorMessage}`, { cause: error });
+    }
+  }
+  /**
+   * Time-travel tape context manager (Python: ``tape()`` / ``TapeContext``).
+   */
+  tape(sessionId, options = {}) {
+    const sid = sessionId ?? this._sessionId ?? void 0;
+    return new TapeContext(this.tapes, sid, options);
+  }
+  /** Build a tool-call recorder for an active tape id (Python: ``ToolCallRecorder``). */
+  toolCallRecorder(tapeId) {
+    return new ToolCallRecorder(this.tapes, tapeId);
+  }
+  /**
+   * @deprecated Streaming is not supported by the API; yields a single chunk from ``execute``.
+   */
+  async *executeStreaming(command, onOutput) {
+    console.warn(
+      "executeStreaming is deprecated. The API does not support streaming execution. Use execute() or executeAsync() instead."
+    );
+    const result = await this.execute(command);
+    const output = result.stdout || "";
+    if (onOutput) {
+      onOutput(output);
+    }
+    yield output;
+  }
+  // --- Vault (flat API parity with Python InstaVM) ---
+  async listVaults() {
+    return this.vaults.list();
+  }
+  async createVault(name, description) {
+    return this.vaults.create(name, description);
+  }
+  async getVault(vaultId) {
+    return this.vaults.get(vaultId);
+  }
+  async updateVault(vaultId, updates) {
+    return this.vaults.update(vaultId, updates);
+  }
+  async deleteVault(vaultId) {
+    return this.vaults.delete(vaultId);
+  }
+  async discoverVault(vaultId) {
+    return this.vaults.discover(vaultId);
+  }
+  async listVaultCredentials(vaultId) {
+    return this.vaults.listCredentials(vaultId);
+  }
+  async addVaultCredential(vaultId, name, value, options = {}) {
+    return this.vaults.addCredential(vaultId, name, value, options);
+  }
+  async rotateVaultCredential(vaultId, credentialId, value) {
+    return this.vaults.rotateCredential(vaultId, credentialId, value);
+  }
+  async deleteVaultCredential(vaultId, credentialId) {
+    return this.vaults.deleteCredential(vaultId, credentialId);
+  }
+  async listVaultServices(vaultId) {
+    return this.vaults.listServices(vaultId);
+  }
+  async addVaultService(vaultId, host, authConfig, options = {}) {
+    return this.vaults.addService(vaultId, host, authConfig, options);
+  }
+  async deleteVaultService(vaultId, serviceId) {
+    return this.vaults.deleteService(vaultId, serviceId);
+  }
+  async addVaultServicesFromTemplates(vaultId, templateIds) {
+    return this.vaults.addServicesFromTemplates(vaultId, templateIds);
+  }
+  async getVaultCatalog() {
+    return this.vaults.getCatalog();
+  }
+  async getVaultRequestLogs(vaultId, limit = 100) {
+    return this.vaults.getRequestLogs(vaultId, limit);
+  }
+  // --- Browser (client-level parity with Python InstaVM) ---
+  async createBrowserSession(viewportWidth = 1920, viewportHeight = 1080, userAgent) {
+    this.ensureNotLocal("Browser session management");
+    const body = {
+      viewport_width: viewportWidth,
+      viewport_height: viewportHeight
+    };
+    if (userAgent) {
+      body.user_agent = userAgent;
+    }
+    try {
+      const result = await this.httpClient.post(
+        "/v1/browser/sessions/",
+        body,
+        this.authHeaders()
+      );
+      const sid = result.session_id;
+      if (!sid) {
+        throw new BrowserSessionError("No session ID returned from server");
+      }
+      return sid;
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new BrowserSessionError(`Failed to create browser session: ${msg}`, { cause: error });
+    }
+  }
+  async getBrowserSession(sessionId) {
+    this.ensureNotLocal("Browser session management");
+    const safe = encodePathSegment(sessionId);
+    try {
+      return await this.httpClient.get(
+        `/v1/browser/sessions/${safe}`,
+        void 0,
+        this.authHeaders()
+      );
+    } catch (error) {
+      const status = error.statusCode;
+      if (status === 404) {
+        throw new BrowserSessionError("Browser session not found or expired", { cause: error });
+      }
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new BrowserSessionError(`Failed to get browser session: ${msg}`, { cause: error });
+    }
+  }
+  async closeBrowserSession(sessionId) {
+    this.ensureNotLocal("Browser session management");
+    const safe = encodePathSegment(sessionId);
+    try {
+      await this.httpClient.delete(`/v1/browser/sessions/${safe}`, this.authHeaders());
+      return true;
+    } catch (error) {
+      const status = error.statusCode;
+      if (status === 404) {
+        return true;
+      }
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new BrowserSessionError(`Failed to close browser session: ${msg}`, { cause: error });
+    }
+  }
+  async listBrowserSessions() {
+    this.ensureNotLocal("Browser session management");
+    const result = await this.httpClient.get("/v1/browser/sessions/", void 0, this.authHeaders());
+    if (Array.isArray(result)) {
+      return result;
+    }
+    return result?.sessions || [];
+  }
+  async browserNavigate(url, sessionId, waitTimeout = 3e4) {
+    if (!this.local) {
+      if (!sessionId) {
+        throw new BrowserSessionError("session_id is required in cloud mode");
+      }
+    }
+    const data = { url, wait_timeout: waitTimeout };
+    if (!this.local && sessionId) {
+      data.session_id = sessionId;
+    }
+    try {
+      return await this.httpClient.post(
+        "/v1/browser/interactions/navigate",
+        data,
+        this.authHeaders()
+      );
+    } catch (error) {
+      const status = error.statusCode;
+      if (status === 404) {
+        throw new BrowserSessionError("Browser session not found or expired", { cause: error });
+      }
+      if (status === 408) {
+        throw new BrowserTimeoutError("Navigation timeout", { cause: error });
+      }
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new BrowserNavigationError(`Failed to navigate: ${msg}`, { cause: error });
+    }
+  }
+  async browserClick(selector, sessionId, force = false, timeout = 3e4) {
+    this.ensureNotLocal("Browser click interaction");
+    try {
+      return await this.httpClient.post(
+        "/v1/browser/interactions/click",
+        { selector, session_id: sessionId, force, timeout },
+        this.authHeaders()
+      );
+    } catch (error) {
+      const status = error.statusCode;
+      if (status === 404) {
+        throw new ElementNotFoundError(`Element not found: ${selector}`, selector, { cause: error });
+      }
+      if (status === 408) {
+        throw new BrowserTimeoutError("Click timeout", { cause: error });
+      }
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new BrowserInteractionError(`Failed to click element: ${msg}`, { cause: error });
+    }
+  }
+  async browserType(selector, text, sessionId, delay = 100, timeout = 3e4) {
+    this.ensureNotLocal("Browser type interaction");
+    try {
+      return await this.httpClient.post(
+        "/v1/browser/interactions/type",
+        { selector, text, session_id: sessionId, delay, timeout },
+        this.authHeaders()
+      );
+    } catch (error) {
+      const status = error.statusCode;
+      if (status === 404) {
+        throw new ElementNotFoundError(`Element not found: ${selector}`, selector, { cause: error });
+      }
+      if (status === 408) {
+        throw new BrowserTimeoutError("Type timeout", { cause: error });
+      }
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new BrowserInteractionError(`Failed to type text: ${msg}`, { cause: error });
+    }
+  }
+  async browserFill(selector, value, sessionId, timeout = 3e4) {
+    this.ensureNotLocal("Browser fill interaction");
+    try {
+      return await this.httpClient.post(
+        "/v1/browser/interactions/fill",
+        { selector, value, session_id: sessionId, timeout },
+        this.authHeaders()
+      );
+    } catch (error) {
+      const status = error.statusCode;
+      if (status === 404) {
+        throw new ElementNotFoundError(`Element not found: ${selector}`, selector, { cause: error });
+      }
+      if (status === 408) {
+        throw new BrowserTimeoutError("Fill timeout", { cause: error });
+      }
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new BrowserInteractionError(`Failed to fill form: ${msg}`, { cause: error });
+    }
+  }
+  async browserScroll(sessionId, selector, x, y) {
+    this.ensureNotLocal("Browser scroll interaction");
+    if (selector == null && x == null && y == null) {
+      throw new BrowserInteractionError(
+        "At least one of 'selector', 'x', or 'y' must be provided for scrolling."
+      );
+    }
+    const data = { session_id: sessionId };
+    if (selector) {
+      data.selector = selector;
+    }
+    if (x != null) {
+      data.x = x;
+    }
+    if (y != null) {
+      data.y = y;
+    }
+    try {
+      return await this.httpClient.post(
+        "/v1/browser/interactions/scroll",
+        data,
+        this.authHeaders()
+      );
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new BrowserInteractionError(`Failed to scroll: ${msg}`, { cause: error });
+    }
+  }
+  async browserWait(condition, sessionId, selector, timeout = 3e4) {
+    this.ensureNotLocal("Browser wait interaction");
+    const data = { condition, session_id: sessionId, timeout };
+    if (selector) {
+      data.selector = selector;
+    }
+    try {
+      return await this.httpClient.post(
+        "/v1/browser/interactions/wait",
+        data,
+        this.authHeaders()
+      );
+    } catch (error) {
+      const status = error.statusCode;
+      if (status === 408) {
+        throw new BrowserTimeoutError(`Wait timeout for condition: ${condition}`, { cause: error });
+      }
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new BrowserInteractionError(`Failed to wait for condition: ${msg}`, { cause: error });
+    }
+  }
+  async browserScreenshot(sessionId, fullPage = true, clip, format = "png", quality) {
+    this.ensureNotLocal("Browser screenshot");
+    const data = {
+      session_id: sessionId,
+      full_page: fullPage,
+      format
+    };
+    if (clip) {
+      data.clip = clip;
+    }
+    if (quality != null) {
+      data.quality = quality;
+    }
+    try {
+      const result = await this.httpClient.post(
+        "/v1/browser/interactions/screenshot",
+        data,
+        this.authHeaders()
+      );
+      return result.screenshot || "";
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new BrowserInteractionError(`Failed to take screenshot: ${msg}`, { cause: error });
+    }
+  }
+  async browserExtractElements(sessionId, selector, attributes) {
+    this.ensureNotLocal("Browser element extraction");
+    const data = { session_id: sessionId };
+    if (selector) {
+      data.selector = selector;
+    }
+    if (attributes?.length) {
+      data.attributes = attributes;
+    }
+    try {
+      const result = await this.httpClient.post(
+        "/v1/browser/interactions/extract",
+        data,
+        this.authHeaders()
+      );
+      return result.elements || [];
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new BrowserInteractionError(`Failed to extract elements: ${msg}`, { cause: error });
+    }
+  }
+  async browserExtractContent(sessionId, url, includeInteractive = true, includeAnchors = true, maxAnchors = 50) {
+    if (!this.local) {
+      if (!sessionId) {
+        throw new BrowserSessionError("session_id is required in cloud mode");
+      }
+    } else if (!url) {
+      throw new BrowserInteractionError("url is required in local mode");
+    }
+    const data = {
+      include_interactive: includeInteractive,
+      include_anchors: includeAnchors,
+      max_anchors: maxAnchors
+    };
+    if (!this.local && sessionId) {
+      data.session_id = sessionId;
+    }
+    if (this.local && url) {
+      data.url = url;
+    }
+    try {
+      return await this.httpClient.post(
+        "/v1/browser/interactions/content",
+        data,
+        this.authHeaders()
+      );
+    } catch (error) {
+      const status = error.statusCode;
+      if (status === 404) {
+        throw new BrowserSessionError("Browser session not found or expired", { cause: error });
+      }
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new BrowserInteractionError(`Failed to extract content: ${msg}`, { cause: error });
+    }
+  }
   /**
    * Download a file from the remote VM
    */
@@ -2113,8 +3413,9 @@ var InstaVM = class {
     if (!targetSessionId) {
       throw new SessionError("Session ID not set. Please create a session first.");
     }
+    const safeSid = encodePathSegment(targetSessionId);
     const response = await this.httpClient.post(
-      `/v1/egress/session/${targetSessionId}`,
+      `/v1/egress/session/${safeSid}`,
       {
         allow_public_repos: options.allowPackageManagers ?? true,
         allow_http: options.allowHttp ?? true,
@@ -2135,8 +3436,9 @@ var InstaVM = class {
     if (!targetSessionId) {
       throw new SessionError("Session ID not set. Please create a session first.");
     }
+    const safeSid = encodePathSegment(targetSessionId);
     const response = await this.httpClient.get(
-      `/v1/egress/session/${targetSessionId}`,
+      `/v1/egress/session/${safeSid}`,
       void 0,
       { "X-API-Key": this.httpClient.apiKey }
     );
@@ -2153,8 +3455,9 @@ var InstaVM = class {
    */
   async setVmEgress(vmId, options = {}) {
     this.ensureNotLocal("Egress policy management");
+    const safeVmId = encodePathSegment(vmId);
     const response = await this.httpClient.post(
-      `/v1/egress/vm/${vmId}`,
+      `/v1/egress/vm/${safeVmId}`,
       {
         allow_public_repos: options.allowPackageManagers ?? true,
         allow_http: options.allowHttp ?? true,
@@ -2171,8 +3474,9 @@ var InstaVM = class {
    */
   async getVmEgress(vmId) {
     this.ensureNotLocal("Egress policy management");
+    const safeVmId = encodePathSegment(vmId);
     const response = await this.httpClient.get(
-      `/v1/egress/vm/${vmId}`,
+      `/v1/egress/vm/${safeVmId}`,
       void 0,
       { "X-API-Key": this.httpClient.apiKey }
     );
@@ -2260,19 +3564,29 @@ export {
   BrowserSessionError,
   BrowserTimeoutError,
   ComputerUseManager,
+  CreditsManager,
   CustomDomainsManager,
   ElementNotFoundError,
   ExecutionError,
+  ForbiddenError,
+  INSTAVM_JS_SDK_VERSION,
   InstaVM,
   InstaVMError,
   NetworkError,
+  PTYManager,
   QuotaExceededError,
   RateLimitError,
+  RecordingsManager,
   SessionError,
   SharesManager,
   SnapshotsManager,
+  TapeContext,
+  TapesManager,
+  ToolCallRecorder,
+  ToolCallSpan,
   UnsupportedOperationError,
   VMsManager,
+  VaultsManager,
   VolumesManager,
   WebhooksManager
 };