@lizard-build/sdk 0.1.29 → 0.1.31

package/dist/index.d.mts

@@ -70,8 +70,12 @@ interface FsOpts {
 interface FileInfo {
     name: string;
     path: string;
-    type: 'file' | 'dir';
+    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. */
+    modTime?: number;
 }
 /**
  * Read and write files inside a Lizard sandbox microVM.
@@ -126,6 +130,35 @@ declare class Fs {
      * Create a directory (and any missing parents) inside the microVM.
      */
     makeDir(path: string, opts?: FsOpts): Promise<void>;
+    /**
+     * Metadata for a single path — size, type, permissions, modification time.
+     *
+     * Saves listing a parent directory and filtering it just to answer "does this
+     * exist, and how big is it".
+     *
+     * @example
+     * ```ts
+     * const info = await sandbox.fs.stat('/app/out.bin')
+     * 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.
+     */
+    stat(path: string, opts?: FsOpts): Promise<FileInfo>;
+    /**
+     * Move or rename a path. Creates the destination's parent directories.
+     *
+     * @example
+     * ```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>;
     private execInternal;
 }
 
@@ -150,7 +183,14 @@ interface SandboxOpts extends ConnectionOpts {
     metadata?: Record<string, string>;
     envs?: Record<string, string>;
     timeoutMs?: number;
+    /** Attach a persistent volume by id, mounted at `/data`. */
     volumeId?: string;
+    /**
+     * Attach a persistent volume by name, mounted at `/data`. A volume's name is its
+     * key inside a project, so this is usually what you want — see {@link Volume}.
+     * Requires the sandbox's project to be given as an exact `projectId`.
+     */
+    volumeName?: string;
 }
 /**
  * Low-level HTTP client for the Lizard sandbox API.
@@ -293,9 +333,16 @@ declare class Sandbox extends SandboxClient {
      * nothing is written to disk, so a paused sandbox does not survive a host
      * failure. Resume with `sandbox.resume()` or `Sandbox.connect(id)`.
      *
-     * Pausing does not stop the timeout: a paused sandbox is still deleted at
-     * its original expiry (default 5 minutes). Pass `timeoutMs: 0` at create
-     * time to opt out of expiry.
+     * Pausing does not buy you time past the original deadline. Resuming pushes the
+     * expiry forward by however long the sandbox was paused — so a pause/resume cycle
+     * costs no runtime — but that adjustment only happens on `resume()`. A sandbox left
+     * paused past its original `expiresAt` is deleted there, within a minute, and
+     * `resume()` then returns `false`.
+     *
+     * In other words: pause and come back *before* the original deadline and you lose
+     * nothing; leave it paused across the deadline and it is gone. Pass `timeoutMs: 0`
+     * at create time to opt out of expiry entirely, which is the only way to park a
+     * sandbox indefinitely.
      *
      * @returns `true` if paused successfully.
      */
@@ -303,7 +350,12 @@ declare class Sandbox extends SandboxClient {
     /**
      * Resume a paused sandbox by unfreezing its vCPUs.
      *
-     * @returns `true` if resumed successfully.
+     * The expiry is pushed forward by the time spent paused, so the timeout measures
+     * running time rather than wall-clock — provided the original deadline had not
+     * already passed while paused. See {@link pause}.
+     *
+     * @returns `true` if resumed successfully, `false` if the sandbox no longer exists
+     * (including because it expired while paused).
      */
     resume(opts?: ConnectionOpts): Promise<boolean>;
     /**
@@ -780,6 +832,14 @@ declare class AuthenticationError extends LizardError {
 declare class NotFoundError extends LizardError {
     constructor(message?: string);
 }
+/**
+ * The resource already exists — most often a volume whose name is already taken in
+ * the project. Volume names are the key inside a project, so `Volume.create` refuses
+ * to make a second one; catch this, or call `Volume.getOrCreate` instead.
+ */
+declare class ConflictError extends LizardError {
+    constructor(message?: string);
+}
 declare class TimeoutError extends LizardError {
     constructor(message?: string);
 }
@@ -950,19 +1010,48 @@ interface CreateVolumeOpts extends ConnectionOpts {
 }
 /**
  * A persistent volume that outlives sandboxes.
- * Mount it to a sandbox via `Sandbox.create({ volumeId: volume.volumeId })`.
+ *
+ * A volume's **name** is its key inside a project: names are unique per project, and
+ * every method here accepts either a name or the generated id wherever a volume is
+ * addressed. Prefer the name — it is the thing you chose and can reconstruct, while
+ * the id only exists after the first create.
+ *
+ * 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' })`.
  */
 declare class Volume {
+    /** The volume's generated id. Stable, but you rarely need it — address by name. */
     readonly volumeId: string;
+    /** The volume's name: unique within its project, and usable anywhere `volumeId` is. */
+    readonly name?: string;
     private readonly config;
     constructor(opts: {
         volumeId: string;
+        name?: string;
     } & ConnectionOpts);
+    /**
+     * Create a volume. Throws `ConflictError` (409) if the project already has one with
+     * this name — use {@link getOrCreate} when you want "make sure this exists" instead.
+     */
     static create(projectId: string, name: string, opts?: CreateVolumeOpts): Promise<Volume>;
-    static get(projectId: string, volumeId: string, opts?: ConnectionOpts): Promise<Volume>;
+    /**
+     * Return the project's volume with this name, creating it first if it does not
+     * exist yet. This is the reason a volume's name is its key: an agent that wants
+     * "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
+     * and never resizes one that is already there.
+     */
+    static getOrCreate(projectId: string, name: string, opts?: CreateVolumeOpts): Promise<Volume>;
+    /** Look a volume up by name or by id. */
+    static get(projectId: string, nameOrId: string, opts?: ConnectionOpts): Promise<Volume>;
     static list(projectId: string, opts?: ConnectionOpts): Promise<VolumeInfo[]>;
+    /** Delete a volume by name or by id, without constructing one first. */
+    static delete(projectId: string, nameOrId: string, opts?: ConnectionOpts): Promise<void>;
     getInfo(projectId: string): Promise<VolumeInfo>;
     delete(projectId: string): Promise<void>;
 }
 
-export { type Addon, type AddonType, AuthenticationError, type CodeContext, CodeSandbox, type ConnectionOpts, type CostMetrics, type CreateAddonOpts, type CreateContextOpts, type CreateProjectOpts, type CreateServiceOpts, type CreateVolumeOpts, type DeployEvent, DeployHandle, type DomainInfo, Execution, ExecutionError, type FileInfo, type FsOpts, Lizard, LizardError, type LizardOpts, type LogLine, type MetricPoint, type MetricRange, NotFoundError, type ProcessOpts, type ProcessResult, type Project, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, type ScaleOpts, type Secret, type Service, type ServiceMetrics, type SetSecretOpts, TimeoutError, Volume, type VolumeInfo, resolveProjectId };
+export { type Addon, type AddonType, AuthenticationError, type CodeContext, CodeSandbox, ConflictError, type ConnectionOpts, type CostMetrics, type CreateAddonOpts, type CreateContextOpts, type CreateProjectOpts, type CreateServiceOpts, type CreateVolumeOpts, type DeployEvent, DeployHandle, type DomainInfo, Execution, ExecutionError, type FileInfo, type FsOpts, Lizard, LizardError, type LizardOpts, type LogLine, type MetricPoint, type MetricRange, NotFoundError, type ProcessOpts, type ProcessResult, type Project, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, type ScaleOpts, type Secret, type Service, type ServiceMetrics, type SetSecretOpts, TimeoutError, Volume, type VolumeInfo, resolveProjectId };

package/dist/index.d.ts

@@ -70,8 +70,12 @@ interface FsOpts {
 interface FileInfo {
     name: string;
     path: string;
-    type: 'file' | 'dir';
+    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. */
+    modTime?: number;
 }
 /**
  * Read and write files inside a Lizard sandbox microVM.
@@ -126,6 +130,35 @@ declare class Fs {
      * Create a directory (and any missing parents) inside the microVM.
      */
     makeDir(path: string, opts?: FsOpts): Promise<void>;
+    /**
+     * Metadata for a single path — size, type, permissions, modification time.
+     *
+     * Saves listing a parent directory and filtering it just to answer "does this
+     * exist, and how big is it".
+     *
+     * @example
+     * ```ts
+     * const info = await sandbox.fs.stat('/app/out.bin')
+     * 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.
+     */
+    stat(path: string, opts?: FsOpts): Promise<FileInfo>;
+    /**
+     * Move or rename a path. Creates the destination's parent directories.
+     *
+     * @example
+     * ```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>;
     private execInternal;
 }
 
@@ -150,7 +183,14 @@ interface SandboxOpts extends ConnectionOpts {
     metadata?: Record<string, string>;
     envs?: Record<string, string>;
     timeoutMs?: number;
+    /** Attach a persistent volume by id, mounted at `/data`. */
     volumeId?: string;
+    /**
+     * Attach a persistent volume by name, mounted at `/data`. A volume's name is its
+     * key inside a project, so this is usually what you want — see {@link Volume}.
+     * Requires the sandbox's project to be given as an exact `projectId`.
+     */
+    volumeName?: string;
 }
 /**
  * Low-level HTTP client for the Lizard sandbox API.
@@ -293,9 +333,16 @@ declare class Sandbox extends SandboxClient {
      * nothing is written to disk, so a paused sandbox does not survive a host
      * failure. Resume with `sandbox.resume()` or `Sandbox.connect(id)`.
      *
-     * Pausing does not stop the timeout: a paused sandbox is still deleted at
-     * its original expiry (default 5 minutes). Pass `timeoutMs: 0` at create
-     * time to opt out of expiry.
+     * Pausing does not buy you time past the original deadline. Resuming pushes the
+     * expiry forward by however long the sandbox was paused — so a pause/resume cycle
+     * costs no runtime — but that adjustment only happens on `resume()`. A sandbox left
+     * paused past its original `expiresAt` is deleted there, within a minute, and
+     * `resume()` then returns `false`.
+     *
+     * In other words: pause and come back *before* the original deadline and you lose
+     * nothing; leave it paused across the deadline and it is gone. Pass `timeoutMs: 0`
+     * at create time to opt out of expiry entirely, which is the only way to park a
+     * sandbox indefinitely.
      *
      * @returns `true` if paused successfully.
      */
@@ -303,7 +350,12 @@ declare class Sandbox extends SandboxClient {
     /**
      * Resume a paused sandbox by unfreezing its vCPUs.
      *
-     * @returns `true` if resumed successfully.
+     * The expiry is pushed forward by the time spent paused, so the timeout measures
+     * running time rather than wall-clock — provided the original deadline had not
+     * already passed while paused. See {@link pause}.
+     *
+     * @returns `true` if resumed successfully, `false` if the sandbox no longer exists
+     * (including because it expired while paused).
      */
     resume(opts?: ConnectionOpts): Promise<boolean>;
     /**
@@ -780,6 +832,14 @@ declare class AuthenticationError extends LizardError {
 declare class NotFoundError extends LizardError {
     constructor(message?: string);
 }
+/**
+ * The resource already exists — most often a volume whose name is already taken in
+ * the project. Volume names are the key inside a project, so `Volume.create` refuses
+ * to make a second one; catch this, or call `Volume.getOrCreate` instead.
+ */
+declare class ConflictError extends LizardError {
+    constructor(message?: string);
+}
 declare class TimeoutError extends LizardError {
     constructor(message?: string);
 }
@@ -950,19 +1010,48 @@ interface CreateVolumeOpts extends ConnectionOpts {
 }
 /**
  * A persistent volume that outlives sandboxes.
- * Mount it to a sandbox via `Sandbox.create({ volumeId: volume.volumeId })`.
+ *
+ * A volume's **name** is its key inside a project: names are unique per project, and
+ * every method here accepts either a name or the generated id wherever a volume is
+ * addressed. Prefer the name — it is the thing you chose and can reconstruct, while
+ * the id only exists after the first create.
+ *
+ * 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' })`.
  */
 declare class Volume {
+    /** The volume's generated id. Stable, but you rarely need it — address by name. */
     readonly volumeId: string;
+    /** The volume's name: unique within its project, and usable anywhere `volumeId` is. */
+    readonly name?: string;
     private readonly config;
     constructor(opts: {
         volumeId: string;
+        name?: string;
     } & ConnectionOpts);
+    /**
+     * Create a volume. Throws `ConflictError` (409) if the project already has one with
+     * this name — use {@link getOrCreate} when you want "make sure this exists" instead.
+     */
     static create(projectId: string, name: string, opts?: CreateVolumeOpts): Promise<Volume>;
-    static get(projectId: string, volumeId: string, opts?: ConnectionOpts): Promise<Volume>;
+    /**
+     * Return the project's volume with this name, creating it first if it does not
+     * exist yet. This is the reason a volume's name is its key: an agent that wants
+     * "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
+     * and never resizes one that is already there.
+     */
+    static getOrCreate(projectId: string, name: string, opts?: CreateVolumeOpts): Promise<Volume>;
+    /** Look a volume up by name or by id. */
+    static get(projectId: string, nameOrId: string, opts?: ConnectionOpts): Promise<Volume>;
     static list(projectId: string, opts?: ConnectionOpts): Promise<VolumeInfo[]>;
+    /** Delete a volume by name or by id, without constructing one first. */
+    static delete(projectId: string, nameOrId: string, opts?: ConnectionOpts): Promise<void>;
     getInfo(projectId: string): Promise<VolumeInfo>;
     delete(projectId: string): Promise<void>;
 }
 
-export { type Addon, type AddonType, AuthenticationError, type CodeContext, CodeSandbox, type ConnectionOpts, type CostMetrics, type CreateAddonOpts, type CreateContextOpts, type CreateProjectOpts, type CreateServiceOpts, type CreateVolumeOpts, type DeployEvent, DeployHandle, type DomainInfo, Execution, ExecutionError, type FileInfo, type FsOpts, Lizard, LizardError, type LizardOpts, type LogLine, type MetricPoint, type MetricRange, NotFoundError, type ProcessOpts, type ProcessResult, type Project, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, type ScaleOpts, type Secret, type Service, type ServiceMetrics, type SetSecretOpts, TimeoutError, Volume, type VolumeInfo, resolveProjectId };
+export { type Addon, type AddonType, AuthenticationError, type CodeContext, CodeSandbox, ConflictError, type ConnectionOpts, type CostMetrics, type CreateAddonOpts, type CreateContextOpts, type CreateProjectOpts, type CreateServiceOpts, type CreateVolumeOpts, type DeployEvent, DeployHandle, type DomainInfo, Execution, ExecutionError, type FileInfo, type FsOpts, Lizard, LizardError, type LizardOpts, type LogLine, type MetricPoint, type MetricRange, NotFoundError, type ProcessOpts, type ProcessResult, type Project, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, type ScaleOpts, type Secret, type Service, type ServiceMetrics, type SetSecretOpts, TimeoutError, Volume, type VolumeInfo, resolveProjectId };

package/dist/index.js

@@ -22,6 +22,7 @@ var index_exports = {};
 __export(index_exports, {
   AuthenticationError: () => AuthenticationError,
   CodeSandbox: () => CodeSandbox,
+  ConflictError: () => ConflictError,
   DeployHandle: () => DeployHandle,
   Lizard: () => Lizard,
   LizardError: () => LizardError,
@@ -74,6 +75,12 @@ var NotFoundError = class extends LizardError {
     this.name = "NotFoundError";
   }
 };
+var ConflictError = class extends LizardError {
+  constructor(message = "Resource already exists") {
+    super(message);
+    this.name = "ConflictError";
+  }
+};
 var TimeoutError = class extends LizardError {
   constructor(message = "Sandbox operation timed out") {
     super(message);
@@ -90,6 +97,7 @@ async function handleApiError(res) {
   }
   if (res.status === 401 || res.status === 403) throw new AuthenticationError(message);
   if (res.status === 404) throw new NotFoundError(message);
+  if (res.status === 409) throw new ConflictError(message);
   if (res.status === 408 || res.status === 504) throw new TimeoutError(message);
   throw new LizardError(`API error ${res.status}: ${message}`);
 }
@@ -253,6 +261,49 @@ var Fs = class {
   async makeDir(path, opts) {
     await this.execInternal(`mkdir -p ${JSON.stringify(path)}`, opts?.user);
   }
+  /**
+   * Metadata for a single path — size, type, permissions, modification time.
+   *
+   * Saves listing a parent directory and filtering it just to answer "does this
+   * exist, and how big is it".
+   *
+   * @example
+   * ```ts
+   * const info = await sandbox.fs.stat('/app/out.bin')
+   * 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.
+   */
+  async stat(path, opts) {
+    const url = new URL(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/files/stat`);
+    url.searchParams.set("path", path);
+    if (opts?.user) url.searchParams.set("user", opts.user);
+    const res = await fetch(url.toString(), { headers: this.config.headers });
+    if (!res.ok) await handleApiError(res);
+    return res.json();
+  }
+  /**
+   * Move or rename a path. Creates the destination's parent directories.
+   *
+   * @example
+   * ```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`, {
+      method: "POST",
+      headers: this.config.headers,
+      body: JSON.stringify({ from, to })
+    });
+    if (!res.ok) await handleApiError(res);
+  }
   async execInternal(cmd, user) {
     const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/exec`, {
       method: "POST",
@@ -278,7 +329,8 @@ var SandboxClient = class {
         projectId,
         metadata: opts?.metadata,
         envs: opts?.envs,
-        volumeId: opts?.volumeId
+        volumeId: opts?.volumeId,
+        volumeName: opts?.volumeName
       })
     });
     if (!res.ok) await handleApiError(res);
@@ -407,9 +459,16 @@ var Sandbox = class extends SandboxClient {
    * nothing is written to disk, so a paused sandbox does not survive a host
    * failure. Resume with `sandbox.resume()` or `Sandbox.connect(id)`.
    *
-   * Pausing does not stop the timeout: a paused sandbox is still deleted at
-   * its original expiry (default 5 minutes). Pass `timeoutMs: 0` at create
-   * time to opt out of expiry.
+   * Pausing does not buy you time past the original deadline. Resuming pushes the
+   * expiry forward by however long the sandbox was paused — so a pause/resume cycle
+   * costs no runtime — but that adjustment only happens on `resume()`. A sandbox left
+   * paused past its original `expiresAt` is deleted there, within a minute, and
+   * `resume()` then returns `false`.
+   *
+   * In other words: pause and come back *before* the original deadline and you lose
+   * nothing; leave it paused across the deadline and it is gone. Pass `timeoutMs: 0`
+   * at create time to opt out of expiry entirely, which is the only way to park a
+   * sandbox indefinitely.
    *
    * @returns `true` if paused successfully.
    */
@@ -419,7 +478,12 @@ var Sandbox = class extends SandboxClient {
   /**
    * Resume a paused sandbox by unfreezing its vCPUs.
    *
-   * @returns `true` if resumed successfully.
+   * The expiry is pushed forward by the time spent paused, so the timeout measures
+   * running time rather than wall-clock — provided the original deadline had not
+   * already passed while paused. See {@link pause}.
+   *
+   * @returns `true` if resumed successfully, `false` if the sandbox no longer exists
+   * (including because it expired while paused).
    */
   async resume(opts) {
     return SandboxClient.resumeSandbox(this.sandboxId, this.resolveOpts(opts));
@@ -1111,8 +1175,13 @@ async function* readLines(body) {
 var Volume = class _Volume {
   constructor(opts) {
     this.volumeId = opts.volumeId;
+    this.name = opts.name;
     this.config = new ConnectionConfig(opts);
   }
+  /**
+   * Create a volume. Throws `ConflictError` (409) if the project already has one with
+   * this name — use {@link getOrCreate} when you want "make sure this exists" instead.
+   */
   static async create(projectId, name, opts) {
     const config = new ConnectionConfig(opts);
     const res = await fetch(`${config.apiUrl}/api/projects/${projectId}/volumes`, {
@@ -1122,15 +1191,36 @@ var Volume = class _Volume {
     });
     if (!res.ok) await handleApiError(res);
     const vol = await res.json();
-    return new _Volume({ volumeId: vol.id, ...opts });
+    return new _Volume({ volumeId: vol.id, name: vol.name, ...opts });
   }
-  static async get(projectId, volumeId, opts) {
+  /**
+   * Return the project's volume with this name, creating it first if it does not
+   * exist yet. This is the reason a volume's name is its key: an agent that wants
+   * "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
+   * and never resizes one that is already there.
+   */
+  static async getOrCreate(projectId, name, opts) {
     const config = new ConnectionConfig(opts);
-    const res = await fetch(`${config.apiUrl}/api/projects/${projectId}/volumes/${volumeId}`, {
+    const res = await fetch(`${config.apiUrl}/api/projects/${projectId}/volumes`, {
+      method: "POST",
+      headers: config.headers,
+      body: JSON.stringify({ name, sizeGb: opts?.sizeGb ?? 5, getOrCreate: true })
+    });
+    if (!res.ok) await handleApiError(res);
+    const vol = await res.json();
+    return new _Volume({ volumeId: vol.id, name: vol.name, ...opts });
+  }
+  /** Look a volume up by name or by id. */
+  static async get(projectId, nameOrId, opts) {
+    const config = new ConnectionConfig(opts);
+    const res = await fetch(`${config.apiUrl}/api/projects/${projectId}/volumes/${encodeURIComponent(nameOrId)}`, {
       headers: config.headers
     });
     if (!res.ok) await handleApiError(res);
-    return new _Volume({ volumeId, ...opts });
+    const vol = await res.json();
+    return new _Volume({ volumeId: vol.id, name: vol.name, ...opts });
   }
   static async list(projectId, opts) {
     const config = new ConnectionConfig(opts);
@@ -1140,6 +1230,15 @@ var Volume = class _Volume {
     if (!res.ok) await handleApiError(res);
     return res.json();
   }
+  /** Delete a volume by name or by id, without constructing one first. */
+  static async delete(projectId, nameOrId, opts) {
+    const config = new ConnectionConfig(opts);
+    const res = await fetch(`${config.apiUrl}/api/projects/${projectId}/volumes/${encodeURIComponent(nameOrId)}`, {
+      method: "DELETE",
+      headers: config.headers
+    });
+    if (!res.ok) await handleApiError(res);
+  }
   async getInfo(projectId) {
     const res = await fetch(`${this.config.apiUrl}/api/projects/${projectId}/volumes/${this.volumeId}`, {
       headers: this.config.headers
@@ -1159,6 +1258,7 @@ var Volume = class _Volume {
 0 && (module.exports = {
   AuthenticationError,
   CodeSandbox,
+  ConflictError,
   DeployHandle,
   Lizard,
   LizardError,

package/dist/index.mjs

@@ -39,6 +39,12 @@ var NotFoundError = class extends LizardError {
     this.name = "NotFoundError";
   }
 };
+var ConflictError = class extends LizardError {
+  constructor(message = "Resource already exists") {
+    super(message);
+    this.name = "ConflictError";
+  }
+};
 var TimeoutError = class extends LizardError {
   constructor(message = "Sandbox operation timed out") {
     super(message);
@@ -55,6 +61,7 @@ async function handleApiError(res) {
   }
   if (res.status === 401 || res.status === 403) throw new AuthenticationError(message);
   if (res.status === 404) throw new NotFoundError(message);
+  if (res.status === 409) throw new ConflictError(message);
   if (res.status === 408 || res.status === 504) throw new TimeoutError(message);
   throw new LizardError(`API error ${res.status}: ${message}`);
 }
@@ -218,6 +225,49 @@ var Fs = class {
   async makeDir(path, opts) {
     await this.execInternal(`mkdir -p ${JSON.stringify(path)}`, opts?.user);
   }
+  /**
+   * Metadata for a single path — size, type, permissions, modification time.
+   *
+   * Saves listing a parent directory and filtering it just to answer "does this
+   * exist, and how big is it".
+   *
+   * @example
+   * ```ts
+   * const info = await sandbox.fs.stat('/app/out.bin')
+   * 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.
+   */
+  async stat(path, opts) {
+    const url = new URL(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/files/stat`);
+    url.searchParams.set("path", path);
+    if (opts?.user) url.searchParams.set("user", opts.user);
+    const res = await fetch(url.toString(), { headers: this.config.headers });
+    if (!res.ok) await handleApiError(res);
+    return res.json();
+  }
+  /**
+   * Move or rename a path. Creates the destination's parent directories.
+   *
+   * @example
+   * ```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`, {
+      method: "POST",
+      headers: this.config.headers,
+      body: JSON.stringify({ from, to })
+    });
+    if (!res.ok) await handleApiError(res);
+  }
   async execInternal(cmd, user) {
     const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/exec`, {
       method: "POST",
@@ -243,7 +293,8 @@ var SandboxClient = class {
         projectId,
         metadata: opts?.metadata,
         envs: opts?.envs,
-        volumeId: opts?.volumeId
+        volumeId: opts?.volumeId,
+        volumeName: opts?.volumeName
       })
     });
     if (!res.ok) await handleApiError(res);
@@ -372,9 +423,16 @@ var Sandbox = class extends SandboxClient {
    * nothing is written to disk, so a paused sandbox does not survive a host
    * failure. Resume with `sandbox.resume()` or `Sandbox.connect(id)`.
    *
-   * Pausing does not stop the timeout: a paused sandbox is still deleted at
-   * its original expiry (default 5 minutes). Pass `timeoutMs: 0` at create
-   * time to opt out of expiry.
+   * Pausing does not buy you time past the original deadline. Resuming pushes the
+   * expiry forward by however long the sandbox was paused — so a pause/resume cycle
+   * costs no runtime — but that adjustment only happens on `resume()`. A sandbox left
+   * paused past its original `expiresAt` is deleted there, within a minute, and
+   * `resume()` then returns `false`.
+   *
+   * In other words: pause and come back *before* the original deadline and you lose
+   * nothing; leave it paused across the deadline and it is gone. Pass `timeoutMs: 0`
+   * at create time to opt out of expiry entirely, which is the only way to park a
+   * sandbox indefinitely.
    *
    * @returns `true` if paused successfully.
    */
@@ -384,7 +442,12 @@ var Sandbox = class extends SandboxClient {
   /**
    * Resume a paused sandbox by unfreezing its vCPUs.
    *
-   * @returns `true` if resumed successfully.
+   * The expiry is pushed forward by the time spent paused, so the timeout measures
+   * running time rather than wall-clock — provided the original deadline had not
+   * already passed while paused. See {@link pause}.
+   *
+   * @returns `true` if resumed successfully, `false` if the sandbox no longer exists
+   * (including because it expired while paused).
    */
   async resume(opts) {
     return SandboxClient.resumeSandbox(this.sandboxId, this.resolveOpts(opts));
@@ -1076,8 +1139,13 @@ async function* readLines(body) {
 var Volume = class _Volume {
   constructor(opts) {
     this.volumeId = opts.volumeId;
+    this.name = opts.name;
     this.config = new ConnectionConfig(opts);
   }
+  /**
+   * Create a volume. Throws `ConflictError` (409) if the project already has one with
+   * this name — use {@link getOrCreate} when you want "make sure this exists" instead.
+   */
   static async create(projectId, name, opts) {
     const config = new ConnectionConfig(opts);
     const res = await fetch(`${config.apiUrl}/api/projects/${projectId}/volumes`, {
@@ -1087,15 +1155,36 @@ var Volume = class _Volume {
     });
     if (!res.ok) await handleApiError(res);
     const vol = await res.json();
-    return new _Volume({ volumeId: vol.id, ...opts });
+    return new _Volume({ volumeId: vol.id, name: vol.name, ...opts });
   }
-  static async get(projectId, volumeId, opts) {
+  /**
+   * Return the project's volume with this name, creating it first if it does not
+   * exist yet. This is the reason a volume's name is its key: an agent that wants
+   * "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
+   * and never resizes one that is already there.
+   */
+  static async getOrCreate(projectId, name, opts) {
     const config = new ConnectionConfig(opts);
-    const res = await fetch(`${config.apiUrl}/api/projects/${projectId}/volumes/${volumeId}`, {
+    const res = await fetch(`${config.apiUrl}/api/projects/${projectId}/volumes`, {
+      method: "POST",
+      headers: config.headers,
+      body: JSON.stringify({ name, sizeGb: opts?.sizeGb ?? 5, getOrCreate: true })
+    });
+    if (!res.ok) await handleApiError(res);
+    const vol = await res.json();
+    return new _Volume({ volumeId: vol.id, name: vol.name, ...opts });
+  }
+  /** Look a volume up by name or by id. */
+  static async get(projectId, nameOrId, opts) {
+    const config = new ConnectionConfig(opts);
+    const res = await fetch(`${config.apiUrl}/api/projects/${projectId}/volumes/${encodeURIComponent(nameOrId)}`, {
       headers: config.headers
     });
     if (!res.ok) await handleApiError(res);
-    return new _Volume({ volumeId, ...opts });
+    const vol = await res.json();
+    return new _Volume({ volumeId: vol.id, name: vol.name, ...opts });
   }
   static async list(projectId, opts) {
     const config = new ConnectionConfig(opts);
@@ -1105,6 +1194,15 @@ var Volume = class _Volume {
     if (!res.ok) await handleApiError(res);
     return res.json();
   }
+  /** Delete a volume by name or by id, without constructing one first. */
+  static async delete(projectId, nameOrId, opts) {
+    const config = new ConnectionConfig(opts);
+    const res = await fetch(`${config.apiUrl}/api/projects/${projectId}/volumes/${encodeURIComponent(nameOrId)}`, {
+      method: "DELETE",
+      headers: config.headers
+    });
+    if (!res.ok) await handleApiError(res);
+  }
   async getInfo(projectId) {
     const res = await fetch(`${this.config.apiUrl}/api/projects/${projectId}/volumes/${this.volumeId}`, {
       headers: this.config.headers
@@ -1123,6 +1221,7 @@ var Volume = class _Volume {
 export {
   AuthenticationError,
   CodeSandbox,
+  ConflictError,
   DeployHandle,
   Lizard,
   LizardError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lizard-build/sdk",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "description": "Firecracker microVM sandboxes for AI agents — boot Linux in milliseconds, run code, write files, expose ports over HTTPS, then pause a session with memory intact and resume it later. TypeScript SDK for Lizard Sandboxes (lizard.build).",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",