@lizard-build/sdk 0.1.49 → 0.1.52

package/dist/index.js

@@ -36,6 +36,7 @@ __export(index_exports, {
   LizardError: () => LizardError,
   MetricsAPI: () => MetricsAPI,
   NotFoundError: () => NotFoundError,
+  PaymentRequiredError: () => PaymentRequiredError,
   PlatformClient: () => PlatformClient,
   ProjectsAPI: () => ProjectsAPI,
   RegionsAPI: () => RegionsAPI,
@@ -111,18 +112,44 @@ var TimeoutError = class extends LizardError {
     this.name = "TimeoutError";
   }
 };
+var PaymentRequiredError = class extends LizardError {
+  constructor(message = "Payment required") {
+    super(message);
+    this.name = "PaymentRequiredError";
+  }
+  /** The one page to open next for this {@link paymentStatus}. */
+  get url() {
+    const s = this.paymentStatus;
+    if (this.invoiceUrl) return this.invoiceUrl;
+    if ((s === "trial_available" || s === "subscription_required") && this.subscribeUrl) return this.subscribeUrl;
+    if (s && PREPAID_STATUSES.has(s) && this.topupUrl) return this.topupUrl;
+    return this.billingUrl ?? this.subscribeUrl ?? this.topupUrl;
+  }
+};
+var PREPAID_STATUSES = /* @__PURE__ */ new Set(["grace", "frozen", "card_required", "credits_required"]);
+var ERROR_CODE = /^[A-Z][A-Z0-9_]*$/;
 async function handleApiError(res) {
-  let message;
-  let code;
+  let body = {};
   try {
-    const body = await res.json();
-    message = body.error ?? res.statusText;
-    if (typeof body.code === "string") code = body.code;
+    const parsed = await res.json();
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) body = parsed;
   } catch {
-    message = res.statusText;
   }
+  const text = (key) => typeof body[key] === "string" && body[key] ? body[key] : void 0;
+  const error = text("error");
+  const errorIsCode = !!error && ERROR_CODE.test(error);
+  const message = (errorIsCode ? text("message") ?? error : error ?? text("message")) ?? res.statusText;
+  const code = text("code") ?? (errorIsCode ? error : void 0);
   let err;
-  if (res.status === 401 || res.status === 403) err = new AuthenticationError(message);
+  if (res.status === 402) {
+    const paid = new PaymentRequiredError(message);
+    paid.paymentStatus = text("status");
+    paid.subscribeUrl = text("subscribeUrl");
+    paid.billingUrl = text("billingUrl");
+    paid.topupUrl = text("topupUrl");
+    paid.invoiceUrl = text("invoiceUrl");
+    err = paid;
+  } else if (res.status === 401 || res.status === 403) err = new AuthenticationError(message);
   else if (res.status === 404) err = new NotFoundError(message);
   else if (res.status === 409) err = new ConflictError(message);
   else if (res.status === 408 || res.status === 504) err = new TimeoutError(message);
@@ -548,7 +575,9 @@ var Process = class {
         envs: opts?.envs,
         user: opts?.user,
         workdir: opts?.workdir,
-        timeoutMs: opts?.timeoutMs
+        timeoutMs: opts?.timeoutMs,
+        // The pid event is opt-in: older CLIs print any unknown data line as output.
+        pidEvent: opts?.onPid ? true : void 0
       }),
       signal: AbortSignal.timeout(opts?.timeoutMs ?? 6e4)
     });
@@ -556,11 +585,6 @@ var Process = class {
     if (!streaming) return res.json();
     return this.consumeStream(res, opts);
   }
-  /**
-   * Read an SSE exec stream, handing each line to the caller as it arrives while
-   * still accumulating the full result. Events are `{stream, line}` for output and
-   * `{exitCode}` at the end.
-   */
   /**
    * List the processes this sandbox is currently running.
    *
@@ -584,8 +608,8 @@ var Process = class {
   /**
    * Signal a running process. Defaults to `SIGTERM`.
    *
-   * The signal goes to the process group, so a shell's children die with it —
-   * killing `sh -c 'sleep 100'` otherwise leaves the sleep running.
+   * The signal goes to the whole process tree, so a shell's children die with
+   * it — killing `sh -c 'sleep 100'` otherwise leaves the sleep running.
    *
    * The pid comes from {@link list}, or from the `pid` event at the start of a
    * streaming `exec`.
@@ -604,6 +628,11 @@ var Process = class {
     });
     if (!res.ok) await handleApiError(res);
   }
+  /**
+   * Read an SSE exec stream, handing each line to the caller as it arrives while
+   * still accumulating the full result. Events are `{pid}` first (when asked for
+   * with `pidEvent`), `{stream, line}` for output and `{exitCode}` at the end.
+   */
   async consumeStream(res, opts) {
     const reader = res.body?.getReader();
     if (!reader) return { stdout: "", stderr: "", exitCode: 0 };
@@ -654,33 +683,37 @@ var Fs = class {
   /**
    * Write a file into the sandbox filesystem.
    *
-   * Creates parent directories automatically if they don't exist.
-   * Byte input must contain valid UTF-8; arbitrary binary uploads are unsupported.
+   * Creates parent directories automatically if they don't exist. A string is
+   * written as UTF-8; bytes (`Uint8Array`, `Buffer` or `ArrayBuffer`) are written
+   * exactly as given, so binary files round-trip with {@link readBytes}.
+   *
+   * With `opts.user` the file is written as (and owned by) that user.
    *
    * @example
    * ```ts
    * await sandbox.fs.write('/app/index.js', 'console.log("hello")')
    * ```
    *
-   * @example Write UTF-8 bytes:
+   * @example Write binary data:
    * ```ts
-   * await sandbox.fs.write('/app/notes.txt', new TextEncoder().encode('hello'))
+   * await sandbox.fs.write('/app/logo.png', await readFile('logo.png'))
    * ```
    */
   async write(path, data, opts) {
-    const content = typeof data === "string" ? data : new TextDecoder("utf-8", { fatal: true }).decode(data);
+    const body = typeof data === "string" ? { path, content: data, user: opts?.user } : { path, content: bytesToBase64(data instanceof ArrayBuffer ? new Uint8Array(data) : data), encoding: "base64", user: opts?.user };
     const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/files`, {
       method: "POST",
       headers: this.config.headers,
-      body: JSON.stringify({ path, content, user: opts?.user })
+      body: JSON.stringify(body)
     });
     if (!res.ok) await handleApiError(res);
   }
   /**
    * Read a file from the sandbox filesystem.
    *
-   * @returns The file contents as a UTF-8 string.
+   * @returns The file contents as a UTF-8 string. Use {@link readBytes} for binary files.
    *
+   * Throws `NotFoundError` if the path does not exist.
    * @example
    * ```ts
    * const content = await sandbox.fs.read('/app/index.js')
@@ -748,9 +781,7 @@ var Fs = class {
    * console.log(info.size, info.type)
    * ```
    *
-   * Throws `NotFoundError` if the path does not exist. Sandboxes created before
-   * this shipped run a guest agent without it and throw `LizardError` (501) —
-   * recreate the sandbox to use it.
+   * Throws `NotFoundError` if the path does not exist.
    */
   async stat(path, opts) {
     const url = new URL(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/files/stat`);
@@ -767,9 +798,6 @@ var Fs = class {
    * ```ts
    * await sandbox.fs.move('/tmp/build.log', '/app/logs/build.log')
    * ```
-   *
-   * Sandboxes created before this shipped run a guest agent without it and throw
-   * `LizardError` (501) — recreate the sandbox to use it.
    */
   async move(from, to) {
     const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/files/move`, {
@@ -798,8 +826,7 @@ var Fs = class {
    * }, 1000)
    * ```
    *
-   * Sandboxes created before this shipped run a guest agent without it and throw
-   * `LizardError` (501) — recreate the sandbox to use it.
+   * Not available on Firecracker sandboxes yet: the call throws `LizardError` (501).
    */
   async watch(path, opts) {
     const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/files/watch`, {
@@ -845,6 +872,12 @@ var Watcher = class {
     if (!res.ok) await handleApiError(res);
   }
 };
+function bytesToBase64(bytes) {
+  if (typeof Buffer !== "undefined") return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("base64");
+  let s = "";
+  for (let i = 0; i < bytes.length; i += 32768) s += String.fromCharCode(...bytes.subarray(i, i + 32768));
+  return btoa(s);
+}
 
 // src/sandbox/desktop.ts
 var BUTTONS = { left: "1", middle: "2", right: "3" };
@@ -1145,11 +1178,17 @@ var Sandbox = class extends SandboxClient {
   async kill(opts) {
     return SandboxClient.killSandbox(this.sandboxId, this.resolveOpts(opts));
   }
-  /** Queue a CRIU checkpoint and stop compute. Use waitForStatus('paused') before resuming. */
+  /**
+   * Pause the sandbox: its memory, running processes and files are kept and
+   * compute stops. Wait with `waitForStatus('paused')` before resuming.
+   */
   async pause(opts) {
     return SandboxClient.pauseSandbox(this.sandboxId, this.resolveOpts(opts));
   }
-  /** Queue restoration of saved memory and files. Use waitForStatus('running') before executing. */
+  /**
+   * Resume a paused sandbox exactly where it stopped, processes included. Wait
+   * with `waitForStatus('running')` before running commands.
+   */
   async resume(opts) {
     return SandboxClient.resumeSandbox(this.sandboxId, this.resolveOpts(opts));
   }
@@ -1182,33 +1221,82 @@ var Sandbox = class extends SandboxClient {
     return SandboxClient.setTimeoutSandbox(this.sandboxId, timeoutMs, this.resolveOpts(opts));
   }
   /**
-   * Register a public HTTPS route and return its hostname without a scheme.
+   * Publish a port on a public HTTPS hostname and return the hostname without a scheme.
    *
-   * Useful for accessing HTTP servers started inside the sandbox from your
-   * agent or tests without additional tunneling.
+   * The port is private: requests need {@link accessToken} (set by this call) as
+   * the `X-Lizard-Access-Token` header, or `?lizard_token=<token>` in a browser.
+   * {@link exposePort} returns the token and a ready-made browser URL together.
    *
    * @example
    * ```ts
    * // Start an HTTP server on port 3000 before exposing it.
    * const hostname = await sandbox.getHost(3000)
-   * console.log(`https://${hostname}`)
+   * const res = await fetch(`https://${hostname}/`, {
+   *   headers: { 'X-Lizard-Access-Token': sandbox.accessToken! },
+   * })
    * ```
    */
   async getHost(port, opts) {
-    const { hostname } = await SandboxClient.exposeSandboxPort(this.sandboxId, port, this.resolveOpts(opts));
-    return hostname;
+    return (await this.exposePort(port, opts)).hostname;
   }
-  /** Fork is unsupported on Kubernetes; the backend returns HTTP 501. */
-  fork(opts = {}) {
-    return new PlatformClient(this.resolveOpts()).post(`/api/sandboxes/${this.sandboxId}/fork`, { count: opts.count ?? 1, timeoutMs: opts.timeoutMs ?? 0 });
+  /**
+   * Publish a port and return everything needed to reach it: the hostname, a
+   * browser `url` that carries the token, and the `accessToken` for API clients.
+   *
+   * @example
+   * ```ts
+   * const { url, hostname, accessToken } = await sandbox.exposePort(3000)
+   * console.log(url) // open in a browser
+   * await fetch(`https://${hostname}/api`, { headers: { 'X-Lizard-Access-Token': accessToken } })
+   * ```
+   */
+  async exposePort(port, opts) {
+    const exposed = await SandboxClient.exposeSandboxPort(this.sandboxId, port, this.resolveOpts(opts));
+    if (exposed.accessToken) this.accessToken = exposed.accessToken;
+    return exposed;
+  }
+  /**
+   * Clone this running sandbox `count` times (1-10). Each fork is a copy of the
+   * microVM at this instant -- memory, running processes and files -- and is
+   * billed like its source. The source keeps running.
+   *
+   * Returns one entry per requested fork, in order: `{ sandbox, info }`, or
+   * `{ error }` for a copy that could not be made (e.g. the account's sandbox
+   * limit). A sandbox with a volume attached cannot be forked (`ConflictError`, 409).
+   *
+   * @param opts.timeoutMs Lifetime of each fork; defaults to the source's timeout.
+   *
+   * @example
+   * ```ts
+   * const forks = await sandbox.fork({ count: 2 })
+   * for (const f of forks) if (f.sandbox) await f.sandbox.process.exec('echo hi')
+   * ```
+   */
+  async fork(opts = {}) {
+    const result = await new PlatformClient(this.resolveOpts()).post(
+      `/api/sandboxes/${this.sandboxId}/fork`,
+      { count: opts.count ?? 1, timeoutMs: opts.timeoutMs ?? 0 }
+    );
+    const Ctor = this.constructor;
+    return (Array.isArray(result) ? result : []).map((entry) => {
+      const id = entry.sandbox?.sandboxId ?? entry.sandbox?.id;
+      if (!entry.sandbox || !id) return { error: entry.error ?? "fork failed" };
+      return { sandbox: new Ctor({ ...this.resolveOpts(), sandboxId: id }), info: { ...entry.sandbox, sandboxId: id } };
+    });
   }
-  /** Capture memory and workspace files. Disconnect active clients before capturing. */
+  /**
+   * Save this sandbox -- memory, running processes and files -- as a private
+   * snapshot. A Firecracker snapshot is `ready` as soon as this returns (about 2 s);
+   * start copies of it with {@link Sandbox.restore} (about 0.4 s each). The source
+   * keeps running. `poolSize` applies to container sandboxes only.
+   */
   snapshot(name = `Snapshot ${this.sandboxId}`, opts = {}) {
     return new PlatformClient(this.resolveOpts()).post(`/api/sandboxes/${this.sandboxId}/snapshot`, { name, poolSize: opts.poolSize ?? 5 });
   }
   unexpose(port) {
     return new PlatformClient(this.resolveOpts()).delete(`/api/sandboxes/${this.sandboxId}/expose/${port}`);
   }
+  /** Stream the sandbox's logs. Not available on Firecracker sandboxes yet (`LizardError`, 501). */
   logs(opts = {}) {
     return new PlatformClient(this.resolveOpts()).events(query(`/api/sandboxes/${this.sandboxId}/logs`, { tail: opts.tail }), { signal: opts.signal });
   }
@@ -1218,7 +1306,7 @@ var Sandbox = class extends SandboxClient {
   static getSnapshot(snapshotId, opts) {
     return new PlatformClient(opts ?? {}).get(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}`);
   }
-  /** Start a sandbox from an available warm copy in the snapshot's project and region. */
+  /** Start a new sandbox from a snapshot, in the snapshot's project and region. */
   static async restore(snapshotId, opts) {
     const client = new PlatformClient(opts ?? {});
     const snapshot = await this.getSnapshot(snapshotId, opts);
@@ -1233,7 +1321,7 @@ var Sandbox = class extends SandboxClient {
   static setSnapshotWarmPool(snapshotId, poolSize, opts) {
     return new PlatformClient(opts ?? {}).patch(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}`, { poolSize });
   }
-  /** Release idle warm copies; retain saved state and existing claimed sandboxes. */
+  /** Release idle warm copies (container snapshots); retain saved state and existing claimed sandboxes. */
   static pauseSnapshot(snapshotId, opts) {
     return new PlatformClient(opts ?? {}).post(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}/pause`, {});
   }
@@ -1611,88 +1699,54 @@ var RegionsAPI = class {
   }
 };
 
-// src/cli.ts
-var import_node_child_process = require("child_process");
-var LizardCLI = class {
-  constructor(opts = {}) {
-    this.opts = opts;
-  }
-  run(args, opts = {}) {
-    return new Promise((resolve, reject) => {
-      const env = { ...process.env };
-      if (this.opts.apiKey) {
-        env.LIZARD_API_KEY = this.opts.apiKey;
-        env.LIZARD_TOKEN = this.opts.apiKey;
-      }
-      if (this.opts.apiUrl) env.LIZARD_API_URL = this.opts.apiUrl;
-      const child = (0, import_node_child_process.spawn)(this.opts.executable ?? "lizard", ["--json", ...args], {
-        cwd: this.opts.cwd,
-        env,
-        shell: false,
-        stdio: "pipe",
-        signal: opts.signal,
-        timeout: this.opts.timeoutMs ?? 6e5
-      });
-      child.stdout.setEncoding("utf8");
-      child.stderr.setEncoding("utf8");
-      let stdout = "", stderr = "", bytes = 0;
-      const collect = (stream, data) => {
-        bytes += Buffer.byteLength(data);
-        if (bytes > 16 * 1024 * 1024) {
-          child.kill();
-          reject(new Error("CLI output exceeds 16 MiB"));
-          return;
-        }
-        if (stream === "stdout") stdout += data;
-        else stderr += data;
-      };
-      child.stdout.on("data", (data) => collect("stdout", data));
-      child.stderr.on("data", (data) => collect("stderr", data));
-      child.on("error", reject);
-      child.on("close", (code, signal) => {
-        if (signal) {
-          reject(new Error(`CLI ended with signal ${signal}`));
-          return;
-        }
-        let events = [];
-        try {
-          events = [JSON.parse(stdout)];
-        } catch {
-          events = stdout.split("\n").filter(Boolean).flatMap((line) => {
-            try {
-              return [JSON.parse(line)];
-            } catch {
-              return [];
-            }
-          });
-        }
-        resolve({ code: code ?? 1, stdout, stderr, events });
-      });
-      child.stdin.on("error", (error) => {
-        if (error.code !== "EPIPE") reject(error);
-      });
-      child.stdin.end(opts.stdin);
-    });
-  }
-};
-
 // src/platform/billing.ts
 var BillingAPI = class {
   constructor(client) {
     this.client = client;
   }
-  /** Current balance, status, burn rate, and runway. */
+  /**
+   * The plan: trial, this month's credits, overage, next charge, cancel date. With
+   * `workspaceId`, the plan of that workspace's owner (`isOwner: false`, no card or
+   * invoice fields).
+   */
+  subscription(opts) {
+    return this.client.get(query("/api/billing/subscription", { workspaceId: opts?.workspaceId }));
+  }
+  /**
+   * Opens Stripe Checkout for Pro: the trial when the account can have one, otherwise
+   * Pro at once ($19 today). Returns the page for the user to finish; a second call
+   * while it is open returns the same session.
+   */
+  startCheckout(opts = {}) {
+    return this.client.post("/api/billing/subscription/checkout", { returnUrl: opts.returnUrl });
+  }
+  /** Ends the trial now: charges $19 and starts the first paid month with $19 of credits. */
+  startProNow() {
+    return this.client.post("/api/billing/subscription/start-now", {});
+  }
+  /** Cancels Pro at the end of the current month or trial. Cancelling in the trial costs nothing. */
+  cancel() {
+    return this.client.post("/api/billing/subscription/cancel", {});
+  }
+  /** Undoes {@link cancel}: Pro renews as usual. */
+  resume() {
+    return this.client.post("/api/billing/subscription/resume", {});
+  }
+  /** Redeems a promo code: a longer trial with more trial credits. Works only before the first payment. */
+  redeemPromo(code) {
+    return this.client.post("/api/billing/promo/redeem", { code });
+  }
+  /** Prepaid credits balance, status, burn rate and runway (old `payg` accounts and enterprise). */
   balance() {
     return this.client.get("/api/billing/balance");
   }
-  /** A page of balance transactions, newest first. */
+  /** A page of balance transactions, newest first (old `payg` accounts and enterprise). */
   transactions(opts) {
-    const qs = new URLSearchParams();
-    if (opts?.limit !== void 0) qs.set("limit", String(opts.limit));
-    if (opts?.cursor) qs.set("cursor", opts.cursor);
-    if (opts?.includeUsage) qs.set("includeUsage", "1");
-    const q = qs.toString();
-    return this.client.get(`/api/billing/transactions${q ? `?${q}` : ""}`);
+    return this.client.get(query("/api/billing/transactions", {
+      limit: opts?.limit,
+      cursor: opts?.cursor || void 0,
+      includeUsage: opts?.includeUsage ? "1" : void 0
+    }));
   }
   /** Cost summary for the current billing period, broken down by resource. */
   summary() {
@@ -1702,46 +1756,13 @@ var BillingAPI = class {
   live() {
     return this.client.get("/api/billing/live");
   }
+  /** Saved cards. Cards are added in Checkout or on the Billing page. */
   paymentMethods() {
     return this.client.get("/api/billing/payment-methods");
   }
-  setupPaymentMethod(returnUrl) {
-    return this.client.post("/api/billing/payment-methods/setup", { returnUrl });
-  }
   removePaymentMethod(id) {
     return this.client.delete(`/api/billing/payment-methods/${encodeURIComponent(id)}`);
   }
-  purchase(creditCents, opts = {}) {
-    if (!Number.isSafeInteger(creditCents) || creditCents <= 0) throw new Error("creditCents must be a positive integer");
-    return this.client.post("/api/billing/purchase", { creditCents, paymentMethod: opts.paymentMethod ?? "card", returnUrl: opts.returnUrl });
-  }
-  autoTopup() {
-    return this.client.get("/api/billing/auto-topup");
-  }
-  setAutoTopup(opts) {
-    return this.client.put("/api/billing/auto-topup", opts);
-  }
-  runAutoTopup() {
-    return this.client.post("/api/billing/auto-topup/run", {});
-  }
-  redeemPromo(code) {
-    return this.client.post("/api/billing/promo/redeem", { code });
-  }
-  x402Quote(creditCents) {
-    return this.client.post("/api/billing/purchase/x402/quote", { creditCents });
-  }
-  paymentStatus(attemptId) {
-    return this.client.get(`/api/billing/purchase/x402/${encodeURIComponent(attemptId)}`);
-  }
-  /** Pay with the CLI's durable x402 journal. Requires CLI >= 4.0.8. Amounts are cents. */
-  async payX402(creditCents, opts) {
-    if (![creditCents, opts.maxTotalCents].every((n) => Number.isSafeInteger(n) && n > 0)) throw new Error("Payment amounts must be positive integer cents");
-    const args = ["credits", "topup", (creditCents / 100).toFixed(2), "--method", "x402", "--max-total", (opts.maxTotalCents / 100).toFixed(2), "--yes"];
-    if (opts.requestId) args.push("--request-id", opts.requestId);
-    const result = await new LizardCLI({ apiKey: this.client.config.apiKey, apiUrl: this.client.config.apiUrl, executable: opts.executable }).run(args);
-    if (result.code !== 0) throw new Error(`x402 CLI exited with code ${result.code}; inspect the payment journal or query paymentStatus before retrying`);
-    return result.events[0];
-  }
 };
 
 // src/volume/index.ts
@@ -1772,7 +1793,7 @@ var Volume = class _Volume {
    * "the scratch disk for this task" no longer has to store an id between runs.
    *
    * An existing volume is returned as-is — `sizeGb` applies only to a fresh create,
-   * so an existing volume keeps its size. Call {@link Volume.resize} to change it.
+   * so an existing volume keeps its size.
    */
   static async getOrCreate(projectId, name, opts) {
     const config = new ConnectionConfig(opts);
@@ -1815,11 +1836,15 @@ var Volume = class _Volume {
   /**
    * Resize a volume, by name or by id, to `sizeGb`.
    *
-   * The change is in place and online: the size is a quota, so no data is copied,
-   * it completes in well under a second, and a sandbox that has the volume mounted
-   * keeps running and sees the new size immediately. Both growing and shrinking are
-   * allowed, but a shrink must leave at least 10% of the new size free — otherwise
-   * it throws `ConflictError` with `code: 'volume_too_full_to_shrink'`.
+   * **Firecracker volumes cannot be resized yet**: volumes created for the default
+   * Firecracker sandboxes throw `LizardError` (400) with `code: 'volume_not_resizable'`.
+   * Create the volume at the size you need, or copy the data to a new, larger one.
+   *
+   * On a container volume the change is in place and online: the size is a quota,
+   * so no data is copied and a mounted sandbox sees the new size immediately. Both
+   * growing and shrinking are allowed, but a shrink must leave at least 10% of the
+   * new size free — otherwise it throws `ConflictError` with
+   * `code: 'volume_too_full_to_shrink'`.
    *
    * Other failures carry a `code` too: `invalid_volume_size`, `volume_not_resizable`,
    * `volume_resize_in_progress`, `volume_not_provisioned`,
@@ -1845,7 +1870,7 @@ var Volume = class _Volume {
     if (!res.ok) await handleApiError(res);
     return res.json();
   }
-  /** Resize this volume in place — see the static {@link Volume.resize}. */
+  /** Resize this volume — see the static {@link Volume.resize} (not supported for Firecracker volumes yet). */
   async resize(projectId, sizeGb) {
     return _Volume.resize(projectId, this.volumeId, sizeGb, {
       apiKey: this.config.apiKey,
@@ -1968,7 +1993,7 @@ var Execution = class {
     this.stderr = "";
     /** Rich output items (images, JSON, HTML, plain values). */
     this.results = [];
-    /** Monotonically increasing counter for this context. */
+    /** Monotonically increasing counter for this context (the Python kernel's `In[n]`). */
     this.executionCount = 0;
   }
   get success() {
@@ -1979,25 +2004,317 @@ var Execution = class {
   }
 };
 
+// src/code-interpreter/runner.ts
+var RUNNER_SOURCE = String.raw`# Lizard code runner: executes code for CodeSandbox.run_code / runCode inside the sandbox.
+# Python runs in a persistent Jupyter kernel per context when the template has one
+# (the interpreter template does); everything else runs as a fresh process.
+# Events are JSON lines on stdout; an event over 24000 chars is sent as "part" lines.
+import base64, json, os, re, shutil, signal, subprocess, sys, threading, time
+ROOT = "/tmp/.lizard-code"
+LANGS = {"python": "python3", "javascript": "node", "bash": "bash"}
+ALIASES = {"py": "python", "python3": "python", "js": "javascript", "node": "javascript", "sh": "bash"}
+ANSI = re.compile(r"\x1b\[[0-9;]*[A-Za-z]")
+LOCK = threading.Lock()
+
+
+def emit(ev):
+    s = json.dumps(ev)
+    with LOCK:
+        if len(s) <= 24000:
+            print(s, flush=True)
+            return
+        n = (len(s) + 23999) // 24000
+        for i in range(n):
+            print(json.dumps({"type": "part", "data": s[i * 24000:(i + 1) * 24000], "end": i == n - 1}), flush=True)
+
+
+def fail(msg):
+    emit({"type": "fatal", "message": msg})
+    sys.exit(3)
+
+
+def meta_path(ctx):
+    return os.path.join(ROOT, ctx, "meta.json")
+
+
+def load(ctx):
+    try:
+        with open(meta_path(ctx)) as f:
+            return json.load(f)
+    except OSError:
+        return None
+
+
+def save(m):
+    os.makedirs(os.path.join(ROOT, m["id"]), exist_ok=True)
+    with open(meta_path(m["id"]), "w") as f:
+        json.dump(m, f)
+
+
+def alive(pid):
+    try:
+        os.kill(pid, 0)
+    except OSError:
+        return False
+    try:
+        with open("/proc/%d/stat" % pid) as f:
+            return f.read().split(") ")[-1][:1] != "Z"
+    except OSError:
+        return False
+
+
+def kernel_pid(m):
+    try:
+        with open(os.path.join(ROOT, m["id"], "kernel.pid")) as f:
+            return int(f.read().strip())
+    except (OSError, ValueError):
+        return 0
+
+
+def stop_kernel(m):
+    pid = kernel_pid(m)
+    if pid and alive(pid):
+        try:
+            os.killpg(pid, signal.SIGKILL)
+        except OSError:
+            pass
+    for name in ("kernel.pid", "kernel.json"):
+        try:
+            os.remove(os.path.join(ROOT, m["id"], name))
+        except OSError:
+            pass
+
+
+def start_kernel(m):
+    d = os.path.join(ROOT, m["id"])
+    conn = os.path.join(d, "kernel.json")
+    stop_kernel(m)
+    os.makedirs(m["cwd"], exist_ok=True)
+    log = open(os.path.join(d, "kernel.log"), "ab")
+    p = subprocess.Popen([sys.executable, "-m", "ipykernel_launcher", "-f", conn], cwd=m["cwd"],
+                         stdin=subprocess.DEVNULL, stdout=log, stderr=log, start_new_session=True,
+                         env=dict(os.environ, PYTHONUNBUFFERED="1"))
+    with open(os.path.join(d, "kernel.pid"), "w") as f:
+        f.write(str(p.pid))
+    end = time.time() + 30
+    while time.time() < end:
+        if os.path.exists(conn) and os.path.getsize(conn) > 0:
+            return
+        if p.poll() is not None:
+            break
+        time.sleep(0.05)
+    with open(os.path.join(d, "kernel.log"), "rb") as f:
+        tail = f.read()[-2000:].decode("utf-8", "replace")
+    fail("python kernel failed to start: " + (tail or "no output"))
+
+
+def has_kernel():
+    try:
+        import jupyter_client, ipykernel  # noqa: F401
+        return True
+    except ImportError:
+        return False
+
+
+def client(m):
+    from jupyter_client import BlockingKernelClient
+    if not (kernel_pid(m) and alive(kernel_pid(m))):
+        start_kernel(m)
+    kc = BlockingKernelClient()
+    kc.load_connection_file(os.path.join(ROOT, m["id"], "kernel.json"))
+    kc.start_channels()
+    kc.wait_for_ready(timeout=30)
+    return kc
+
+
+def shell_reply(kc, msg_id, timeout):
+    end = time.time() + timeout
+    while time.time() < end:
+        try:
+            r = kc.get_shell_msg(timeout=max(0.01, end - time.time()))
+        except Exception:
+            return None
+        if r["parent_header"].get("msg_id") == msg_id:
+            return r
+    return None
+
+
+def silent(kc, code):
+    shell_reply(kc, kc.execute(code, silent=True, store_history=False), 10)
+
+
+BEST = ("image/png", "image/jpeg", "image/svg+xml", "text/html", "text/markdown", "application/json", "text/latex", "text/plain")
+
+
+def run_python(m, code, envs, timeout):
+    kc = client(m)
+    if envs:
+        silent(kc, "import os as _lz_os\n_lz_saved = {k: _lz_os.environ.get(k) for k in %r}\n_lz_os.environ.update(%r)" % (list(envs), envs))
+    msg_id = kc.execute(code, store_history=True, allow_stdin=False)
+    end = time.time() + timeout
+    timed_out = False
+    while True:
+        left = end - time.time()
+        if left <= 0:
+            timed_out = True
+            break
+        try:
+            msg = kc.get_iopub_msg(timeout=left)
+        except Exception:
+            continue
+        if msg["parent_header"].get("msg_id") != msg_id:
+            continue
+        t, c = msg["msg_type"], msg["content"]
+        if t == "stream":
+            emit({"type": "stderr" if c.get("name") == "stderr" else "stdout", "data": c.get("text", "")})
+        elif t in ("execute_result", "display_data"):
+            data = c.get("data", {})
+            mime = next((k for k in BEST if k in data), next(iter(data), None))
+            if mime:
+                v = data[mime]
+                emit({"type": "result", "mime": mime, "data": v if isinstance(v, str) else json.dumps(v)})
+        elif t == "error":
+            emit({"type": "error", "name": c.get("ename", "Error"), "message": c.get("evalue", ""),
+                  "traceback": ANSI.sub("", "\n".join(c.get("traceback", [])))})
+        elif t == "status" and c.get("execution_state") == "idle":
+            break
+    count = 0
+    if timed_out:
+        pid = kernel_pid(m)
+        if pid:
+            try:
+                os.kill(pid, signal.SIGINT)
+            except OSError:
+                pass
+        emit({"type": "error", "name": "TimeoutError", "message": "execution timed out after %gs; the kernel was interrupted" % timeout, "traceback": ""})
+    else:
+        r = shell_reply(kc, msg_id, 10)
+        count = (r or {}).get("content", {}).get("execution_count") or 0
+    if envs and not timed_out:
+        silent(kc, "for _lz_k, _lz_v in _lz_saved.items():\n    _lz_os.environ.pop(_lz_k, None) if _lz_v is None else _lz_os.environ.__setitem__(_lz_k, _lz_v)")
+    kc.stop_channels()
+    emit({"type": "done", "execution_count": count})
+
+
+def run_process(m, code, envs, timeout):
+    interp = LANGS[m["language"]]
+    if shutil.which(interp) is None:
+        emit({"type": "error", "name": "LanguageUnavailable", "message": "%s is not installed in this sandbox" % interp, "traceback": ""})
+        emit({"type": "done", "execution_count": 0})
+        return
+    d = os.path.join(ROOT, m["id"])
+    src = os.path.join(d, "cell" + {"node": ".js", "bash": ".sh"}.get(interp, ".py"))
+    with open(src, "w") as f:
+        f.write(code)
+    os.makedirs(m["cwd"], exist_ok=True)
+    p = subprocess.Popen([interp, src], cwd=m["cwd"], stdin=subprocess.DEVNULL, stdout=subprocess.PIPE,
+                         stderr=subprocess.PIPE, env=dict(os.environ, **(envs or {})), start_new_session=True)
+    err_tail = []
+
+    def pump(stream, kind):
+        for line in iter(stream.readline, b""):
+            text = line.decode("utf-8", "replace")
+            if kind == "stderr":
+                err_tail.append(text)
+                del err_tail[:-50]
+            emit({"type": kind, "data": text})
+
+    ts = [threading.Thread(target=pump, args=(p.stdout, "stdout")), threading.Thread(target=pump, args=(p.stderr, "stderr"))]
+    for t in ts:
+        t.start()
+    try:
+        rc = p.wait(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        os.killpg(p.pid, signal.SIGKILL)
+        rc = None
+    for t in ts:
+        t.join(5)
+    m["count"] = m.get("count", 0) + 1
+    save(m)
+    if rc is None:
+        emit({"type": "error", "name": "TimeoutError", "message": "execution timed out after %gs" % timeout, "traceback": ""})
+    elif rc != 0:
+        emit({"type": "error", "name": "ExitError", "message": "exited with code %d" % rc, "traceback": "".join(err_tail)})
+    emit({"type": "done", "execution_count": m["count"]})
+
+
+def ctx_for(a):
+    lang = (a.get("language") or "python").lower()
+    lang = ALIASES.get(lang, lang)
+    if lang not in LANGS:
+        fail("unsupported language %r; use python, javascript or bash" % lang)
+    return lang
+
+
+def main():
+    a = json.loads(base64.b64decode(sys.argv[1]))
+    act = a["action"]
+    os.makedirs(ROOT, exist_ok=True)
+    if act == "create" or (act == "run" and not a.get("context")):
+        lang = ctx_for(a)
+        cid = a.get("context") or ("default-" + lang)
+        m = load(cid) if act == "run" else None
+        if m is None:
+            m = {"id": cid if act == "run" else a["id"], "language": lang, "cwd": a.get("cwd") or "/home/user"}
+            save(m)
+            if lang == "python" and act == "create" and has_kernel():
+                client(m).stop_channels()
+        if act == "create":
+            emit({"type": "context", "id": m["id"], "language": m["language"], "cwd": m["cwd"]})
+            return
+    elif act == "list":
+        out = []
+        for name in sorted(os.listdir(ROOT)):
+            m = load(name)
+            if m and not name.startswith("default-"):
+                out.append({"id": m["id"], "language": m["language"], "cwd": m["cwd"]})
+        emit({"type": "contexts", "data": out})
+        return
+    else:
+        m = load(a["context"])
+        if m is None:
+            fail("context %r not found" % a["context"])
+        if act == "delete":
+            stop_kernel(m)
+            shutil.rmtree(os.path.join(ROOT, m["id"]), ignore_errors=True)
+            emit({"type": "ok"})
+            return
+        if act == "restart":
+            if m["language"] == "python" and has_kernel():
+                start_kernel(m)
+            m["count"] = 0
+            save(m)
+            emit({"type": "ok"})
+            return
+    code = a.get("code")
+    if code is None:
+        with open(a["codeFile"]) as f:
+            code = f.read()
+        os.remove(a["codeFile"])
+    if m["language"] == "python" and has_kernel():
+        run_python(m, code, a.get("envs") or {}, a.get("timeout") or 60)
+    else:
+        run_process(m, code, a.get("envs") or {}, a.get("timeout") or 60)
+
+
+main()
+`;
+
 // src/code-interpreter/index.ts
-var CODE_INTERPRETER_PORT = 8080;
+var DEFAULT_RUN_TIMEOUT_MS = 6e4;
+var RUNNER_OVERHEAD_MS = 45e3;
+var MAX_INLINE_ARGS = 1e5;
 var CodeSandbox = class extends Sandbox {
-  get serverUrl() {
-    return this.getHost(CODE_INTERPRETER_PORT).then((h) => `https://${h}`);
-  }
   /**
-   * Execute code in a persistent kernel.
+   * Execute code and wait for it to finish.
    *
-   * Variables, imports, and function definitions from previous calls are
-   * available in subsequent calls within the same context.
+   * Python keeps its state per context (the default context, per language,
+   * when none is given). Code errors appear in `execution.error`; request
+   * failures throw.
    *
    * @param code  Source code to run.
    * @param opts  Language, context, env vars, timeout, and streaming callbacks.
    *
-   * @returns Execution result with stdout, stderr, results, and any error.
-   *
-   * Code errors appear in `execution.error`; request failures throw.
-   *
    * @example
    * ```ts
    * const result = await sandbox.runCode(`
@@ -2011,63 +2328,42 @@ var CodeSandbox = class extends Sandbox {
     if (opts?.context && opts?.language) {
       throw new Error("Provide context or language, not both");
     }
-    const body = { code, env_vars: opts?.envs ?? {} };
-    if (opts?.context) body.context_id = opts.context.id;
-    else if (opts?.language) body.language = opts.language;
-    const controller = new AbortController();
-    const timer = opts?.timeoutMs ? setTimeout(() => controller.abort(), opts.timeoutMs) : void 0;
-    try {
-      const res = await fetch(`${await this.serverUrl}/execute`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify(body),
-        signal: controller.signal
-      });
-      if (!res.ok) {
-        throw new Error(`Code interpreter returned ${res.status}: ${await res.text()}`);
-      }
-      if (!res.body) throw new Error("Empty response body");
-      const execution = new Execution();
-      for await (const line of readLines(res.body)) {
-        let item;
-        try {
-          item = JSON.parse(line);
-        } catch {
-          continue;
-        }
-        if (item.type === "stdout") {
-          execution.stdout += item.data;
-          opts?.onStdout?.(item.data);
-        } else if (item.type === "stderr") {
-          execution.stderr += item.data;
-          opts?.onStderr?.(item.data);
-        } else if (item.type === "result") {
-          const out = item;
-          execution.results.push(out);
-          opts?.onResult?.(out);
-        } else if (item.type === "error") {
-          const err = new ExecutionError(
-            item.name,
-            item.message,
-            item.traceback
-          );
-          execution.error = err;
-          opts?.onError?.(err);
-        } else if (item.type === "done") {
-          execution.executionCount = item.execution_count ?? 0;
-          break;
-        }
+    const timeoutMs = opts?.timeoutMs ?? DEFAULT_RUN_TIMEOUT_MS;
+    const args = {
+      action: "run",
+      code,
+      envs: opts?.envs ?? {},
+      timeout: timeoutMs / 1e3
+    };
+    if (opts?.context) args.context = opts.context.id;
+    else args.language = opts?.language ?? "python";
+    const execution = new Execution();
+    await this.runner(args, timeoutMs, (item) => {
+      if (item.type === "stdout") {
+        execution.stdout += item.data;
+        opts?.onStdout?.(item.data);
+      } else if (item.type === "stderr") {
+        execution.stderr += item.data;
+        opts?.onStderr?.(item.data);
+      } else if (item.type === "result") {
+        const out = { type: "result", mime: item.mime, data: item.data };
+        execution.results.push(out);
+        opts?.onResult?.(out);
+      } else if (item.type === "error") {
+        const err = new ExecutionError(item.name, item.message, item.traceback);
+        execution.error = err;
+        opts?.onError?.(err);
+      } else if (item.type === "done") {
+        execution.executionCount = item.execution_count ?? 0;
       }
-      return execution;
-    } finally {
-      clearTimeout(timer);
-    }
+    });
+    return execution;
   }
   /**
    * Create a new isolated execution context.
    *
-   * Each context maintains its own variable namespace and process state.
-   * Useful for running multiple independent sessions in the same sandbox.
+   * A Python context is its own kernel: its own variables, and `cwd` as its
+   * working directory. Other languages get the working directory only.
    *
    * @example
    * ```ts
@@ -2077,40 +2373,80 @@ var CodeSandbox = class extends Sandbox {
    * ```
    */
   async createContext(opts) {
-    const res = await fetch(`${await this.serverUrl}/contexts`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        language: opts?.language ?? "python",
-        cwd: opts?.cwd ?? "/home/user"
-      })
-    });
-    if (!res.ok) throw new Error(`Failed to create context: ${await res.text()}`);
-    return res.json();
+    const id = `ctx-${randomId()}`;
+    let ctx;
+    await this.runner(
+      { action: "create", id, language: opts?.language ?? "python", cwd: opts?.cwd ?? "/home/user" },
+      DEFAULT_RUN_TIMEOUT_MS,
+      (ev) => {
+        if (ev.type === "context") ctx = { id: ev.id, language: ev.language, cwd: ev.cwd };
+      }
+    );
+    if (!ctx) throw new LizardError("Failed to create context");
+    return ctx;
   }
-  /**
-   * List all active execution contexts in this sandbox.
-   */
+  /** List the contexts created with {@link createContext} in this sandbox. */
   async listContexts() {
-    const res = await fetch(`${await this.serverUrl}/contexts`);
-    if (!res.ok) throw new Error(`Failed to list contexts: ${await res.text()}`);
-    return res.json();
+    let out = [];
+    await this.runner({ action: "list" }, DEFAULT_RUN_TIMEOUT_MS, (ev) => {
+      if (ev.type === "contexts") out = ev.data;
+    });
+    return out;
   }
-  /**
-   * Delete an execution context and free its resources.
-   */
+  /** Delete an execution context, stopping its kernel. */
   async deleteContext(context) {
     const id = typeof context === "string" ? context : context.id;
-    const res = await fetch(`${await this.serverUrl}/contexts/${id}`, { method: "DELETE" });
-    if (!res.ok) throw new Error(`Failed to delete context: ${await res.text()}`);
+    await this.runner({ action: "delete", context: id }, DEFAULT_RUN_TIMEOUT_MS, () => {
+    });
   }
-  /**
-   * Restart a context, clearing all variables and state.
-   */
+  /** Restart a context, clearing all variables and state. */
   async restartContext(context) {
     const id = typeof context === "string" ? context : context.id;
-    const res = await fetch(`${await this.serverUrl}/contexts/${id}/restart`, { method: "POST" });
-    if (!res.ok) throw new Error(`Failed to restart context: ${await res.text()}`);
+    await this.runner({ action: "restart", context: id }, DEFAULT_RUN_TIMEOUT_MS, () => {
+    });
+  }
+  /** Run the in-sandbox runner with `args` and hand each of its events to `onEvent`. */
+  async runner(args, timeoutMs, onEvent) {
+    let encoded = toBase64(JSON.stringify(args));
+    if (encoded.length > MAX_INLINE_ARGS && typeof args.code === "string") {
+      const codeFile = `/tmp/.lizard-code/in-${randomId()}`;
+      await this.fs.write(codeFile, args.code);
+      const { code: _code, ...rest } = args;
+      encoded = toBase64(JSON.stringify({ ...rest, codeFile }));
+    }
+    let part = "";
+    let fatal;
+    let sawEvent = false;
+    const stderr = [];
+    const result = await this.process.exec(["python3", "-c", RUNNER_SOURCE, encoded], {
+      timeoutMs: timeoutMs + RUNNER_OVERHEAD_MS,
+      onStdout: (line) => {
+        let ev;
+        try {
+          ev = JSON.parse(line);
+          if (ev.type === "part") {
+            part += ev.data;
+            if (!ev.end) return;
+            ev = JSON.parse(part);
+            part = "";
+          }
+        } catch {
+          part = "";
+          return;
+        }
+        sawEvent = true;
+        if (ev.type === "fatal") fatal = ev.message;
+        else onEvent(ev);
+      },
+      onStderr: (line) => {
+        stderr.push(line);
+      }
+    });
+    if (fatal) throw new LizardError(fatal);
+    if (result.exitCode !== 0 || !sawEvent) {
+      const detail = stderr.slice(-20).join("\n").trim() || `exit code ${result.exitCode}`;
+      throw new LizardError(`Code runner failed (python3 is required in the sandbox): ${detail}`);
+    }
   }
   static async create(templateOrOpts, opts) {
     return super.create(templateOrOpts, opts);
@@ -2119,27 +2455,83 @@ var CodeSandbox = class extends Sandbox {
     return super.connect(sandboxId, opts);
   }
 };
-CodeSandbox.defaultTemplate = "code-interpreter-v1";
-async function* readLines(body) {
-  const reader = body.getReader();
-  const decoder = new TextDecoder();
-  let buf = "";
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      buf += decoder.decode(value, { stream: true });
-      const lines = buf.split("\n");
-      buf = lines.pop() ?? "";
-      for (const line of lines) {
-        if (line.trim()) yield line;
+CodeSandbox.defaultTemplate = "interpreter";
+function randomId() {
+  const c = globalThis.crypto;
+  return c?.randomUUID ? c.randomUUID().replace(/-/g, "").slice(0, 16) : Math.random().toString(16).slice(2, 18);
+}
+function toBase64(text) {
+  if (typeof Buffer !== "undefined") return Buffer.from(text, "utf8").toString("base64");
+  const bytes = new TextEncoder().encode(text);
+  let s = "";
+  for (let i = 0; i < bytes.length; i += 32768) s += String.fromCharCode(...bytes.subarray(i, i + 32768));
+  return btoa(s);
+}
+
+// src/cli.ts
+var import_node_child_process = require("child_process");
+var LizardCLI = class {
+  constructor(opts = {}) {
+    this.opts = opts;
+  }
+  run(args, opts = {}) {
+    return new Promise((resolve, reject) => {
+      const env = { ...process.env };
+      if (this.opts.apiKey) {
+        env.LIZARD_API_KEY = this.opts.apiKey;
+        env.LIZARD_TOKEN = this.opts.apiKey;
       }
-    }
-    if (buf.trim()) yield buf;
-  } finally {
-    reader.releaseLock();
+      if (this.opts.apiUrl) env.LIZARD_API_URL = this.opts.apiUrl;
+      const child = (0, import_node_child_process.spawn)(this.opts.executable ?? "lizard", ["--json", ...args], {
+        cwd: this.opts.cwd,
+        env,
+        shell: false,
+        stdio: "pipe",
+        signal: opts.signal,
+        timeout: this.opts.timeoutMs ?? 6e5
+      });
+      child.stdout.setEncoding("utf8");
+      child.stderr.setEncoding("utf8");
+      let stdout = "", stderr = "", bytes = 0;
+      const collect = (stream, data) => {
+        bytes += Buffer.byteLength(data);
+        if (bytes > 16 * 1024 * 1024) {
+          child.kill();
+          reject(new Error("CLI output exceeds 16 MiB"));
+          return;
+        }
+        if (stream === "stdout") stdout += data;
+        else stderr += data;
+      };
+      child.stdout.on("data", (data) => collect("stdout", data));
+      child.stderr.on("data", (data) => collect("stderr", data));
+      child.on("error", reject);
+      child.on("close", (code, signal) => {
+        if (signal) {
+          reject(new Error(`CLI ended with signal ${signal}`));
+          return;
+        }
+        let events = [];
+        try {
+          events = [JSON.parse(stdout)];
+        } catch {
+          events = stdout.split("\n").filter(Boolean).flatMap((line) => {
+            try {
+              return [JSON.parse(line)];
+            } catch {
+              return [];
+            }
+          });
+        }
+        resolve({ code: code ?? 1, stdout, stderr, events });
+      });
+      child.stdin.on("error", (error) => {
+        if (error.code !== "EPIPE") reject(error);
+      });
+      child.stdin.end(opts.stdin);
+    });
   }
-}
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AddonsAPI,
@@ -2158,6 +2550,7 @@ async function* readLines(body) {
   LizardError,
   MetricsAPI,
   NotFoundError,
+  PaymentRequiredError,
   PlatformClient,
   ProjectsAPI,
   RegionsAPI,