@lizard-build/sdk 0.1.49 → 0.1.52

package/dist/index.d.mts

@@ -385,12 +385,19 @@ declare class GitHubAPI {
     checkout(serviceId: string, branch: string): Promise<DeployHandle>;
 }
 
-/** A process this sandbox is currently running. */
+/** A process this sandbox is currently running (one started through `exec`). */
 interface ProcessInfo {
     pid: number;
+    /** The argv: `['/bin/sh', '-c', 'npm test']` for a shell command. */
     cmd: string[];
-    /** When the process started, unix milliseconds. */
-    startedAt: number;
+    /** `cmd` joined with spaces, for display. */
+    command?: string;
+    /** Working directory the process was started in, when known. */
+    cwd?: string | null;
+    /** The process's tag, when it was started with one. */
+    tag?: string | null;
+    /** When the process started, unix milliseconds. Not reported by every sandbox. */
+    startedAt?: number;
 }
 /** Signals accepted by {@link Process.kill}. */
 type ProcessSignal = 'SIGTERM' | 'SIGKILL' | 'SIGINT' | 'SIGHUP' | 'SIGQUIT' | 'SIGUSR1' | 'SIGUSR2';
@@ -460,11 +467,6 @@ declare class Process {
      * ```
      */
     exec(cmd: string | string[], opts?: ProcessOpts): Promise<ProcessResult>;
-    /**
-     * 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.
      *
@@ -482,8 +484,8 @@ declare class Process {
     /**
      * 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`.
@@ -495,6 +497,11 @@ declare class Process {
      * ```
      */
     kill(pid: number, signal?: ProcessSignal): Promise<void>;
+    /**
+     * 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.
+     */
     private consumeStream;
 }
 
@@ -514,10 +521,20 @@ interface FileInfo {
     path: string;
     type: 'file' | 'dir' | 'symlink';
     size: number;
-    /** Permission bits as a string, e.g. `-rw-r--r--`. Absent on older sandboxes. */
-    mode?: string;
-    /** Last modification time, unix milliseconds. Absent on older sandboxes. */
+    /** Permission bits as a number, e.g. `0o644` (420). */
+    mode?: number;
+    /** Permission bits as a string, e.g. `-rw-r--r--`. */
+    permissions?: string;
+    /** Owning user name. */
+    owner?: string;
+    /** Owning group name. */
+    group?: string;
+    /** Last modification time, unix milliseconds. */
     modTime?: number;
+    /** Same as `modTime`, unix milliseconds. */
+    modifiedAt?: number;
+    /** Where a symlink points, for a symlink. */
+    symlinkTarget?: string;
 }
 /**
  * Read and write files inside a Lizard sandbox.
@@ -531,25 +548,29 @@ declare class Fs {
     /**
      * 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'))
      * ```
      */
-    write(path: string, data: string | Uint8Array, opts?: FsOpts): Promise<void>;
+    write(path: string, data: string | Uint8Array | ArrayBuffer, opts?: FsOpts): Promise<void>;
     /**
      * 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')
@@ -587,9 +608,7 @@ declare class Fs {
      * 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.
      */
     stat(path: string, opts?: FsOpts): Promise<FileInfo>;
     /**
@@ -599,9 +618,6 @@ declare class Fs {
      * ```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.
      */
     move(from: string, to: string): Promise<void>;
     /**
@@ -623,8 +639,7 @@ declare class Fs {
      * }, 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).
      */
     watch(path: string, opts?: {
         recursive?: boolean;
@@ -773,6 +788,8 @@ interface SandboxInfo {
     /** Region the sandbox runs in — the volume's region when one is attached. */
     region?: string;
     status?: string;
+    /** The sandbox runtime: `'firecracker'` (a microVM), `'container'`, or `null` when unknown. */
+    runtime?: 'firecracker' | 'container' | null;
     pauseError?: string | null;
     /** Machine size (`'small' | 'medium' | 'large'`); may be `null` for a sandbox created from a private snapshot. */
     size?: 'small' | 'medium' | 'large' | null;
@@ -782,6 +799,19 @@ interface SandboxInfo {
     memoryMb?: number;
     metadata?: Record<string, string>;
 }
+/** A sandbox port published on a public HTTPS hostname. See {@link Sandbox.exposePort}. */
+interface ExposedPort {
+    /** Hostname without a scheme, e.g. `abc-3000.sandbox.eu-west-lim-a.onlizard.com`. */
+    hostname: string;
+    /** A browser URL that carries the access token (`?lizard_token=...`). */
+    url: string;
+    port: number;
+    /**
+     * The port is private: every request needs this token, either as the
+     * `X-Lizard-Access-Token` header or once as `?lizard_token=` (a browser then gets a cookie).
+     */
+    accessToken: string;
+}
 interface SandboxOpts extends ConnectionOpts {
     /**
      * The project this sandbox belongs to — its ID, slug, or name. Required:
@@ -808,7 +838,9 @@ interface SandboxOpts extends ConnectionOpts {
      * Measured CPU/RAM are not charged and egress is free. Ignored with {@link SandboxOpts.snapshotId}.
      */
     size?: 'small' | 'medium' | 'large';
+    /** Your own key/value labels for the sandbox, returned by `getInfo()` and `list()`. */
     metadata?: Record<string, string>;
+    /** Environment variables set in the sandbox, visible to every command it runs. */
     envs?: Record<string, string>;
     timeoutMs?: number;
     /**
@@ -868,10 +900,7 @@ declare class SandboxClient {
     }): Promise<SandboxInfo[]>;
     protected static getSandboxInfo(sandboxId: string, opts?: ConnectionOpts): Promise<SandboxInfo>;
     protected static setTimeoutSandbox(sandboxId: string, timeoutMs: number, opts?: ConnectionOpts): Promise<void>;
-    protected static exposeSandboxPort(sandboxId: string, port: number, opts?: ConnectionOpts): Promise<{
-        hostname: string;
-        url: string;
-    }>;
+    protected static exposeSandboxPort(sandboxId: string, port: number, opts?: ConnectionOpts): Promise<ExposedPort>;
 }
 
 interface SandboxSnapshot {
@@ -887,18 +916,37 @@ interface SandboxSnapshot {
     error: string | null;
     cpus: number;
     memoryMb: number;
+    /** Unix milliseconds. */
     createdAt: number;
 }
 interface SnapshotOpts {
+    /** Warm copies to keep ready (container sandboxes only; ignored for Firecracker, whose snapshots restore from disk). */
     poolSize?: number;
 }
+/**
+ * One entry of {@link Sandbox.fork}'s result: the new sandbox, or why that copy
+ * could not be made (e.g. the account's sandbox limit).
+ */
+type ForkResult<S extends Sandbox = Sandbox> = {
+    sandbox: S;
+    info: SandboxInfo;
+    error?: undefined;
+} | {
+    sandbox?: undefined;
+    info?: undefined;
+    error: string;
+};
 interface SnapshotWaitOpts extends ConnectionOpts {
     waitTimeoutMs?: number;
 }
 /**
- * A Linux sandbox running on Kubernetes.
+ * A Linux sandbox: a Firecracker microVM with its own kernel.
  *
- * Run commands, read and write files, and expose HTTP ports in a sandbox.
+ * Run commands, read and write files, and expose HTTP ports in a sandbox. A
+ * sandbox boots in well under a second; {@link pause} and {@link resume} keep its
+ * memory and running processes, {@link snapshot} saves it in about 2 s and
+ * {@link restore} starts a copy in about 0.4 s, and {@link fork} clones a running
+ * sandbox, processes and all.
  *
  * Sandboxes are **ephemeral**: killing one, or letting it hit its timeout, discards
  * everything written inside it. State that has to outlive a sandbox belongs on a
@@ -990,8 +1038,9 @@ declare class Sandbox extends SandboxClient {
      * Create a new Lizard sandbox from the specified template.
      *
      * Template availability and installed tools depend on the platform and region.
-     * Use `base` for shell commands or `interpreter` for Python process commands.
-     * Hosted templates do not support the legacy `CodeSandbox` execution API.
+     * Use `base` for shell commands, `interpreter` for Python with the data stack
+     * (use {@link CodeSandbox} to run code snippets in it), or `desktop` for a
+     * graphical desktop.
      *
      * @param template Name of the sandbox template to boot from.
      *
@@ -1033,9 +1082,15 @@ declare class Sandbox extends SandboxClient {
      * @returns `true` if the sandbox was terminated, `false` if it was already gone.
      */
     kill(opts?: ConnectionOpts): Promise<boolean>;
-    /** 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.
+     */
     pause(opts?: ConnectionOpts): Promise<boolean>;
-    /** 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.
+     */
     resume(opts?: ConnectionOpts): Promise<boolean>;
     /** Wait for an asynchronous pause/resume operation to finish. */
     waitForStatus(status: 'paused' | 'running', opts?: SnapshotWaitOpts): Promise<SandboxInfo>;
@@ -1050,39 +1105,81 @@ declare class Sandbox extends SandboxClient {
      */
     setTimeout(timeoutMs: number, opts?: ConnectionOpts): Promise<void>;
     /**
-     * Register a public HTTPS route and return its hostname without a scheme.
+     * The token that opens this sandbox's published ports. Set by {@link getHost}
+     * and {@link exposePort}; send it as the `X-Lizard-Access-Token` header.
+     */
+    accessToken?: string;
+    /**
+     * 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! },
+     * })
      * ```
      */
     getHost(port: number, opts?: ConnectionOpts): Promise<string>;
-    /** Fork is unsupported on Kubernetes; the backend returns HTTP 501. */
+    /**
+     * 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 } })
+     * ```
+     */
+    exposePort(port: number, opts?: ConnectionOpts): Promise<ExposedPort>;
+    /**
+     * 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')
+     * ```
+     */
     fork(opts?: {
         count?: number;
         timeoutMs?: number;
-    }): Promise<unknown>;
-    /** Capture memory and workspace files. Disconnect active clients before capturing. */
+    }): Promise<ForkResult<this>[]>;
+    /**
+     * 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?: string, opts?: SnapshotOpts): Promise<SandboxSnapshot>;
     unexpose(port: number): Promise<void>;
+    /** Stream the sandbox's logs. Not available on Firecracker sandboxes yet (`LizardError`, 501). */
     logs(opts?: {
         tail?: number;
         signal?: AbortSignal;
     }): AsyncGenerator<StreamEvent, any, any>;
     static snapshots(projectId: string, opts?: ConnectionOpts): Promise<SandboxSnapshot[]>;
     static getSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
-    /** 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 restore(snapshotId: string, opts?: ConnectionOpts & {
         timeoutMs?: number;
     }): Promise<Sandbox>;
     static setSnapshotWarmPool(snapshotId: string, poolSize: number, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
-    /** 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: string, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
     /** Refill the configured warm pool without another capture. */
     static resumeSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
@@ -1423,6 +1520,7 @@ declare class RegionsAPI {
     list(): Promise<Region[]>;
 }
 
+/** Prepaid credits balance: old credits accounts (`plan: 'payg'`) until 1 November 2026, and enterprise usage. */
 interface Balance {
     plan: string;
     status: 'active' | 'grace' | 'frozen' | string;
@@ -1461,61 +1559,180 @@ interface ListTransactionsOpts {
     includeUsage?: boolean;
 }
 /**
- * Account balance and usage.
+ * `none`: no plan yet (creating anything answers 402). `pro`: the Pro subscription, see
+ * {@link Subscription.status}. `payg`: old prepaid credits, until 1 November 2026.
+ * `enterprise`: pay as you go, invoiced monthly.
+ */
+type Plan = 'none' | 'pro' | 'payg' | 'enterprise';
+/** Pro subscription status; `none` when there is no subscription. */
+type SubscriptionStatus = 'trialing' | 'active' | 'past_due' | 'canceled' | 'none';
+interface Subscription {
+    plan: Plan | (string & {});
+    status: SubscriptionStatus | (string & {});
+    /** False when read for a workspace the caller does not own; card and invoice fields are then null. */
+    isOwner: boolean;
+    /** 1900: $19/month. */
+    priceCents: number;
+    /** The price includes taxes. */
+    taxIncluded: boolean;
+    /** Credits included each paid month, in cents (1900). */
+    includedCents: number;
+    trial: {
+        /** The account can start a trial now. */
+        eligible: boolean;
+        /** Trial length it would get, or got. */
+        days: number | null;
+        /** Trial credits, in cents. */
+        creditCents: number | null;
+        /** Promo code held for the trial, if any. */
+        promoCode: string | null;
+        /** Trial end (ms); null when not trialing. */
+        endsAt: number | null;
+        /** Trial credits used (trialing only). */
+        usedCents: number | null;
+        remainingCents: number | null;
+    };
+    /** The current Pro period; null when there is none. */
+    period: {
+        kind: 'trial' | 'paid';
+        start: number;
+        end: number;
+        /** 500 in the trial, 1900 in a paid month. */
+        includedCents: number;
+        usedCents: number;
+        /** Paid month: usage above the included credits. */
+        overageCents: number;
+        /** Of the overage, already invoiced. */
+        billedOverageCents: number;
+        unbilledOverageCents: number;
+        /** Paid month: unbilled overage at which the next invoice goes out. */
+        nextOverageChargeAtCents: number | null;
+    } | null;
+    /** Null when there is none, or the subscription is cancelling. */
+    nextCharge: {
+        at: number | null;
+        amountCents: number;
+    } | null;
+    /** When a cancelled subscription ends (ms). */
+    cancelAt: number | null;
+    /** An invoice is unpaid. */
+    pastDue: boolean;
+    /** Stripe page that pays it (owner only). */
+    openInvoiceUrl: string | null;
+    paymentMethod: {
+        brand: string;
+        last4: string;
+        expMonth: number;
+        expYear: number;
+    } | null;
+    /** Pro only: `tier` is `trial` or `pro`. */
+    limits: {
+        tier: string;
+        replicasPerApp: number;
+    } | null;
+    /** Pro Checkout is open for this account. */
+    checkoutAvailable: boolean;
+}
+interface StartCheckoutOpts {
+    /** Dashboard path to come back to after Checkout, e.g. `/projects/abc`. */
+    returnUrl?: string;
+}
+interface CheckoutSession {
+    /** Stripe Checkout page. The user finishes it in a browser. */
+    url: string;
+    sessionId: string;
+    /** Null when the account already had a trial: Pro starts at once and charges $19. */
+    trialDays: number | null;
+    trialCreditCents: number | null;
+}
+interface StartProNowResult {
+    /**
+     * `active`: charged $19, the first paid month started. `requires_action`: the bank
+     * wants a confirmation (or declined); open `invoiceUrl`, the trial continues.
+     * `failed`: nothing changed, the trial continues.
+     */
+    status: 'active' | 'requires_action' | 'failed';
+    invoiceUrl?: string | null;
+}
+interface PromoRedemption {
+    /** `pending_payment_method`: held for the trial Checkout starts. `applied`: applied now. */
+    status: string;
+    code?: string;
+    /** The trial credits (older servers: the credit amount). */
+    creditCents: number;
+    expiresAt: number | null;
+    /** Kept for older clients. */
+    balanceCents: number;
+    /** Trial length the code gives. Missing from servers before Pro. */
+    trialDays?: number;
+    trialCreditCents?: number;
+    /** `next_checkout`: held for the trial `startCheckout` opens. `current_trial`: extended the running trial. */
+    appliesTo?: 'next_checkout' | 'current_trial';
+}
+/**
+ * The account's plan, balance and usage.
+ *
+ * Pro costs $19/month, taxes included, with $19 of credits each month; usage above that
+ * is pay as you go, invoiced as it builds up. A new account starts with a 7-day trial
+ * with $5 of credits. Enterprise is pay as you go, invoiced monthly. Old prepaid
+ * credits accounts (`plan: 'payg'`) keep {@link balance} and {@link transactions}
+ * until 1 November 2026.
  *
  * Billing is **account-scoped, not workspace-scoped**: every workspace you create for
  * a user bills to the account that owns the key. That is what makes per-user
- * workspaces a safe pattern — your users get isolation, you keep one bill — and also
- * what makes {@link Balance.runwayHours} worth watching before you provision more.
+ * workspaces a safe pattern — your users get isolation, you keep one bill.
+ *
+ * **Requires an unscoped key**, except {@link subscription} with a `workspaceId` the
+ * key can reach. A scoped key is refused with 403 `ACCOUNT_SCOPE_REQUIRED`, because a
+ * scoped key is meant to be handed to an end user, who should not be reading your
+ * card details or changing your plan. For per-workspace spend, use
+ * {@link MetricsAPI.cost} instead.
  *
- * **Requires an unscoped key.** A scoped key is refused with 403
- * `ACCOUNT_SCOPE_REQUIRED`, because there is no workspace-scoped view of one shared
- * balance, ledger and set of saved cards — and because a scoped key is meant to be
- * handed to an end user, who should not be reading your card details or spending
- * against them. For per-workspace spend, use {@link MetricsAPI.cost} instead.
+ * Checkout and invoices are web pages: methods return their URL for the user to open.
+ * Nothing here retries a payment.
  */
 declare class BillingAPI {
     private readonly client;
     constructor(client: PlatformClient);
-    /** 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?: {
+        workspaceId?: string;
+    }): Promise<Subscription>;
+    /**
+     * 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?: StartCheckoutOpts): Promise<CheckoutSession>;
+    /** Ends the trial now: charges $19 and starts the first paid month with $19 of credits. */
+    startProNow(): Promise<StartProNowResult>;
+    /** Cancels Pro at the end of the current month or trial. Cancelling in the trial costs nothing. */
+    cancel(): Promise<{
+        cancelAt: number | null;
+    }>;
+    /** Undoes {@link cancel}: Pro renews as usual. */
+    resume(): Promise<{
+        cancelAt: null;
+    }>;
+    /** Redeems a promo code: a longer trial with more trial credits. Works only before the first payment. */
+    redeemPromo(code: string): Promise<PromoRedemption>;
+    /** Prepaid credits balance, status, burn rate and runway (old `payg` accounts and enterprise). */
     balance(): Promise<Balance>;
-    /** A page of balance transactions, newest first. */
+    /** A page of balance transactions, newest first (old `payg` accounts and enterprise). */
     transactions(opts?: ListTransactionsOpts): Promise<TransactionPage>;
     /** Cost summary for the current billing period, broken down by resource. */
     summary(): Promise<unknown>;
     /** Live (not-yet-invoiced) usage accumulating right now. */
     live(): Promise<unknown>;
+    /** Saved cards. Cards are added in Checkout or on the Billing page. */
     paymentMethods(): Promise<{
         items: unknown[];
     }>;
-    setupPaymentMethod(returnUrl?: string): Promise<{
-        url: string;
-    }>;
     removePaymentMethod(id: string): Promise<void>;
-    purchase(creditCents: number, opts?: {
-        paymentMethod?: 'card' | 'crypto';
-        returnUrl?: string;
-    }): Promise<{
-        url: string;
-        sessionId?: string;
-    }>;
-    autoTopup(): Promise<unknown>;
-    setAutoTopup(opts: {
-        enabled: boolean;
-        thresholdCents: number;
-        amountCents: number;
-        paymentMethodIds: string[];
-    }): Promise<unknown>;
-    runAutoTopup(): Promise<unknown>;
-    redeemPromo(code: string): Promise<unknown>;
-    x402Quote(creditCents: number): Promise<unknown>;
-    paymentStatus(attemptId: string): Promise<unknown>;
-    /** Pay with the CLI's durable x402 journal. Requires CLI >= 4.0.8. Amounts are cents. */
-    payX402(creditCents: number, opts: {
-        maxTotalCents: number;
-        requestId?: string;
-        executable?: string;
-    }): Promise<unknown>;
 }
 
 interface VolumeInfo {
@@ -1527,8 +1744,10 @@ interface VolumeInfo {
     /** Region the volume's node lives in. A sandbox mounting it runs here too. */
     region?: string;
     status: string;
+    /** Id of the sandbox the volume is attached to, or `null` when it is free. */
     attachedTo?: string | null;
-    createdAt: number;
+    /** Creation time: an ISO-8601 string for Firecracker volumes, unix milliseconds for container volumes. */
+    createdAt: string | number;
     /**
      * Whether `sizeGb` is actually enforced as a hard limit on the volume's node.
      * Returned by {@link Volume.resize}; `false` means the size was recorded but the
@@ -1537,7 +1756,7 @@ interface VolumeInfo {
     sizeEnforced?: boolean;
 }
 interface CreateVolumeOpts extends ConnectionOpts {
-    /** Whole GB, default 5. New volumes allow 1–50 GB unless the server config sets another maximum. Creating never changes an existing volume's size; use `Volume.resize` for that. */
+    /** Whole GB, default 5. New volumes allow 1–50 GB unless the server config sets another maximum. Creating never changes an existing volume's size. */
     sizeGb?: number;
     /**
      * Region to place the volume in, e.g. `'us-east-1'`. A volume is node-local, so
@@ -1560,7 +1779,9 @@ interface CreateVolumeOpts extends ConnectionOpts {
  * Names are slugs: lowercase letters, digits and dashes, starting and ending with a
  * letter or digit, up to 64 characters.
  *
- * Mount one to a sandbox via `Sandbox.create({ volumeName: 'my-data' })`.
+ * Mount one to a sandbox via `Sandbox.create({ volumeName: 'my-data' })`; it appears
+ * at `/workspace`. A volume is attached to one sandbox at a time (`attachedTo`), and
+ * a sandbox with a volume attached cannot be forked.
  */
 declare class Volume {
     /** The volume's generated id. Stable, but you rarely need it — address by name. */
@@ -1583,7 +1804,7 @@ declare 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 getOrCreate(projectId: string, name: string, opts?: CreateVolumeOpts): Promise<Volume>;
     /** Look a volume up by name or by id. */
@@ -1594,11 +1815,15 @@ declare 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`,
@@ -1609,7 +1834,7 @@ declare class Volume {
      */
     static resize(projectId: string, nameOrId: string, sizeGb: number, opts?: ConnectionOpts): Promise<VolumeInfo>;
     getInfo(projectId: string): Promise<VolumeInfo>;
-    /** 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). */
     resize(projectId: string, sizeGb: number): Promise<VolumeInfo>;
     delete(projectId: string): Promise<void>;
 }
@@ -1791,6 +2016,34 @@ declare class ConflictError extends LizardError {
 declare class TimeoutError extends LizardError {
     constructor(message?: string);
 }
+/**
+ * The account has to pay before it can do this (HTTP 402). Every create call answers
+ * 402 when the account has no plan yet, its trial credits are used up, or an invoice
+ * is unpaid. Show {@link message} to the user as is and send them to {@link url}.
+ *
+ * Still a {@link LizardError}, so existing `catch` blocks keep working.
+ */
+declare class PaymentRequiredError extends LizardError {
+    /**
+     * Why payment is needed: `trial_available` (start the Pro trial),
+     * `subscription_required` (the trial was used: start Pro), `trial_credits_used`
+     * (start Pro now), `past_due` or `paused` (pay the open invoice), or, for accounts
+     * on the old prepaid credits, `grace`, `frozen`, `card_required` or
+     * `credits_required`. {@link LizardError.status} stays the HTTP status, 402.
+     */
+    paymentStatus?: string;
+    /** Billing page that starts the Pro trial, or Pro when the trial was used. */
+    subscribeUrl?: string;
+    /** The Billing page. */
+    billingUrl?: string;
+    /** The Credits page, for accounts on the old prepaid credits. */
+    topupUrl?: string;
+    /** Stripe page that pays an unpaid invoice (`code` `UNPAID_INVOICE`). */
+    invoiceUrl?: string;
+    constructor(message?: string);
+    /** The one page to open next for this {@link paymentStatus}. */
+    get url(): string | undefined;
+}
 
 /** A single output item produced during code execution. */
 type OutputItem = {
@@ -1827,7 +2080,7 @@ declare class Execution {
     results: OutputItem[];
     /** Execution error if the code threw an exception. */
     error?: ExecutionError;
-    /** Monotonically increasing counter for this context. */
+    /** Monotonically increasing counter for this context (the Python kernel's `In[n]`). */
     executionCount: number;
     get success(): boolean;
     get text(): string;
@@ -1842,11 +2095,15 @@ type RunCodeLanguage = 'python' | 'javascript' | 'bash' | (string & Record<never
 interface RunCodeOpts {
     /** Language to run in. Defaults to python. */
     language?: RunCodeLanguage;
-    /** Use a specific context instead of the per-language default. */
+    /** Use a specific context (from `createContext`) instead of the per-language default. */
     context?: CodeContext;
     /** Extra environment variables available to the code. */
     envs?: Record<string, string>;
-    /** Client timeout in milliseconds. No client timer is set when omitted. */
+    /**
+     * Execution timeout in milliseconds, default 60 000. A Python kernel that runs
+     * past it is interrupted (its state is kept) and `execution.error.name` is
+     * `'TimeoutError'`; a process is killed.
+     */
     timeoutMs?: number;
     onStdout?: (data: string) => void;
     onStderr?: (data: string) => void;
@@ -1859,31 +2116,47 @@ interface CreateContextOpts {
 }
 
 /**
- * Legacy client for the code-interpreter execution server.
+ * A sandbox for running code snippets, built on {@link Sandbox.process}.
+ *
+ * Boots the `interpreter` template by default. Python runs in a persistent
+ * Jupyter kernel per context, so variables, imports and functions carry over
+ * between calls, `execution.results` holds rich output (the value of the last
+ * expression, matplotlib charts as `image/png`, HTML, ...) and errors carry
+ * the exception name and traceback.
  *
- * Current hosted templates do not provide this server. The default
- * `code-interpreter-v1` template is unavailable; selecting `interpreter`
- * does not enable this API. Use `Sandbox.create('interpreter', options)`
- * and `sandbox.process.exec()` for Python commands instead.
+ * Limits, honestly:
+ * - `javascript` (node) and `bash` run each call as a fresh process: no state
+ *   carries over and `results` stays empty. `node` must be installed in the
+ *   template; the `interpreter` template does not ship it.
+ * - On a template without Jupyter (e.g. `base`), Python also runs as a fresh
+ *   process per call.
+ * - `stdout`/`stderr` are delivered in the chunks the kernel or process
+ *   produced them, not per character.
  *
- * The methods remain for compatibility with a separately provided server.
+ * Kernels live inside the sandbox's microVM, so pause/resume, snapshots and
+ * forks keep their state.
+ *
+ * @example
+ * ```ts
+ * const sandbox = await CodeSandbox.create({ project: 'my-project' })
+ * await sandbox.runCode('x = 21')
+ * const run = await sandbox.runCode('x * 2')
+ * console.log(run.results[0].data) // "42"
+ * await sandbox.kill()
+ * ```
  */
 declare class CodeSandbox extends Sandbox {
-    protected static readonly defaultTemplate = "code-interpreter-v1";
-    private get serverUrl();
+    protected static readonly defaultTemplate: string;
     /**
-     * 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(`
@@ -1897,8 +2170,8 @@ declare class CodeSandbox extends Sandbox {
     /**
      * 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
@@ -1908,18 +2181,14 @@ declare class CodeSandbox extends Sandbox {
      * ```
      */
     createContext(opts?: CreateContextOpts): Promise<CodeContext>;
-    /**
-     * List all active execution contexts in this sandbox.
-     */
+    /** List the contexts created with {@link createContext} in this sandbox. */
     listContexts(): Promise<CodeContext[]>;
-    /**
-     * Delete an execution context and free its resources.
-     */
+    /** Delete an execution context, stopping its kernel. */
     deleteContext(context: CodeContext | string): Promise<void>;
-    /**
-     * Restart a context, clearing all variables and state.
-     */
+    /** Restart a context, clearing all variables and state. */
     restartContext(context: CodeContext | string): Promise<void>;
+    /** Run the in-sandbox runner with `args` and hand each of its events to `onEvent`. */
+    private runner;
     static create(opts?: SandboxOpts): Promise<CodeSandbox>;
     static create(template: string, opts?: SandboxOpts): Promise<CodeSandbox>;
     static connect(sandboxId: string, opts?: ConnectionOpts): Promise<CodeSandbox>;
@@ -1949,4 +2218,4 @@ declare class LizardCLI {
     }): Promise<CLIResult>;
 }
 
-export { type Account, type Addon, type AddonType, AddonsAPI, type ApiKey, type ApiKeyScope, ApiKeysAPI, AuthenticationError, type Balance, BillingAPI, type CLIOptions, type CLIResult, type ClickOpts, type CodeContext, CodeSandbox, ConfigApplyError, type ConfigResult, ConflictError, type ConnectionOpts, type CostMetrics, type CreateAddonOpts, type CreateApiKeyOpts, type CreateContextOpts, type CreateProjectOpts, type CreateServiceOpts, type CreateVolumeOpts, type CreateWorkspaceOpts, type CreatedApiKey, type DeployEvent, DeployHandle, Desktop, type DesktopInfo, type DesktopStartOpts, type DomainInfo, type DomainStatus, DomainsAPI, Execution, ExecutionError, type FileInfo, type FsOpts, GitHubAPI, type ListTransactionsOpts, Lizard, LizardCLI, LizardError, type LizardOpts, type LogLine, type MetricPoint, type MetricRange, MetricsAPI, type MouseButton, NotFoundError, PlatformClient, type ProcessOpts, type ProcessResult, type Project, type ProjectConfig, type ProjectCost, ProjectsAPI, type RawMetrics, type Region, RegionsAPI, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, type SandboxSnapshot, type ScaleOpts, type ScrollDirection, type Secret, SecretsAPI, type Service, type ServiceMetrics, type ServiceUpdate, ServicesAPI, type SetSecretOpts, type SnapshotOpts, type SnapshotWaitOpts, StorageAPI, type StreamEvent, TimeoutError, type Transaction, type TransactionPage, Volume, type VolumeInfo, type Workspace, WorkspacesAPI, resolveProjectId };
+export { type Account, type Addon, type AddonType, AddonsAPI, type ApiKey, type ApiKeyScope, ApiKeysAPI, AuthenticationError, type Balance, BillingAPI, type CLIOptions, type CLIResult, type CheckoutSession, type ClickOpts, type CodeContext, CodeSandbox, ConfigApplyError, type ConfigResult, ConflictError, type ConnectionOpts, type CostMetrics, type CreateAddonOpts, type CreateApiKeyOpts, type CreateContextOpts, type CreateProjectOpts, type CreateServiceOpts, type CreateVolumeOpts, type CreateWorkspaceOpts, type CreatedApiKey, type DeployEvent, DeployHandle, Desktop, type DesktopInfo, type DesktopStartOpts, type DomainInfo, type DomainStatus, DomainsAPI, Execution, ExecutionError, type ExposedPort, type FileInfo, type ForkResult, type FsEvent, type FsOpts, GitHubAPI, type ListTransactionsOpts, Lizard, LizardCLI, LizardError, type LizardOpts, type LogLine, type MetricPoint, type MetricRange, MetricsAPI, type MouseButton, NotFoundError, PaymentRequiredError, type Plan, PlatformClient, type ProcessInfo, type ProcessOpts, type ProcessResult, type ProcessSignal, type Project, type ProjectConfig, type ProjectCost, ProjectsAPI, type PromoRedemption, type RawMetrics, type Region, RegionsAPI, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, type SandboxSnapshot, type ScaleOpts, type ScrollDirection, type Secret, SecretsAPI, type Service, type ServiceMetrics, type ServiceUpdate, ServicesAPI, type SetSecretOpts, type SnapshotOpts, type SnapshotWaitOpts, type StartCheckoutOpts, type StartProNowResult, StorageAPI, type StreamEvent, type Subscription, type SubscriptionStatus, TimeoutError, type Transaction, type TransactionPage, Volume, type VolumeInfo, type Workspace, WorkspacesAPI, resolveProjectId };