@vercel/sandbox 1.9.3 → 1.10.1

package/dist/sandbox.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox.cjs","names":["getCredentials","APIClient","WORKFLOW_SERIALIZE","WORKFLOW_DESERIALIZE","getPrivateParams","toSandboxSnapshot","Command","params: RunCommandParams","command","CommandFinished","path","consumeReadable","Snapshot"],"sources":["../src/sandbox.ts"],"sourcesContent":["import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from \"@workflow/serde\";\nimport { createWriteStream } from \"fs\";\nimport { mkdir } from \"fs/promises\";\nimport { dirname, resolve } from \"path\";\nimport type { Writable } from \"stream\";\nimport { pipeline } from \"stream/promises\";\nimport type { WithFetchOptions } from \"./api-client/api-client.js\";\nimport type { SandboxMetaData, SandboxRouteData } from \"./api-client/index.js\";\nimport { APIClient } from \"./api-client/index.js\";\nimport { Command, CommandFinished } from \"./command.js\";\nimport type { RUNTIMES } from \"./constants.js\";\nimport type {\n  NetworkPolicy,\n  NetworkPolicyRule,\n  NetworkTransformer,\n} from \"./network-policy.js\";\nimport { Snapshot } from \"./snapshot.js\";\nimport { consumeReadable } from \"./utils/consume-readable.js\";\nimport { type Credentials, getCredentials } from \"./utils/get-credentials.js\";\nimport {\n  type SandboxSnapshot,\n  toSandboxSnapshot,\n} from \"./utils/sandbox-snapshot.js\";\nimport { getPrivateParams, type WithPrivate } from \"./utils/types.js\";\n\nexport type { NetworkPolicy, NetworkPolicyRule, NetworkTransformer };\n\n/** @inline */\nexport interface BaseCreateSandboxParams {\n  /**\n   * The source of the sandbox.\n   *\n   * Omit this parameter start a sandbox without a source.\n   *\n   * For git sources:\n   * - `depth`: Creates shallow clones with limited commit history (minimum: 1)\n   * - `revision`: Clones and checks out a specific commit, branch, or tag\n   */\n  source?:\n    | {\n        type: \"git\";\n        url: string;\n        depth?: number;\n        revision?: string;\n      }\n    | {\n        type: \"git\";\n        url: string;\n        username: string;\n        password: string;\n        depth?: number;\n        revision?: string;\n      }\n    | { type: \"tarball\"; url: string };\n  /**\n   * Array of port numbers to expose from the sandbox. Sandboxes can\n   * expose up to 4 ports.\n   */\n  ports?: number[];\n  /**\n   * Timeout in milliseconds before the sandbox auto-terminates.\n   */\n  timeout?: number;\n  /**\n   * Resources to allocate to the sandbox.\n   *\n   * Your sandbox will get the amount of vCPUs you specify here and\n   * 2048 MB of memory per vCPU.\n   */\n  resources?: { vcpus: number };\n\n  /**\n   * The runtime of the sandbox, currently only `node24`, `node22` and `python3.13` are supported.\n   * If not specified, the default runtime `node24` will be used.\n   */\n  runtime?: RUNTIMES | (string & {});\n\n  /**\n   * Network policy to define network restrictions for the sandbox.\n   * Defaults to full internet access if not specified.\n   */\n  networkPolicy?: NetworkPolicy;\n\n  /**\n   * Default environment variables for the sandbox.\n   * These are inherited by all commands unless overridden with\n   * the `env` option in `runCommand`.\n   *\n   * @example\n   * const sandbox = await Sandbox.create({\n   *   env: { NODE_ENV: \"production\", API_KEY: \"secret\" },\n   * });\n   * // All commands will have NODE_ENV and API_KEY set\n   * await sandbox.runCommand(\"node\", [\"app.js\"]);\n   */\n  env?: Record<string, string>;\n\n  /**\n   * An AbortSignal to cancel sandbox creation.\n   */\n  signal?: AbortSignal;\n}\n\nexport type CreateSandboxParams =\n  | BaseCreateSandboxParams\n  | (Omit<BaseCreateSandboxParams, \"runtime\" | \"source\"> & {\n      source: { type: \"snapshot\"; snapshotId: string };\n    });\n\n/** @inline */\ninterface GetSandboxParams {\n  /**\n   * Unique identifier of the sandbox.\n   */\n  sandboxId: string;\n  /**\n   * An AbortSignal to cancel the operation.\n   */\n  signal?: AbortSignal;\n}\n\n/**\n * Serialized representation of a Sandbox for @workflow/serde.\n */\nexport interface SerializedSandbox {\n  metadata: SandboxSnapshot;\n  routes: SandboxRouteData[];\n}\n\n/** @inline */\ninterface RunCommandParams {\n  /**\n   * The command to execute\n   */\n  cmd: string;\n  /**\n   * Arguments to pass to the command\n   */\n  args?: string[];\n  /**\n   * Working directory to execute the command in\n   */\n  cwd?: string;\n  /**\n   * Environment variables to set for this command\n   */\n  env?: Record<string, string>;\n  /**\n   * If true, execute this command with root privileges. Defaults to false.\n   */\n  sudo?: boolean;\n  /**\n   * If true, the command will return without waiting for `exitCode`\n   */\n  detached?: boolean;\n  /**\n   * A `Writable` stream where `stdout` from the command will be piped\n   */\n  stdout?: Writable;\n  /**\n   * A `Writable` stream where `stderr` from the command will be piped\n   */\n  stderr?: Writable;\n  /**\n   * An AbortSignal to cancel the command execution\n   */\n  signal?: AbortSignal;\n}\n\n// ============================================================================\n// Sandbox class\n// ============================================================================\n\n/**\n * A Sandbox is an isolated Linux MicroVM to run commands in.\n *\n * Use {@link Sandbox.create} or {@link Sandbox.get} to construct.\n * @hideconstructor\n */\nexport class Sandbox {\n  private _client: APIClient | null = null;\n\n  /**\n   * Lazily resolve credentials and construct an API client.\n   * This is used in step contexts where the Sandbox was deserialized\n   * without a client (e.g. when crossing workflow/step boundaries).\n   * Uses getCredentials() which resolves from OIDC or env vars.\n   * @internal\n   */\n  private async ensureClient(): Promise<APIClient> {\n    \"use step\";\n    if (this._client) return this._client;\n    const credentials = await getCredentials();\n    this._client = new APIClient({\n      teamId: credentials.teamId,\n      token: credentials.token,\n    });\n    return this._client;\n  }\n\n  /**\n   * Routes from ports to subdomains.\n  /* @hidden\n   */\n  public readonly routes: SandboxRouteData[];\n\n  /**\n   * Unique ID of this sandbox.\n   */\n  public get sandboxId(): string {\n    return this.sandbox.id;\n  }\n\n  public get interactivePort(): number | undefined {\n    return this.sandbox.interactivePort ?? undefined;\n  }\n\n  /**\n   * The status of the sandbox.\n   */\n  public get status(): SandboxMetaData[\"status\"] {\n    return this.sandbox.status;\n  }\n\n  /**\n   * The creation date of the sandbox.\n   */\n  public get createdAt(): Date {\n    return new Date(this.sandbox.createdAt);\n  }\n\n  /**\n   * The timeout of the sandbox in milliseconds.\n   */\n  public get timeout(): number {\n    return this.sandbox.timeout;\n  }\n\n  /**\n   * The network policy of the sandbox.\n   */\n  public get networkPolicy(): NetworkPolicy | undefined {\n    return this.sandbox.networkPolicy;\n  }\n\n  /**\n   * If the sandbox was created from a snapshot, the ID of that snapshot.\n   */\n  public get sourceSnapshotId(): string | undefined {\n    return this.sandbox.sourceSnapshotId;\n  }\n\n  /**\n   * The amount of CPU used by the sandbox. Only reported once the VM is stopped.\n   */\n  public get activeCpuUsageMs(): number | undefined {\n    return this.sandbox.activeCpuDurationMs;\n  }\n\n  /**\n   * The amount of network data used by the sandbox. Only reported once the VM is stopped.\n   */\n  public get networkTransfer():\n    | { ingress: number; egress: number }\n    | undefined {\n    return this.sandbox.networkTransfer;\n  }\n\n  /**\n   * Internal metadata about this sandbox.\n   */\n  private sandbox: SandboxSnapshot;\n\n  /**\n   * Allow to get a list of sandboxes for a team narrowed to the given params.\n   * It returns both the sandboxes and the pagination metadata to allow getting\n   * the next page of results.\n   */\n  static async list(\n    params?: Partial<Parameters<APIClient[\"listSandboxes\"]>[0]> &\n      Partial<Credentials> &\n      WithFetchOptions,\n  ) {\n    \"use step\";\n    const credentials = await getCredentials(params);\n    const client = new APIClient({\n      teamId: credentials.teamId,\n      token: credentials.token,\n      fetch: params?.fetch,\n    });\n    return client.listSandboxes({\n      ...credentials,\n      ...params,\n    });\n  }\n\n  /**\n   * Serialize a Sandbox instance to plain data for @workflow/serde.\n   *\n   * @param instance - The Sandbox instance to serialize\n   * @returns A plain object containing sandbox metadata and routes\n   */\n  static [WORKFLOW_SERIALIZE](instance: Sandbox): SerializedSandbox {\n    return {\n      metadata: instance.sandbox,\n      routes: instance.routes,\n    };\n  }\n\n  /**\n   * Deserialize a Sandbox from serialized snapshot data.\n   *\n   * The deserialized instance uses the serialized metadata synchronously and\n   * lazily creates an API client only when methods perform API requests.\n   *\n   * @param data - The serialized sandbox data\n   * @returns The reconstructed Sandbox instance\n   */\n  static [WORKFLOW_DESERIALIZE](data: SerializedSandbox): Sandbox {\n    return new Sandbox({\n      sandbox: data.metadata,\n      routes: data.routes,\n    });\n  }\n\n  /**\n   * Create a new sandbox.\n   *\n   * @param params - Creation parameters and optional credentials.\n   * @returns A promise resolving to the created {@link Sandbox}.\n   * @example\n   * <caption>Create a sandbox and drop it in the end of the block</caption>\n   * async function fn() {\n   *   await using const sandbox = await Sandbox.create();\n   *   // Sandbox automatically stopped at the end of the lexical scope\n   * }\n   */\n  static async create(\n    params?: WithPrivate<\n      CreateSandboxParams | (CreateSandboxParams & Credentials)\n    > &\n      WithFetchOptions,\n  ): Promise<Sandbox & AsyncDisposable> {\n    \"use step\";\n    const credentials = await getCredentials(params);\n    const client = new APIClient({\n      teamId: credentials.teamId,\n      token: credentials.token,\n      fetch: params?.fetch,\n    });\n\n    const privateParams = getPrivateParams(params);\n    const sandbox = await client.createSandbox({\n      source: params?.source,\n      projectId: credentials.projectId,\n      ports: params?.ports ?? [],\n      timeout: params?.timeout,\n      resources: params?.resources,\n      runtime: params && \"runtime\" in params ? params?.runtime : undefined,\n      networkPolicy: params?.networkPolicy,\n      env: params?.env,\n      signal: params?.signal,\n      ...privateParams,\n    });\n\n    return new DisposableSandbox({\n      client,\n      sandbox: toSandboxSnapshot(sandbox.json.sandbox),\n      routes: sandbox.json.routes,\n    });\n  }\n\n  /**\n   * Retrieve an existing sandbox.\n   *\n   * @param params - Get parameters and optional credentials.\n   * @returns A promise resolving to the {@link Sandbox}.\n   */\n  static async get(\n    params: WithPrivate<GetSandboxParams | (GetSandboxParams & Credentials)> &\n      WithFetchOptions,\n  ): Promise<Sandbox> {\n    \"use step\";\n    const credentials = await getCredentials(params);\n    const client = new APIClient({\n      teamId: credentials.teamId,\n      token: credentials.token,\n      fetch: params.fetch,\n    });\n\n    const privateParams = getPrivateParams(params);\n    const sandbox = await client.getSandbox({\n      sandboxId: params.sandboxId,\n      signal: params.signal,\n      ...privateParams,\n    });\n\n    return new Sandbox({\n      client,\n      sandbox: toSandboxSnapshot(sandbox.json.sandbox),\n      routes: sandbox.json.routes,\n    });\n  }\n\n  /**\n   * Create a new Sandbox instance.\n   *\n   * @param params.client - Optional API client. If not provided, will be lazily created using global credentials.\n   * @param params.routes - Port-to-subdomain mappings for exposed ports\n   * @param params.sandbox - Sandbox snapshot metadata\n   */\n  constructor({\n    client,\n    routes,\n    sandbox,\n  }: {\n    client?: APIClient;\n    routes: SandboxRouteData[];\n    sandbox: SandboxSnapshot;\n  }) {\n    this._client = client ?? null;\n    this.routes = routes;\n    this.sandbox = sandbox;\n  }\n\n  /**\n   * Get a previously run command by its ID.\n   *\n   * @param cmdId - ID of the command to retrieve\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A {@link Command} instance representing the command\n   */\n  async getCommand(\n    cmdId: string,\n    opts?: { signal?: AbortSignal },\n  ): Promise<Command> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const command = await client.getCommand({\n      sandboxId: this.sandbox.id,\n      cmdId,\n      signal: opts?.signal,\n    });\n\n    return new Command({\n      client,\n      sandboxId: this.sandbox.id,\n      cmd: command.json.command,\n    });\n  }\n\n  /**\n   * Start executing a command in this sandbox.\n   *\n   * @param command - The command to execute.\n   * @param args - Arguments to pass to the command.\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the command execution.\n   * @returns A {@link CommandFinished} result once execution is done.\n   */\n  async runCommand(\n    command: string,\n    args?: string[],\n    opts?: { signal?: AbortSignal },\n  ): Promise<CommandFinished>;\n\n  /**\n   * Start executing a command in detached mode.\n   *\n   * @param params - The command parameters.\n   * @returns A {@link Command} instance for the running command.\n   */\n  async runCommand(\n    params: RunCommandParams & { detached: true },\n  ): Promise<Command>;\n\n  /**\n   * Start executing a command in this sandbox.\n   *\n   * @param params - The command parameters.\n   * @returns A {@link CommandFinished} result once execution is done.\n   */\n  async runCommand(params: RunCommandParams): Promise<CommandFinished>;\n\n  async runCommand(\n    commandOrParams: string | RunCommandParams,\n    args?: string[],\n    opts?: { signal?: AbortSignal },\n  ): Promise<Command | CommandFinished> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const params: RunCommandParams =\n      typeof commandOrParams === \"string\"\n        ? { cmd: commandOrParams, args, signal: opts?.signal }\n        : commandOrParams;\n\n    const wait = params.detached ? false : true;\n    const pipeLogs = async (command: Command): Promise<void> => {\n      if (!params.stdout && !params.stderr) {\n        return;\n      }\n\n      try {\n        for await (const log of command.logs({ signal: params.signal })) {\n          if (log.stream === \"stdout\") {\n            params.stdout?.write(log.data);\n          } else if (log.stream === \"stderr\") {\n            params.stderr?.write(log.data);\n          }\n        }\n      } catch (err) {\n        if (params.signal?.aborted) {\n          return;\n        }\n        throw err;\n      }\n    };\n\n    if (wait) {\n      const commandStream = await client.runCommand({\n        sandboxId: this.sandbox.id,\n        command: params.cmd,\n        args: params.args ?? [],\n        cwd: params.cwd,\n        env: params.env ?? {},\n        sudo: params.sudo ?? false,\n        wait: true,\n        signal: params.signal,\n      });\n\n      const command = new Command({\n        client,\n        sandboxId: this.sandbox.id,\n        cmd: commandStream.command,\n      });\n\n      const [finished] = await Promise.all([\n        commandStream.finished,\n        pipeLogs(command),\n      ]);\n      return new CommandFinished({\n        client,\n        sandboxId: this.sandbox.id,\n        cmd: finished,\n        exitCode: finished.exitCode ?? 0,\n      });\n    }\n\n    const commandResponse = await client.runCommand({\n      sandboxId: this.sandbox.id,\n      command: params.cmd,\n      args: params.args ?? [],\n      cwd: params.cwd,\n      env: params.env ?? {},\n      sudo: params.sudo ?? false,\n      signal: params.signal,\n    });\n\n    const command = new Command({\n      client,\n      sandboxId: this.sandbox.id,\n      cmd: commandResponse.json.command,\n    });\n\n    void pipeLogs(command).catch((err) => {\n      if (params.signal?.aborted) {\n        return;\n      }\n      (params.stderr ?? params.stdout)?.emit(\"error\", err);\n    });\n\n    return command;\n  }\n\n  /**\n   * Create a directory in the filesystem of this sandbox.\n   *\n   * @param path - Path of the directory to create\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   */\n  async mkDir(path: string, opts?: { signal?: AbortSignal }): Promise<void> {\n    \"use step\";\n    const client = await this.ensureClient();\n    await client.mkDir({\n      sandboxId: this.sandbox.id,\n      path: path,\n      signal: opts?.signal,\n    });\n  }\n\n  /**\n   * Read a file from the filesystem of this sandbox as a stream.\n   *\n   * @param file - File to read, with path and optional cwd\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A promise that resolves to a ReadableStream containing the file contents, or null if file not found\n   */\n  async readFile(\n    file: { path: string; cwd?: string },\n    opts?: { signal?: AbortSignal },\n  ): Promise<NodeJS.ReadableStream | null> {\n    \"use step\";\n    const client = await this.ensureClient();\n    return client.readFile({\n      sandboxId: this.sandbox.id,\n      path: file.path,\n      cwd: file.cwd,\n      signal: opts?.signal,\n    });\n  }\n\n  /**\n   * Read a file from the filesystem of this sandbox as a Buffer.\n   *\n   * @param file - File to read, with path and optional cwd\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A promise that resolves to the file contents as a Buffer, or null if file not found\n   */\n  async readFileToBuffer(\n    file: { path: string; cwd?: string },\n    opts?: { signal?: AbortSignal },\n  ): Promise<Buffer | null> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const stream = await client.readFile({\n      sandboxId: this.sandbox.id,\n      path: file.path,\n      cwd: file.cwd,\n      signal: opts?.signal,\n    });\n\n    if (stream === null) {\n      return null;\n    }\n\n    return consumeReadable(stream);\n  }\n\n  /**\n   * Download a file from the sandbox to the local filesystem.\n   *\n   * @param src - Source file on the sandbox, with path and optional cwd\n   * @param dst - Destination file on the local machine, with path and optional cwd\n   * @param opts - Optional parameters.\n   * @param opts.mkdirRecursive - If true, create parent directories for the destination if they don't exist.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns The absolute path to the written file, or null if the source file was not found\n   */\n  async downloadFile(\n    src: { path: string; cwd?: string },\n    dst: { path: string; cwd?: string },\n    opts?: { mkdirRecursive?: boolean; signal?: AbortSignal },\n  ): Promise<string | null> {\n    \"use step\";\n    const client = await this.ensureClient();\n    if (!src?.path) {\n      throw new Error(\"downloadFile: source path is required\");\n    }\n\n    if (!dst?.path) {\n      throw new Error(\"downloadFile: destination path is required\");\n    }\n\n    const stream = await client.readFile({\n      sandboxId: this.sandbox.id,\n      path: src.path,\n      cwd: src.cwd,\n      signal: opts?.signal,\n    });\n\n    if (stream === null) {\n      return null;\n    }\n\n    try {\n      const dstPath = resolve(dst.cwd ?? \"\", dst.path);\n      if (opts?.mkdirRecursive) {\n        await mkdir(dirname(dstPath), { recursive: true });\n      }\n      await pipeline(stream, createWriteStream(dstPath), {\n        signal: opts?.signal,\n      });\n      return dstPath;\n    } finally {\n      stream.destroy();\n    }\n  }\n\n  /**\n   * Write files to the filesystem of this sandbox.\n   * Defaults to writing to /vercel/sandbox unless an absolute path is specified.\n   * Writes files using the `vercel-sandbox` user.\n   *\n   * @param files - Array of files with path, content, and optional mode (permissions)\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A promise that resolves when the files are written\n   *\n   * @example\n   * // Write an executable script\n   * await sandbox.writeFiles([\n   *   { path: \"/usr/local/bin/myscript\", content: \"#!/bin/bash\\necho hello\", mode: 0o755 }\n   * ]);\n   */\n  async writeFiles(\n    files: {\n      path: string;\n      content: string | Uint8Array;\n      mode?: number;\n    }[],\n    opts?: { signal?: AbortSignal },\n  ) {\n    \"use step\";\n    const client = await this.ensureClient();\n    return client.writeFiles({\n      sandboxId: this.sandbox.id,\n      cwd: this.sandbox.cwd,\n      extractDir: \"/\",\n      files: files,\n      signal: opts?.signal,\n    });\n  }\n\n  /**\n   * Get the public domain of a port of this sandbox.\n   *\n   * @param p - Port number to resolve\n   * @returns A full domain (e.g. `https://subdomain.vercel.run`)\n   * @throws If the port has no associated route\n   */\n  domain(p: number): string {\n    const route = this.routes.find(({ port }) => port == p);\n    if (route) {\n      return `https://${route.subdomain}.vercel.run`;\n    } else {\n      throw new Error(`No route for port ${p}`);\n    }\n  }\n\n  /**\n   * Stop the sandbox.\n   *\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @param opts.blocking - If true, poll until the sandbox has fully stopped and return the final state.\n   * @returns The sandbox metadata at the time the stop was acknowledged, or after fully stopped if `blocking` is true.\n   */\n  async stop(opts?: {\n    signal?: AbortSignal;\n    blocking?: boolean;\n  }): Promise<SandboxSnapshot> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const response = await client.stopSandbox({\n      sandboxId: this.sandbox.id,\n      signal: opts?.signal,\n      blocking: opts?.blocking,\n    });\n    this.sandbox = toSandboxSnapshot(response.json.sandbox);\n    return this.sandbox;\n  }\n\n  /**\n   * Update the network policy for this sandbox.\n   *\n   * @param networkPolicy - The new network policy to apply.\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A promise that resolves when the network policy is updated.\n   *\n   * @example\n   * // Restrict to specific domains\n   * await sandbox.updateNetworkPolicy({\n   *   allow: [\"*.npmjs.org\", \"github.com\"],\n   * });\n   *\n   * @example\n   * // Inject credentials with per-domain transformers\n   * await sandbox.updateNetworkPolicy({\n   *   allow: {\n   *     \"ai-gateway.vercel.sh\": [{\n   *       transform: [{\n   *         headers: { authorization: \"Bearer ...\" }\n   *       }]\n   *     }],\n   *     \"*\": []\n   *   }\n   * });\n   *\n   * @example\n   * // Deny all network access\n   * await sandbox.updateNetworkPolicy(\"deny-all\");\n   */\n  async updateNetworkPolicy(\n    networkPolicy: NetworkPolicy,\n    opts?: { signal?: AbortSignal },\n  ): Promise<NetworkPolicy> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const response = await client.updateNetworkPolicy({\n      sandboxId: this.sandbox.id,\n      networkPolicy: networkPolicy,\n      signal: opts?.signal,\n    });\n\n    // Update the internal sandbox metadata with the new timeout value\n    this.sandbox = toSandboxSnapshot(response.json.sandbox);\n    return this.sandbox.networkPolicy!;\n  }\n\n  /**\n   * Extend the timeout of the sandbox by the specified duration.\n   *\n   * This allows you to extend the lifetime of a sandbox up until the maximum\n   * execution timeout for your plan.\n   *\n   * @param duration - The duration in milliseconds to extend the timeout by\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A promise that resolves when the timeout is extended\n   *\n   * @example\n   * const sandbox = await Sandbox.create({ timeout: ms('10m') });\n   * // Extends timeout by 5 minutes, to a total of 15 minutes.\n   * await sandbox.extendTimeout(ms('5m'));\n   */\n  async extendTimeout(\n    duration: number,\n    opts?: { signal?: AbortSignal },\n  ): Promise<void> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const response = await client.extendTimeout({\n      sandboxId: this.sandbox.id,\n      duration,\n      signal: opts?.signal,\n    });\n\n    // Update the internal sandbox metadata with the new timeout value\n    this.sandbox = toSandboxSnapshot(response.json.sandbox);\n  }\n\n  /**\n   * Create a snapshot from this currently running sandbox. New sandboxes can\n   * then be created from this snapshot using {@link Sandbox.createFromSnapshot}.\n   *\n   * Note: this sandbox will be stopped as part of the snapshot creation process.\n   *\n   * @param opts - Optional parameters.\n   * @param opts.expiration - Optional expiration time in milliseconds. Use 0 for no expiration at all.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A promise that resolves to the Snapshot instance\n   */\n  async snapshot(opts?: {\n    expiration?: number;\n    signal?: AbortSignal;\n  }): Promise<Snapshot> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const response = await client.createSnapshot({\n      sandboxId: this.sandbox.id,\n      expiration: opts?.expiration,\n      signal: opts?.signal,\n    });\n\n    this.sandbox = toSandboxSnapshot(response.json.sandbox);\n\n    return new Snapshot({\n      client,\n      snapshot: response.json.snapshot,\n    });\n  }\n}\n\n/**\n * A {@link Sandbox} that can automatically be disposed using a `await using` statement.\n *\n * @example\n * {\n *   await using const sandbox = await Sandbox.create();\n * }\n * // Sandbox is automatically stopped here\n */\nclass DisposableSandbox extends Sandbox implements AsyncDisposable {\n  async [Symbol.asyncDispose]() {\n    await this.stop();\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"sandbox.cjs","names":["getCredentials","APIClient","WORKFLOW_SERIALIZE","WORKFLOW_DESERIALIZE","getPrivateParams","toSandboxSnapshot","FileSystem","Command","params: RunCommandParams","command","CommandFinished","path","consumeReadable","Snapshot"],"sources":["../src/sandbox.ts"],"sourcesContent":["import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from \"@workflow/serde\";\nimport { createWriteStream } from \"fs\";\nimport { mkdir } from \"fs/promises\";\nimport { dirname, resolve } from \"path\";\nimport type { Writable } from \"stream\";\nimport { pipeline } from \"stream/promises\";\nimport type { WithFetchOptions } from \"./api-client/api-client.js\";\nimport type { SandboxMetaData, SandboxRouteData } from \"./api-client/index.js\";\nimport { APIClient } from \"./api-client/index.js\";\nimport { Command, CommandFinished } from \"./command.js\";\nimport type { RUNTIMES } from \"./constants.js\";\nimport type {\n  NetworkPolicy,\n  NetworkPolicyRule,\n  NetworkTransformer,\n} from \"./network-policy.js\";\nimport { Snapshot } from \"./snapshot.js\";\nimport { consumeReadable } from \"./utils/consume-readable.js\";\nimport { type Credentials, getCredentials } from \"./utils/get-credentials.js\";\nimport {\n  type SandboxSnapshot,\n  toSandboxSnapshot,\n} from \"./utils/sandbox-snapshot.js\";\nimport { getPrivateParams, type WithPrivate } from \"./utils/types.js\";\nimport { FileSystem } from \"./filesystem.js\";\n\nexport type { NetworkPolicy, NetworkPolicyRule, NetworkTransformer };\n\n/** @inline */\nexport interface BaseCreateSandboxParams {\n  /**\n   * The source of the sandbox.\n   *\n   * Omit this parameter start a sandbox without a source.\n   *\n   * For git sources:\n   * - `depth`: Creates shallow clones with limited commit history (minimum: 1)\n   * - `revision`: Clones and checks out a specific commit, branch, or tag\n   */\n  source?:\n    | {\n        type: \"git\";\n        url: string;\n        depth?: number;\n        revision?: string;\n      }\n    | {\n        type: \"git\";\n        url: string;\n        username: string;\n        password: string;\n        depth?: number;\n        revision?: string;\n      }\n    | { type: \"tarball\"; url: string };\n  /**\n   * Array of port numbers to expose from the sandbox. Sandboxes can\n   * expose up to 4 ports.\n   */\n  ports?: number[];\n  /**\n   * Timeout in milliseconds before the sandbox auto-terminates.\n   */\n  timeout?: number;\n  /**\n   * Resources to allocate to the sandbox.\n   *\n   * Your sandbox will get the amount of vCPUs you specify here and\n   * 2048 MB of memory per vCPU.\n   */\n  resources?: { vcpus: number };\n\n  /**\n   * The runtime of the sandbox, currently only `node24`, `node22` and `python3.13` are supported.\n   * If not specified, the default runtime `node24` will be used.\n   */\n  runtime?: RUNTIMES | (string & {});\n\n  /**\n   * Network policy to define network restrictions for the sandbox.\n   * Defaults to full internet access if not specified.\n   */\n  networkPolicy?: NetworkPolicy;\n\n  /**\n   * Default environment variables for the sandbox.\n   * These are inherited by all commands unless overridden with\n   * the `env` option in `runCommand`.\n   *\n   * @example\n   * const sandbox = await Sandbox.create({\n   *   env: { NODE_ENV: \"production\", API_KEY: \"secret\" },\n   * });\n   * // All commands will have NODE_ENV and API_KEY set\n   * await sandbox.runCommand(\"node\", [\"app.js\"]);\n   */\n  env?: Record<string, string>;\n\n  /**\n   * An AbortSignal to cancel sandbox creation.\n   */\n  signal?: AbortSignal;\n}\n\nexport type CreateSandboxParams =\n  | BaseCreateSandboxParams\n  | (Omit<BaseCreateSandboxParams, \"runtime\" | \"source\"> & {\n      source: { type: \"snapshot\"; snapshotId: string };\n    });\n\n/** @inline */\ninterface GetSandboxParams {\n  /**\n   * Unique identifier of the sandbox.\n   */\n  sandboxId: string;\n  /**\n   * An AbortSignal to cancel the operation.\n   */\n  signal?: AbortSignal;\n}\n\n/**\n * Serialized representation of a Sandbox for @workflow/serde.\n */\nexport interface SerializedSandbox {\n  metadata: SandboxSnapshot;\n  routes: SandboxRouteData[];\n}\n\n/** @inline */\ninterface RunCommandParams {\n  /**\n   * The command to execute\n   */\n  cmd: string;\n  /**\n   * Arguments to pass to the command\n   */\n  args?: string[];\n  /**\n   * Working directory to execute the command in\n   */\n  cwd?: string;\n  /**\n   * Environment variables to set for this command\n   */\n  env?: Record<string, string>;\n  /**\n   * If true, execute this command with root privileges. Defaults to false.\n   */\n  sudo?: boolean;\n  /**\n   * If true, the command will return without waiting for `exitCode`\n   */\n  detached?: boolean;\n  /**\n   * A `Writable` stream where `stdout` from the command will be piped\n   */\n  stdout?: Writable;\n  /**\n   * A `Writable` stream where `stderr` from the command will be piped\n   */\n  stderr?: Writable;\n  /**\n   * An AbortSignal to cancel the command execution\n   */\n  signal?: AbortSignal;\n}\n\n// ============================================================================\n// Sandbox class\n// ============================================================================\n\n/**\n * A Sandbox is an isolated Linux MicroVM to run commands in.\n *\n * Use {@link Sandbox.create} or {@link Sandbox.get} to construct.\n * @hideconstructor\n */\nexport class Sandbox {\n  private _client: APIClient | null = null;\n\n  /**\n   * Lazily resolve credentials and construct an API client.\n   * This is used in step contexts where the Sandbox was deserialized\n   * without a client (e.g. when crossing workflow/step boundaries).\n   * Uses getCredentials() which resolves from OIDC or env vars.\n   * @internal\n   */\n  private async ensureClient(): Promise<APIClient> {\n    \"use step\";\n    if (this._client) return this._client;\n    const credentials = await getCredentials();\n    this._client = new APIClient({\n      teamId: credentials.teamId,\n      token: credentials.token,\n    });\n    return this._client;\n  }\n\n  /**\n   * Routes from ports to subdomains.\n  /* @hidden\n   */\n  public readonly routes: SandboxRouteData[];\n\n  /**\n   * A `node:fs/promises`-compatible API for interacting with the sandbox filesystem.\n   *\n   * @example\n   * const content = await sandbox.fs.readFile('/etc/hostname', 'utf8');\n   * await sandbox.fs.writeFile('/tmp/hello.txt', 'Hello, world!');\n   * const files = await sandbox.fs.readdir('/tmp');\n   * const stats = await sandbox.fs.stat('/tmp/hello.txt');\n   */\n  public readonly fs: FileSystem;\n\n  /**\n   * Unique ID of this sandbox.\n   */\n  public get sandboxId(): string {\n    return this.sandbox.id;\n  }\n\n  public get interactivePort(): number | undefined {\n    return this.sandbox.interactivePort ?? undefined;\n  }\n\n  /**\n   * The status of the sandbox.\n   */\n  public get status(): SandboxMetaData[\"status\"] {\n    return this.sandbox.status;\n  }\n\n  /**\n   * The creation date of the sandbox.\n   */\n  public get createdAt(): Date {\n    return new Date(this.sandbox.createdAt);\n  }\n\n  /**\n   * The timeout of the sandbox in milliseconds.\n   */\n  public get timeout(): number {\n    return this.sandbox.timeout;\n  }\n\n  /**\n   * The network policy of the sandbox.\n   */\n  public get networkPolicy(): NetworkPolicy | undefined {\n    return this.sandbox.networkPolicy;\n  }\n\n  /**\n   * If the sandbox was created from a snapshot, the ID of that snapshot.\n   */\n  public get sourceSnapshotId(): string | undefined {\n    return this.sandbox.sourceSnapshotId;\n  }\n\n  /**\n   * The amount of CPU used by the sandbox. Only reported once the VM is stopped.\n   */\n  public get activeCpuUsageMs(): number | undefined {\n    return this.sandbox.activeCpuDurationMs;\n  }\n\n  /**\n   * The amount of network data used by the sandbox. Only reported once the VM is stopped.\n   */\n  public get networkTransfer():\n    | { ingress: number; egress: number }\n    | undefined {\n    return this.sandbox.networkTransfer;\n  }\n\n  /**\n   * Internal metadata about this sandbox.\n   */\n  private sandbox: SandboxSnapshot;\n\n  /**\n   * Allow to get a list of sandboxes for a team narrowed to the given params.\n   * It returns both the sandboxes and the pagination metadata to allow getting\n   * the next page of results.\n   */\n  static async list(\n    params?: Partial<Parameters<APIClient[\"listSandboxes\"]>[0]> &\n      Partial<Credentials> &\n      WithFetchOptions,\n  ) {\n    \"use step\";\n    const credentials = await getCredentials(params);\n    const client = new APIClient({\n      teamId: credentials.teamId,\n      token: credentials.token,\n      fetch: params?.fetch,\n    });\n    return client.listSandboxes({\n      ...credentials,\n      ...params,\n    });\n  }\n\n  /**\n   * Serialize a Sandbox instance to plain data for @workflow/serde.\n   *\n   * @param instance - The Sandbox instance to serialize\n   * @returns A plain object containing sandbox metadata and routes\n   */\n  static [WORKFLOW_SERIALIZE](instance: Sandbox): SerializedSandbox {\n    return {\n      metadata: instance.sandbox,\n      routes: instance.routes,\n    };\n  }\n\n  /**\n   * Deserialize a Sandbox from serialized snapshot data.\n   *\n   * The deserialized instance uses the serialized metadata synchronously and\n   * lazily creates an API client only when methods perform API requests.\n   *\n   * @param data - The serialized sandbox data\n   * @returns The reconstructed Sandbox instance\n   */\n  static [WORKFLOW_DESERIALIZE](data: SerializedSandbox): Sandbox {\n    return new Sandbox({\n      sandbox: data.metadata,\n      routes: data.routes,\n    });\n  }\n\n  /**\n   * Create a new sandbox.\n   *\n   * @param params - Creation parameters and optional credentials.\n   * @returns A promise resolving to the created {@link Sandbox}.\n   * @example\n   * <caption>Create a sandbox and drop it in the end of the block</caption>\n   * async function fn() {\n   *   await using const sandbox = await Sandbox.create();\n   *   // Sandbox automatically stopped at the end of the lexical scope\n   * }\n   */\n  static async create(\n    params?: WithPrivate<\n      CreateSandboxParams | (CreateSandboxParams & Credentials)\n    > &\n      WithFetchOptions,\n  ): Promise<Sandbox & AsyncDisposable> {\n    \"use step\";\n    const credentials = await getCredentials(params);\n    const client = new APIClient({\n      teamId: credentials.teamId,\n      token: credentials.token,\n      fetch: params?.fetch,\n    });\n\n    const privateParams = getPrivateParams(params);\n    const sandbox = await client.createSandbox({\n      source: params?.source,\n      projectId: credentials.projectId,\n      ports: params?.ports ?? [],\n      timeout: params?.timeout,\n      resources: params?.resources,\n      runtime: params && \"runtime\" in params ? params?.runtime : undefined,\n      networkPolicy: params?.networkPolicy,\n      env: params?.env,\n      signal: params?.signal,\n      ...privateParams,\n    });\n\n    return new DisposableSandbox({\n      client,\n      sandbox: toSandboxSnapshot(sandbox.json.sandbox),\n      routes: sandbox.json.routes,\n    });\n  }\n\n  /**\n   * Retrieve an existing sandbox.\n   *\n   * @param params - Get parameters and optional credentials.\n   * @returns A promise resolving to the {@link Sandbox}.\n   */\n  static async get(\n    params: WithPrivate<GetSandboxParams | (GetSandboxParams & Credentials)> &\n      WithFetchOptions,\n  ): Promise<Sandbox> {\n    \"use step\";\n    const credentials = await getCredentials(params);\n    const client = new APIClient({\n      teamId: credentials.teamId,\n      token: credentials.token,\n      fetch: params.fetch,\n    });\n\n    const privateParams = getPrivateParams(params);\n    const sandbox = await client.getSandbox({\n      sandboxId: params.sandboxId,\n      signal: params.signal,\n      ...privateParams,\n    });\n\n    return new Sandbox({\n      client,\n      sandbox: toSandboxSnapshot(sandbox.json.sandbox),\n      routes: sandbox.json.routes,\n    });\n  }\n\n  /**\n   * Create a new Sandbox instance.\n   *\n   * @param params.client - Optional API client. If not provided, will be lazily created using global credentials.\n   * @param params.routes - Port-to-subdomain mappings for exposed ports\n   * @param params.sandbox - Sandbox snapshot metadata\n   */\n  constructor({\n    client,\n    routes,\n    sandbox,\n  }: {\n    client?: APIClient;\n    routes: SandboxRouteData[];\n    sandbox: SandboxSnapshot;\n  }) {\n    this._client = client ?? null;\n    this.routes = routes;\n    this.sandbox = sandbox;\n    this.fs = new FileSystem(this);\n  }\n\n  /**\n   * Get a previously run command by its ID.\n   *\n   * @param cmdId - ID of the command to retrieve\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A {@link Command} instance representing the command\n   */\n  async getCommand(\n    cmdId: string,\n    opts?: { signal?: AbortSignal },\n  ): Promise<Command> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const command = await client.getCommand({\n      sandboxId: this.sandbox.id,\n      cmdId,\n      signal: opts?.signal,\n    });\n\n    return new Command({\n      client,\n      sandboxId: this.sandbox.id,\n      cmd: command.json.command,\n    });\n  }\n\n  /**\n   * Start executing a command in this sandbox.\n   *\n   * @param command - The command to execute.\n   * @param args - Arguments to pass to the command.\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the command execution.\n   * @returns A {@link CommandFinished} result once execution is done.\n   */\n  async runCommand(\n    command: string,\n    args?: string[],\n    opts?: { signal?: AbortSignal },\n  ): Promise<CommandFinished>;\n\n  /**\n   * Start executing a command in detached mode.\n   *\n   * @param params - The command parameters.\n   * @returns A {@link Command} instance for the running command.\n   */\n  async runCommand(\n    params: RunCommandParams & { detached: true },\n  ): Promise<Command>;\n\n  /**\n   * Start executing a command in this sandbox.\n   *\n   * @param params - The command parameters.\n   * @returns A {@link CommandFinished} result once execution is done.\n   */\n  async runCommand(params: RunCommandParams): Promise<CommandFinished>;\n\n  async runCommand(\n    commandOrParams: string | RunCommandParams,\n    args?: string[],\n    opts?: { signal?: AbortSignal },\n  ): Promise<Command | CommandFinished> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const params: RunCommandParams =\n      typeof commandOrParams === \"string\"\n        ? { cmd: commandOrParams, args, signal: opts?.signal }\n        : commandOrParams;\n\n    const wait = params.detached ? false : true;\n    const pipeLogs = async (command: Command): Promise<void> => {\n      if (!params.stdout && !params.stderr) {\n        return;\n      }\n\n      try {\n        for await (const log of command.logs({ signal: params.signal })) {\n          if (log.stream === \"stdout\") {\n            params.stdout?.write(log.data);\n          } else if (log.stream === \"stderr\") {\n            params.stderr?.write(log.data);\n          }\n        }\n      } catch (err) {\n        if (params.signal?.aborted) {\n          return;\n        }\n        throw err;\n      }\n    };\n\n    if (wait) {\n      const commandStream = await client.runCommand({\n        sandboxId: this.sandbox.id,\n        command: params.cmd,\n        args: params.args ?? [],\n        cwd: params.cwd,\n        env: params.env ?? {},\n        sudo: params.sudo ?? false,\n        wait: true,\n        signal: params.signal,\n      });\n\n      const command = new Command({\n        client,\n        sandboxId: this.sandbox.id,\n        cmd: commandStream.command,\n      });\n\n      const [finished] = await Promise.all([\n        commandStream.finished,\n        pipeLogs(command),\n      ]);\n      return new CommandFinished({\n        client,\n        sandboxId: this.sandbox.id,\n        cmd: finished,\n        exitCode: finished.exitCode ?? 0,\n      });\n    }\n\n    const commandResponse = await client.runCommand({\n      sandboxId: this.sandbox.id,\n      command: params.cmd,\n      args: params.args ?? [],\n      cwd: params.cwd,\n      env: params.env ?? {},\n      sudo: params.sudo ?? false,\n      signal: params.signal,\n    });\n\n    const command = new Command({\n      client,\n      sandboxId: this.sandbox.id,\n      cmd: commandResponse.json.command,\n    });\n\n    void pipeLogs(command).catch((err) => {\n      if (params.signal?.aborted) {\n        return;\n      }\n      (params.stderr ?? params.stdout)?.emit(\"error\", err);\n    });\n\n    return command;\n  }\n\n  /**\n   * Create a directory in the filesystem of this sandbox.\n   *\n   * @param path - Path of the directory to create\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   */\n  async mkDir(path: string, opts?: { signal?: AbortSignal }): Promise<void> {\n    \"use step\";\n    const client = await this.ensureClient();\n    await client.mkDir({\n      sandboxId: this.sandbox.id,\n      path: path,\n      signal: opts?.signal,\n    });\n  }\n\n  /**\n   * Read a file from the filesystem of this sandbox as a stream.\n   *\n   * @param file - File to read, with path and optional cwd\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A promise that resolves to a ReadableStream containing the file contents, or null if file not found\n   */\n  async readFile(\n    file: { path: string; cwd?: string },\n    opts?: { signal?: AbortSignal },\n  ): Promise<NodeJS.ReadableStream | null> {\n    \"use step\";\n    const client = await this.ensureClient();\n    return client.readFile({\n      sandboxId: this.sandbox.id,\n      path: file.path,\n      cwd: file.cwd,\n      signal: opts?.signal,\n    });\n  }\n\n  /**\n   * Read a file from the filesystem of this sandbox as a Buffer.\n   *\n   * @param file - File to read, with path and optional cwd\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A promise that resolves to the file contents as a Buffer, or null if file not found\n   */\n  async readFileToBuffer(\n    file: { path: string; cwd?: string },\n    opts?: { signal?: AbortSignal },\n  ): Promise<Buffer | null> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const stream = await client.readFile({\n      sandboxId: this.sandbox.id,\n      path: file.path,\n      cwd: file.cwd,\n      signal: opts?.signal,\n    });\n\n    if (stream === null) {\n      return null;\n    }\n\n    return consumeReadable(stream);\n  }\n\n  /**\n   * Download a file from the sandbox to the local filesystem.\n   *\n   * @param src - Source file on the sandbox, with path and optional cwd\n   * @param dst - Destination file on the local machine, with path and optional cwd\n   * @param opts - Optional parameters.\n   * @param opts.mkdirRecursive - If true, create parent directories for the destination if they don't exist.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns The absolute path to the written file, or null if the source file was not found\n   */\n  async downloadFile(\n    src: { path: string; cwd?: string },\n    dst: { path: string; cwd?: string },\n    opts?: { mkdirRecursive?: boolean; signal?: AbortSignal },\n  ): Promise<string | null> {\n    \"use step\";\n    const client = await this.ensureClient();\n    if (!src?.path) {\n      throw new Error(\"downloadFile: source path is required\");\n    }\n\n    if (!dst?.path) {\n      throw new Error(\"downloadFile: destination path is required\");\n    }\n\n    const stream = await client.readFile({\n      sandboxId: this.sandbox.id,\n      path: src.path,\n      cwd: src.cwd,\n      signal: opts?.signal,\n    });\n\n    if (stream === null) {\n      return null;\n    }\n\n    try {\n      const dstPath = resolve(dst.cwd ?? \"\", dst.path);\n      if (opts?.mkdirRecursive) {\n        await mkdir(dirname(dstPath), { recursive: true });\n      }\n      await pipeline(stream, createWriteStream(dstPath), {\n        signal: opts?.signal,\n      });\n      return dstPath;\n    } finally {\n      stream.destroy();\n    }\n  }\n\n  /**\n   * Write files to the filesystem of this sandbox.\n   * Defaults to writing to /vercel/sandbox unless an absolute path is specified.\n   * Writes files using the `vercel-sandbox` user.\n   *\n   * @param files - Array of files with path, content, and optional mode (permissions)\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A promise that resolves when the files are written\n   *\n   * @example\n   * // Write an executable script\n   * await sandbox.writeFiles([\n   *   { path: \"/usr/local/bin/myscript\", content: \"#!/bin/bash\\necho hello\", mode: 0o755 }\n   * ]);\n   */\n  async writeFiles(\n    files: {\n      path: string;\n      content: string | Uint8Array;\n      mode?: number;\n    }[],\n    opts?: { signal?: AbortSignal },\n  ) {\n    \"use step\";\n    const client = await this.ensureClient();\n    return client.writeFiles({\n      sandboxId: this.sandbox.id,\n      cwd: this.sandbox.cwd,\n      extractDir: \"/\",\n      files: files,\n      signal: opts?.signal,\n    });\n  }\n\n  /**\n   * Get the public domain of a port of this sandbox.\n   *\n   * @param p - Port number to resolve\n   * @returns A full domain (e.g. `https://subdomain.vercel.run`)\n   * @throws If the port has no associated route\n   */\n  domain(p: number): string {\n    const route = this.routes.find(({ port }) => port == p);\n    if (route) {\n      return `https://${route.subdomain}.vercel.run`;\n    } else {\n      throw new Error(`No route for port ${p}`);\n    }\n  }\n\n  /**\n   * Stop the sandbox.\n   *\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @param opts.blocking - If true, poll until the sandbox has fully stopped and return the final state.\n   * @returns The sandbox metadata at the time the stop was acknowledged, or after fully stopped if `blocking` is true.\n   */\n  async stop(opts?: {\n    signal?: AbortSignal;\n    blocking?: boolean;\n  }): Promise<SandboxSnapshot> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const response = await client.stopSandbox({\n      sandboxId: this.sandbox.id,\n      signal: opts?.signal,\n      blocking: opts?.blocking,\n    });\n    this.sandbox = toSandboxSnapshot(response.json.sandbox);\n    return this.sandbox;\n  }\n\n  /**\n   * Update the network policy for this sandbox.\n   *\n   * @param networkPolicy - The new network policy to apply.\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A promise that resolves when the network policy is updated.\n   *\n   * @example\n   * // Restrict to specific domains\n   * await sandbox.updateNetworkPolicy({\n   *   allow: [\"*.npmjs.org\", \"github.com\"],\n   * });\n   *\n   * @example\n   * // Inject credentials with per-domain transformers\n   * await sandbox.updateNetworkPolicy({\n   *   allow: {\n   *     \"ai-gateway.vercel.sh\": [{\n   *       transform: [{\n   *         headers: { authorization: \"Bearer ...\" }\n   *       }]\n   *     }],\n   *     \"*\": []\n   *   }\n   * });\n   *\n   * @example\n   * // Deny all network access\n   * await sandbox.updateNetworkPolicy(\"deny-all\");\n   */\n  async updateNetworkPolicy(\n    networkPolicy: NetworkPolicy,\n    opts?: { signal?: AbortSignal },\n  ): Promise<NetworkPolicy> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const response = await client.updateNetworkPolicy({\n      sandboxId: this.sandbox.id,\n      networkPolicy: networkPolicy,\n      signal: opts?.signal,\n    });\n\n    // Update the internal sandbox metadata with the new timeout value\n    this.sandbox = toSandboxSnapshot(response.json.sandbox);\n    return this.sandbox.networkPolicy!;\n  }\n\n  /**\n   * Extend the timeout of the sandbox by the specified duration.\n   *\n   * This allows you to extend the lifetime of a sandbox up until the maximum\n   * execution timeout for your plan.\n   *\n   * @param duration - The duration in milliseconds to extend the timeout by\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A promise that resolves when the timeout is extended\n   *\n   * @example\n   * const sandbox = await Sandbox.create({ timeout: ms('10m') });\n   * // Extends timeout by 5 minutes, to a total of 15 minutes.\n   * await sandbox.extendTimeout(ms('5m'));\n   */\n  async extendTimeout(\n    duration: number,\n    opts?: { signal?: AbortSignal },\n  ): Promise<void> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const response = await client.extendTimeout({\n      sandboxId: this.sandbox.id,\n      duration,\n      signal: opts?.signal,\n    });\n\n    // Update the internal sandbox metadata with the new timeout value\n    this.sandbox = toSandboxSnapshot(response.json.sandbox);\n  }\n\n  /**\n   * Create a snapshot from this currently running sandbox. New sandboxes can\n   * then be created from this snapshot using {@link Sandbox.createFromSnapshot}.\n   *\n   * Note: this sandbox will be stopped as part of the snapshot creation process.\n   *\n   * @param opts - Optional parameters.\n   * @param opts.expiration - Optional expiration time in milliseconds. Use 0 for no expiration at all.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A promise that resolves to the Snapshot instance\n   */\n  async snapshot(opts?: {\n    expiration?: number;\n    signal?: AbortSignal;\n  }): Promise<Snapshot> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const response = await client.createSnapshot({\n      sandboxId: this.sandbox.id,\n      expiration: opts?.expiration,\n      signal: opts?.signal,\n    });\n\n    this.sandbox = toSandboxSnapshot(response.json.sandbox);\n\n    return new Snapshot({\n      client,\n      snapshot: response.json.snapshot,\n    });\n  }\n}\n\n/**\n * A {@link Sandbox} that can automatically be disposed using a `await using` statement.\n *\n * @example\n * {\n *   await using const sandbox = await Sandbox.create();\n * }\n * // Sandbox is automatically stopped here\n */\nclass DisposableSandbox extends Sandbox implements AsyncDisposable {\n  async [Symbol.asyncDispose]() {\n    await this.stop();\n  }\n}\n"],"mappings":"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"}

package/dist/sandbox.d.cts

@@ -8,6 +8,7 @@ import { Command, CommandFinished } from "./command.cjs";
 import { Credentials } from "./utils/get-credentials.cjs";
 import { Snapshot } from "./snapshot.cjs";
 import { SandboxSnapshot } from "./utils/sandbox-snapshot.cjs";
+import { FileSystem } from "./filesystem.cjs";
 import * as zod0 from "zod";
 import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from "@workflow/serde";
 import { Writable } from "stream";
@@ -170,6 +171,16 @@ declare class Sandbox {
   /* @hidden
    */
   readonly routes: SandboxRouteData[];
+  /**
+   * A `node:fs/promises`-compatible API for interacting with the sandbox filesystem.
+   *
+   * @example
+   * const content = await sandbox.fs.readFile('/etc/hostname', 'utf8');
+   * await sandbox.fs.writeFile('/tmp/hello.txt', 'Hello, world!');
+   * const files = await sandbox.fs.readdir('/tmp');
+   * const stats = await sandbox.fs.stat('/tmp/hello.txt');
+   */
+  readonly fs: FileSystem;
   /**
    * Unique ID of this sandbox.
    */

package/dist/sandbox.d.ts

@@ -9,6 +9,7 @@ import { Command, CommandFinished } from "./command.js";
 import { Credentials } from "./utils/get-credentials.js";
 import { Snapshot } from "./snapshot.js";
 import { SandboxSnapshot } from "./utils/sandbox-snapshot.js";
+import { FileSystem } from "./filesystem.js";
 import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from "@workflow/serde";
 import * as zod0 from "zod";
 import { Writable } from "stream";
@@ -171,6 +172,16 @@ declare class Sandbox {
   /* @hidden
    */
   readonly routes: SandboxRouteData[];
+  /**
+   * A `node:fs/promises`-compatible API for interacting with the sandbox filesystem.
+   *
+   * @example
+   * const content = await sandbox.fs.readFile('/etc/hostname', 'utf8');
+   * await sandbox.fs.writeFile('/tmp/hello.txt', 'Hello, world!');
+   * const files = await sandbox.fs.readdir('/tmp');
+   * const stats = await sandbox.fs.stat('/tmp/hello.txt');
+   */
+  readonly fs: FileSystem;
   /**
    * Unique ID of this sandbox.
    */

package/dist/sandbox.js

@@ -6,6 +6,7 @@ import { getCredentials } from "./utils/get-credentials.js";
 import { Command, CommandFinished } from "./command.js";
 import { Snapshot } from "./snapshot.js";
 import { toSandboxSnapshot } from "./utils/sandbox-snapshot.js";
+import { FileSystem } from "./filesystem.js";
 import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from "@workflow/serde";
 import { createWriteStream } from "fs";
 import { mkdir } from "fs/promises";
@@ -209,6 +210,7 @@ var Sandbox = class Sandbox {
 		this._client = client ?? null;
 		this.routes = routes;
 		this.sandbox = sandbox;
+		this.fs = new FileSystem(this);
 	}
 	/**
 	* Get a previously run command by its ID.

package/dist/sandbox.js.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox.js","names":["params: RunCommandParams","command","path"],"sources":["../src/sandbox.ts"],"sourcesContent":["import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from \"@workflow/serde\";\nimport { createWriteStream } from \"fs\";\nimport { mkdir } from \"fs/promises\";\nimport { dirname, resolve } from \"path\";\nimport type { Writable } from \"stream\";\nimport { pipeline } from \"stream/promises\";\nimport type { WithFetchOptions } from \"./api-client/api-client.js\";\nimport type { SandboxMetaData, SandboxRouteData } from \"./api-client/index.js\";\nimport { APIClient } from \"./api-client/index.js\";\nimport { Command, CommandFinished } from \"./command.js\";\nimport type { RUNTIMES } from \"./constants.js\";\nimport type {\n  NetworkPolicy,\n  NetworkPolicyRule,\n  NetworkTransformer,\n} from \"./network-policy.js\";\nimport { Snapshot } from \"./snapshot.js\";\nimport { consumeReadable } from \"./utils/consume-readable.js\";\nimport { type Credentials, getCredentials } from \"./utils/get-credentials.js\";\nimport {\n  type SandboxSnapshot,\n  toSandboxSnapshot,\n} from \"./utils/sandbox-snapshot.js\";\nimport { getPrivateParams, type WithPrivate } from \"./utils/types.js\";\n\nexport type { NetworkPolicy, NetworkPolicyRule, NetworkTransformer };\n\n/** @inline */\nexport interface BaseCreateSandboxParams {\n  /**\n   * The source of the sandbox.\n   *\n   * Omit this parameter start a sandbox without a source.\n   *\n   * For git sources:\n   * - `depth`: Creates shallow clones with limited commit history (minimum: 1)\n   * - `revision`: Clones and checks out a specific commit, branch, or tag\n   */\n  source?:\n    | {\n        type: \"git\";\n        url: string;\n        depth?: number;\n        revision?: string;\n      }\n    | {\n        type: \"git\";\n        url: string;\n        username: string;\n        password: string;\n        depth?: number;\n        revision?: string;\n      }\n    | { type: \"tarball\"; url: string };\n  /**\n   * Array of port numbers to expose from the sandbox. Sandboxes can\n   * expose up to 4 ports.\n   */\n  ports?: number[];\n  /**\n   * Timeout in milliseconds before the sandbox auto-terminates.\n   */\n  timeout?: number;\n  /**\n   * Resources to allocate to the sandbox.\n   *\n   * Your sandbox will get the amount of vCPUs you specify here and\n   * 2048 MB of memory per vCPU.\n   */\n  resources?: { vcpus: number };\n\n  /**\n   * The runtime of the sandbox, currently only `node24`, `node22` and `python3.13` are supported.\n   * If not specified, the default runtime `node24` will be used.\n   */\n  runtime?: RUNTIMES | (string & {});\n\n  /**\n   * Network policy to define network restrictions for the sandbox.\n   * Defaults to full internet access if not specified.\n   */\n  networkPolicy?: NetworkPolicy;\n\n  /**\n   * Default environment variables for the sandbox.\n   * These are inherited by all commands unless overridden with\n   * the `env` option in `runCommand`.\n   *\n   * @example\n   * const sandbox = await Sandbox.create({\n   *   env: { NODE_ENV: \"production\", API_KEY: \"secret\" },\n   * });\n   * // All commands will have NODE_ENV and API_KEY set\n   * await sandbox.runCommand(\"node\", [\"app.js\"]);\n   */\n  env?: Record<string, string>;\n\n  /**\n   * An AbortSignal to cancel sandbox creation.\n   */\n  signal?: AbortSignal;\n}\n\nexport type CreateSandboxParams =\n  | BaseCreateSandboxParams\n  | (Omit<BaseCreateSandboxParams, \"runtime\" | \"source\"> & {\n      source: { type: \"snapshot\"; snapshotId: string };\n    });\n\n/** @inline */\ninterface GetSandboxParams {\n  /**\n   * Unique identifier of the sandbox.\n   */\n  sandboxId: string;\n  /**\n   * An AbortSignal to cancel the operation.\n   */\n  signal?: AbortSignal;\n}\n\n/**\n * Serialized representation of a Sandbox for @workflow/serde.\n */\nexport interface SerializedSandbox {\n  metadata: SandboxSnapshot;\n  routes: SandboxRouteData[];\n}\n\n/** @inline */\ninterface RunCommandParams {\n  /**\n   * The command to execute\n   */\n  cmd: string;\n  /**\n   * Arguments to pass to the command\n   */\n  args?: string[];\n  /**\n   * Working directory to execute the command in\n   */\n  cwd?: string;\n  /**\n   * Environment variables to set for this command\n   */\n  env?: Record<string, string>;\n  /**\n   * If true, execute this command with root privileges. Defaults to false.\n   */\n  sudo?: boolean;\n  /**\n   * If true, the command will return without waiting for `exitCode`\n   */\n  detached?: boolean;\n  /**\n   * A `Writable` stream where `stdout` from the command will be piped\n   */\n  stdout?: Writable;\n  /**\n   * A `Writable` stream where `stderr` from the command will be piped\n   */\n  stderr?: Writable;\n  /**\n   * An AbortSignal to cancel the command execution\n   */\n  signal?: AbortSignal;\n}\n\n// ============================================================================\n// Sandbox class\n// ============================================================================\n\n/**\n * A Sandbox is an isolated Linux MicroVM to run commands in.\n *\n * Use {@link Sandbox.create} or {@link Sandbox.get} to construct.\n * @hideconstructor\n */\nexport class Sandbox {\n  private _client: APIClient | null = null;\n\n  /**\n   * Lazily resolve credentials and construct an API client.\n   * This is used in step contexts where the Sandbox was deserialized\n   * without a client (e.g. when crossing workflow/step boundaries).\n   * Uses getCredentials() which resolves from OIDC or env vars.\n   * @internal\n   */\n  private async ensureClient(): Promise<APIClient> {\n    \"use step\";\n    if (this._client) return this._client;\n    const credentials = await getCredentials();\n    this._client = new APIClient({\n      teamId: credentials.teamId,\n      token: credentials.token,\n    });\n    return this._client;\n  }\n\n  /**\n   * Routes from ports to subdomains.\n  /* @hidden\n   */\n  public readonly routes: SandboxRouteData[];\n\n  /**\n   * Unique ID of this sandbox.\n   */\n  public get sandboxId(): string {\n    return this.sandbox.id;\n  }\n\n  public get interactivePort(): number | undefined {\n    return this.sandbox.interactivePort ?? undefined;\n  }\n\n  /**\n   * The status of the sandbox.\n   */\n  public get status(): SandboxMetaData[\"status\"] {\n    return this.sandbox.status;\n  }\n\n  /**\n   * The creation date of the sandbox.\n   */\n  public get createdAt(): Date {\n    return new Date(this.sandbox.createdAt);\n  }\n\n  /**\n   * The timeout of the sandbox in milliseconds.\n   */\n  public get timeout(): number {\n    return this.sandbox.timeout;\n  }\n\n  /**\n   * The network policy of the sandbox.\n   */\n  public get networkPolicy(): NetworkPolicy | undefined {\n    return this.sandbox.networkPolicy;\n  }\n\n  /**\n   * If the sandbox was created from a snapshot, the ID of that snapshot.\n   */\n  public get sourceSnapshotId(): string | undefined {\n    return this.sandbox.sourceSnapshotId;\n  }\n\n  /**\n   * The amount of CPU used by the sandbox. Only reported once the VM is stopped.\n   */\n  public get activeCpuUsageMs(): number | undefined {\n    return this.sandbox.activeCpuDurationMs;\n  }\n\n  /**\n   * The amount of network data used by the sandbox. Only reported once the VM is stopped.\n   */\n  public get networkTransfer():\n    | { ingress: number; egress: number }\n    | undefined {\n    return this.sandbox.networkTransfer;\n  }\n\n  /**\n   * Internal metadata about this sandbox.\n   */\n  private sandbox: SandboxSnapshot;\n\n  /**\n   * Allow to get a list of sandboxes for a team narrowed to the given params.\n   * It returns both the sandboxes and the pagination metadata to allow getting\n   * the next page of results.\n   */\n  static async list(\n    params?: Partial<Parameters<APIClient[\"listSandboxes\"]>[0]> &\n      Partial<Credentials> &\n      WithFetchOptions,\n  ) {\n    \"use step\";\n    const credentials = await getCredentials(params);\n    const client = new APIClient({\n      teamId: credentials.teamId,\n      token: credentials.token,\n      fetch: params?.fetch,\n    });\n    return client.listSandboxes({\n      ...credentials,\n      ...params,\n    });\n  }\n\n  /**\n   * Serialize a Sandbox instance to plain data for @workflow/serde.\n   *\n   * @param instance - The Sandbox instance to serialize\n   * @returns A plain object containing sandbox metadata and routes\n   */\n  static [WORKFLOW_SERIALIZE](instance: Sandbox): SerializedSandbox {\n    return {\n      metadata: instance.sandbox,\n      routes: instance.routes,\n    };\n  }\n\n  /**\n   * Deserialize a Sandbox from serialized snapshot data.\n   *\n   * The deserialized instance uses the serialized metadata synchronously and\n   * lazily creates an API client only when methods perform API requests.\n   *\n   * @param data - The serialized sandbox data\n   * @returns The reconstructed Sandbox instance\n   */\n  static [WORKFLOW_DESERIALIZE](data: SerializedSandbox): Sandbox {\n    return new Sandbox({\n      sandbox: data.metadata,\n      routes: data.routes,\n    });\n  }\n\n  /**\n   * Create a new sandbox.\n   *\n   * @param params - Creation parameters and optional credentials.\n   * @returns A promise resolving to the created {@link Sandbox}.\n   * @example\n   * <caption>Create a sandbox and drop it in the end of the block</caption>\n   * async function fn() {\n   *   await using const sandbox = await Sandbox.create();\n   *   // Sandbox automatically stopped at the end of the lexical scope\n   * }\n   */\n  static async create(\n    params?: WithPrivate<\n      CreateSandboxParams | (CreateSandboxParams & Credentials)\n    > &\n      WithFetchOptions,\n  ): Promise<Sandbox & AsyncDisposable> {\n    \"use step\";\n    const credentials = await getCredentials(params);\n    const client = new APIClient({\n      teamId: credentials.teamId,\n      token: credentials.token,\n      fetch: params?.fetch,\n    });\n\n    const privateParams = getPrivateParams(params);\n    const sandbox = await client.createSandbox({\n      source: params?.source,\n      projectId: credentials.projectId,\n      ports: params?.ports ?? [],\n      timeout: params?.timeout,\n      resources: params?.resources,\n      runtime: params && \"runtime\" in params ? params?.runtime : undefined,\n      networkPolicy: params?.networkPolicy,\n      env: params?.env,\n      signal: params?.signal,\n      ...privateParams,\n    });\n\n    return new DisposableSandbox({\n      client,\n      sandbox: toSandboxSnapshot(sandbox.json.sandbox),\n      routes: sandbox.json.routes,\n    });\n  }\n\n  /**\n   * Retrieve an existing sandbox.\n   *\n   * @param params - Get parameters and optional credentials.\n   * @returns A promise resolving to the {@link Sandbox}.\n   */\n  static async get(\n    params: WithPrivate<GetSandboxParams | (GetSandboxParams & Credentials)> &\n      WithFetchOptions,\n  ): Promise<Sandbox> {\n    \"use step\";\n    const credentials = await getCredentials(params);\n    const client = new APIClient({\n      teamId: credentials.teamId,\n      token: credentials.token,\n      fetch: params.fetch,\n    });\n\n    const privateParams = getPrivateParams(params);\n    const sandbox = await client.getSandbox({\n      sandboxId: params.sandboxId,\n      signal: params.signal,\n      ...privateParams,\n    });\n\n    return new Sandbox({\n      client,\n      sandbox: toSandboxSnapshot(sandbox.json.sandbox),\n      routes: sandbox.json.routes,\n    });\n  }\n\n  /**\n   * Create a new Sandbox instance.\n   *\n   * @param params.client - Optional API client. If not provided, will be lazily created using global credentials.\n   * @param params.routes - Port-to-subdomain mappings for exposed ports\n   * @param params.sandbox - Sandbox snapshot metadata\n   */\n  constructor({\n    client,\n    routes,\n    sandbox,\n  }: {\n    client?: APIClient;\n    routes: SandboxRouteData[];\n    sandbox: SandboxSnapshot;\n  }) {\n    this._client = client ?? null;\n    this.routes = routes;\n    this.sandbox = sandbox;\n  }\n\n  /**\n   * Get a previously run command by its ID.\n   *\n   * @param cmdId - ID of the command to retrieve\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A {@link Command} instance representing the command\n   */\n  async getCommand(\n    cmdId: string,\n    opts?: { signal?: AbortSignal },\n  ): Promise<Command> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const command = await client.getCommand({\n      sandboxId: this.sandbox.id,\n      cmdId,\n      signal: opts?.signal,\n    });\n\n    return new Command({\n      client,\n      sandboxId: this.sandbox.id,\n      cmd: command.json.command,\n    });\n  }\n\n  /**\n   * Start executing a command in this sandbox.\n   *\n   * @param command - The command to execute.\n   * @param args - Arguments to pass to the command.\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the command execution.\n   * @returns A {@link CommandFinished} result once execution is done.\n   */\n  async runCommand(\n    command: string,\n    args?: string[],\n    opts?: { signal?: AbortSignal },\n  ): Promise<CommandFinished>;\n\n  /**\n   * Start executing a command in detached mode.\n   *\n   * @param params - The command parameters.\n   * @returns A {@link Command} instance for the running command.\n   */\n  async runCommand(\n    params: RunCommandParams & { detached: true },\n  ): Promise<Command>;\n\n  /**\n   * Start executing a command in this sandbox.\n   *\n   * @param params - The command parameters.\n   * @returns A {@link CommandFinished} result once execution is done.\n   */\n  async runCommand(params: RunCommandParams): Promise<CommandFinished>;\n\n  async runCommand(\n    commandOrParams: string | RunCommandParams,\n    args?: string[],\n    opts?: { signal?: AbortSignal },\n  ): Promise<Command | CommandFinished> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const params: RunCommandParams =\n      typeof commandOrParams === \"string\"\n        ? { cmd: commandOrParams, args, signal: opts?.signal }\n        : commandOrParams;\n\n    const wait = params.detached ? false : true;\n    const pipeLogs = async (command: Command): Promise<void> => {\n      if (!params.stdout && !params.stderr) {\n        return;\n      }\n\n      try {\n        for await (const log of command.logs({ signal: params.signal })) {\n          if (log.stream === \"stdout\") {\n            params.stdout?.write(log.data);\n          } else if (log.stream === \"stderr\") {\n            params.stderr?.write(log.data);\n          }\n        }\n      } catch (err) {\n        if (params.signal?.aborted) {\n          return;\n        }\n        throw err;\n      }\n    };\n\n    if (wait) {\n      const commandStream = await client.runCommand({\n        sandboxId: this.sandbox.id,\n        command: params.cmd,\n        args: params.args ?? [],\n        cwd: params.cwd,\n        env: params.env ?? {},\n        sudo: params.sudo ?? false,\n        wait: true,\n        signal: params.signal,\n      });\n\n      const command = new Command({\n        client,\n        sandboxId: this.sandbox.id,\n        cmd: commandStream.command,\n      });\n\n      const [finished] = await Promise.all([\n        commandStream.finished,\n        pipeLogs(command),\n      ]);\n      return new CommandFinished({\n        client,\n        sandboxId: this.sandbox.id,\n        cmd: finished,\n        exitCode: finished.exitCode ?? 0,\n      });\n    }\n\n    const commandResponse = await client.runCommand({\n      sandboxId: this.sandbox.id,\n      command: params.cmd,\n      args: params.args ?? [],\n      cwd: params.cwd,\n      env: params.env ?? {},\n      sudo: params.sudo ?? false,\n      signal: params.signal,\n    });\n\n    const command = new Command({\n      client,\n      sandboxId: this.sandbox.id,\n      cmd: commandResponse.json.command,\n    });\n\n    void pipeLogs(command).catch((err) => {\n      if (params.signal?.aborted) {\n        return;\n      }\n      (params.stderr ?? params.stdout)?.emit(\"error\", err);\n    });\n\n    return command;\n  }\n\n  /**\n   * Create a directory in the filesystem of this sandbox.\n   *\n   * @param path - Path of the directory to create\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   */\n  async mkDir(path: string, opts?: { signal?: AbortSignal }): Promise<void> {\n    \"use step\";\n    const client = await this.ensureClient();\n    await client.mkDir({\n      sandboxId: this.sandbox.id,\n      path: path,\n      signal: opts?.signal,\n    });\n  }\n\n  /**\n   * Read a file from the filesystem of this sandbox as a stream.\n   *\n   * @param file - File to read, with path and optional cwd\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A promise that resolves to a ReadableStream containing the file contents, or null if file not found\n   */\n  async readFile(\n    file: { path: string; cwd?: string },\n    opts?: { signal?: AbortSignal },\n  ): Promise<NodeJS.ReadableStream | null> {\n    \"use step\";\n    const client = await this.ensureClient();\n    return client.readFile({\n      sandboxId: this.sandbox.id,\n      path: file.path,\n      cwd: file.cwd,\n      signal: opts?.signal,\n    });\n  }\n\n  /**\n   * Read a file from the filesystem of this sandbox as a Buffer.\n   *\n   * @param file - File to read, with path and optional cwd\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A promise that resolves to the file contents as a Buffer, or null if file not found\n   */\n  async readFileToBuffer(\n    file: { path: string; cwd?: string },\n    opts?: { signal?: AbortSignal },\n  ): Promise<Buffer | null> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const stream = await client.readFile({\n      sandboxId: this.sandbox.id,\n      path: file.path,\n      cwd: file.cwd,\n      signal: opts?.signal,\n    });\n\n    if (stream === null) {\n      return null;\n    }\n\n    return consumeReadable(stream);\n  }\n\n  /**\n   * Download a file from the sandbox to the local filesystem.\n   *\n   * @param src - Source file on the sandbox, with path and optional cwd\n   * @param dst - Destination file on the local machine, with path and optional cwd\n   * @param opts - Optional parameters.\n   * @param opts.mkdirRecursive - If true, create parent directories for the destination if they don't exist.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns The absolute path to the written file, or null if the source file was not found\n   */\n  async downloadFile(\n    src: { path: string; cwd?: string },\n    dst: { path: string; cwd?: string },\n    opts?: { mkdirRecursive?: boolean; signal?: AbortSignal },\n  ): Promise<string | null> {\n    \"use step\";\n    const client = await this.ensureClient();\n    if (!src?.path) {\n      throw new Error(\"downloadFile: source path is required\");\n    }\n\n    if (!dst?.path) {\n      throw new Error(\"downloadFile: destination path is required\");\n    }\n\n    const stream = await client.readFile({\n      sandboxId: this.sandbox.id,\n      path: src.path,\n      cwd: src.cwd,\n      signal: opts?.signal,\n    });\n\n    if (stream === null) {\n      return null;\n    }\n\n    try {\n      const dstPath = resolve(dst.cwd ?? \"\", dst.path);\n      if (opts?.mkdirRecursive) {\n        await mkdir(dirname(dstPath), { recursive: true });\n      }\n      await pipeline(stream, createWriteStream(dstPath), {\n        signal: opts?.signal,\n      });\n      return dstPath;\n    } finally {\n      stream.destroy();\n    }\n  }\n\n  /**\n   * Write files to the filesystem of this sandbox.\n   * Defaults to writing to /vercel/sandbox unless an absolute path is specified.\n   * Writes files using the `vercel-sandbox` user.\n   *\n   * @param files - Array of files with path, content, and optional mode (permissions)\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A promise that resolves when the files are written\n   *\n   * @example\n   * // Write an executable script\n   * await sandbox.writeFiles([\n   *   { path: \"/usr/local/bin/myscript\", content: \"#!/bin/bash\\necho hello\", mode: 0o755 }\n   * ]);\n   */\n  async writeFiles(\n    files: {\n      path: string;\n      content: string | Uint8Array;\n      mode?: number;\n    }[],\n    opts?: { signal?: AbortSignal },\n  ) {\n    \"use step\";\n    const client = await this.ensureClient();\n    return client.writeFiles({\n      sandboxId: this.sandbox.id,\n      cwd: this.sandbox.cwd,\n      extractDir: \"/\",\n      files: files,\n      signal: opts?.signal,\n    });\n  }\n\n  /**\n   * Get the public domain of a port of this sandbox.\n   *\n   * @param p - Port number to resolve\n   * @returns A full domain (e.g. `https://subdomain.vercel.run`)\n   * @throws If the port has no associated route\n   */\n  domain(p: number): string {\n    const route = this.routes.find(({ port }) => port == p);\n    if (route) {\n      return `https://${route.subdomain}.vercel.run`;\n    } else {\n      throw new Error(`No route for port ${p}`);\n    }\n  }\n\n  /**\n   * Stop the sandbox.\n   *\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @param opts.blocking - If true, poll until the sandbox has fully stopped and return the final state.\n   * @returns The sandbox metadata at the time the stop was acknowledged, or after fully stopped if `blocking` is true.\n   */\n  async stop(opts?: {\n    signal?: AbortSignal;\n    blocking?: boolean;\n  }): Promise<SandboxSnapshot> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const response = await client.stopSandbox({\n      sandboxId: this.sandbox.id,\n      signal: opts?.signal,\n      blocking: opts?.blocking,\n    });\n    this.sandbox = toSandboxSnapshot(response.json.sandbox);\n    return this.sandbox;\n  }\n\n  /**\n   * Update the network policy for this sandbox.\n   *\n   * @param networkPolicy - The new network policy to apply.\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A promise that resolves when the network policy is updated.\n   *\n   * @example\n   * // Restrict to specific domains\n   * await sandbox.updateNetworkPolicy({\n   *   allow: [\"*.npmjs.org\", \"github.com\"],\n   * });\n   *\n   * @example\n   * // Inject credentials with per-domain transformers\n   * await sandbox.updateNetworkPolicy({\n   *   allow: {\n   *     \"ai-gateway.vercel.sh\": [{\n   *       transform: [{\n   *         headers: { authorization: \"Bearer ...\" }\n   *       }]\n   *     }],\n   *     \"*\": []\n   *   }\n   * });\n   *\n   * @example\n   * // Deny all network access\n   * await sandbox.updateNetworkPolicy(\"deny-all\");\n   */\n  async updateNetworkPolicy(\n    networkPolicy: NetworkPolicy,\n    opts?: { signal?: AbortSignal },\n  ): Promise<NetworkPolicy> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const response = await client.updateNetworkPolicy({\n      sandboxId: this.sandbox.id,\n      networkPolicy: networkPolicy,\n      signal: opts?.signal,\n    });\n\n    // Update the internal sandbox metadata with the new timeout value\n    this.sandbox = toSandboxSnapshot(response.json.sandbox);\n    return this.sandbox.networkPolicy!;\n  }\n\n  /**\n   * Extend the timeout of the sandbox by the specified duration.\n   *\n   * This allows you to extend the lifetime of a sandbox up until the maximum\n   * execution timeout for your plan.\n   *\n   * @param duration - The duration in milliseconds to extend the timeout by\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A promise that resolves when the timeout is extended\n   *\n   * @example\n   * const sandbox = await Sandbox.create({ timeout: ms('10m') });\n   * // Extends timeout by 5 minutes, to a total of 15 minutes.\n   * await sandbox.extendTimeout(ms('5m'));\n   */\n  async extendTimeout(\n    duration: number,\n    opts?: { signal?: AbortSignal },\n  ): Promise<void> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const response = await client.extendTimeout({\n      sandboxId: this.sandbox.id,\n      duration,\n      signal: opts?.signal,\n    });\n\n    // Update the internal sandbox metadata with the new timeout value\n    this.sandbox = toSandboxSnapshot(response.json.sandbox);\n  }\n\n  /**\n   * Create a snapshot from this currently running sandbox. New sandboxes can\n   * then be created from this snapshot using {@link Sandbox.createFromSnapshot}.\n   *\n   * Note: this sandbox will be stopped as part of the snapshot creation process.\n   *\n   * @param opts - Optional parameters.\n   * @param opts.expiration - Optional expiration time in milliseconds. Use 0 for no expiration at all.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A promise that resolves to the Snapshot instance\n   */\n  async snapshot(opts?: {\n    expiration?: number;\n    signal?: AbortSignal;\n  }): Promise<Snapshot> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const response = await client.createSnapshot({\n      sandboxId: this.sandbox.id,\n      expiration: opts?.expiration,\n      signal: opts?.signal,\n    });\n\n    this.sandbox = toSandboxSnapshot(response.json.sandbox);\n\n    return new Snapshot({\n      client,\n      snapshot: response.json.snapshot,\n    });\n  }\n}\n\n/**\n * A {@link Sandbox} that can automatically be disposed using a `await using` statement.\n *\n * @example\n * {\n *   await using const sandbox = await Sandbox.create();\n * }\n * // Sandbox is automatically stopped here\n */\nclass DisposableSandbox extends Sandbox implements AsyncDisposable {\n  async [Symbol.asyncDispose]() {\n    await this.stop();\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"sandbox.js","names":["params: RunCommandParams","command","path"],"sources":["../src/sandbox.ts"],"sourcesContent":["import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from \"@workflow/serde\";\nimport { createWriteStream } from \"fs\";\nimport { mkdir } from \"fs/promises\";\nimport { dirname, resolve } from \"path\";\nimport type { Writable } from \"stream\";\nimport { pipeline } from \"stream/promises\";\nimport type { WithFetchOptions } from \"./api-client/api-client.js\";\nimport type { SandboxMetaData, SandboxRouteData } from \"./api-client/index.js\";\nimport { APIClient } from \"./api-client/index.js\";\nimport { Command, CommandFinished } from \"./command.js\";\nimport type { RUNTIMES } from \"./constants.js\";\nimport type {\n  NetworkPolicy,\n  NetworkPolicyRule,\n  NetworkTransformer,\n} from \"./network-policy.js\";\nimport { Snapshot } from \"./snapshot.js\";\nimport { consumeReadable } from \"./utils/consume-readable.js\";\nimport { type Credentials, getCredentials } from \"./utils/get-credentials.js\";\nimport {\n  type SandboxSnapshot,\n  toSandboxSnapshot,\n} from \"./utils/sandbox-snapshot.js\";\nimport { getPrivateParams, type WithPrivate } from \"./utils/types.js\";\nimport { FileSystem } from \"./filesystem.js\";\n\nexport type { NetworkPolicy, NetworkPolicyRule, NetworkTransformer };\n\n/** @inline */\nexport interface BaseCreateSandboxParams {\n  /**\n   * The source of the sandbox.\n   *\n   * Omit this parameter start a sandbox without a source.\n   *\n   * For git sources:\n   * - `depth`: Creates shallow clones with limited commit history (minimum: 1)\n   * - `revision`: Clones and checks out a specific commit, branch, or tag\n   */\n  source?:\n    | {\n        type: \"git\";\n        url: string;\n        depth?: number;\n        revision?: string;\n      }\n    | {\n        type: \"git\";\n        url: string;\n        username: string;\n        password: string;\n        depth?: number;\n        revision?: string;\n      }\n    | { type: \"tarball\"; url: string };\n  /**\n   * Array of port numbers to expose from the sandbox. Sandboxes can\n   * expose up to 4 ports.\n   */\n  ports?: number[];\n  /**\n   * Timeout in milliseconds before the sandbox auto-terminates.\n   */\n  timeout?: number;\n  /**\n   * Resources to allocate to the sandbox.\n   *\n   * Your sandbox will get the amount of vCPUs you specify here and\n   * 2048 MB of memory per vCPU.\n   */\n  resources?: { vcpus: number };\n\n  /**\n   * The runtime of the sandbox, currently only `node24`, `node22` and `python3.13` are supported.\n   * If not specified, the default runtime `node24` will be used.\n   */\n  runtime?: RUNTIMES | (string & {});\n\n  /**\n   * Network policy to define network restrictions for the sandbox.\n   * Defaults to full internet access if not specified.\n   */\n  networkPolicy?: NetworkPolicy;\n\n  /**\n   * Default environment variables for the sandbox.\n   * These are inherited by all commands unless overridden with\n   * the `env` option in `runCommand`.\n   *\n   * @example\n   * const sandbox = await Sandbox.create({\n   *   env: { NODE_ENV: \"production\", API_KEY: \"secret\" },\n   * });\n   * // All commands will have NODE_ENV and API_KEY set\n   * await sandbox.runCommand(\"node\", [\"app.js\"]);\n   */\n  env?: Record<string, string>;\n\n  /**\n   * An AbortSignal to cancel sandbox creation.\n   */\n  signal?: AbortSignal;\n}\n\nexport type CreateSandboxParams =\n  | BaseCreateSandboxParams\n  | (Omit<BaseCreateSandboxParams, \"runtime\" | \"source\"> & {\n      source: { type: \"snapshot\"; snapshotId: string };\n    });\n\n/** @inline */\ninterface GetSandboxParams {\n  /**\n   * Unique identifier of the sandbox.\n   */\n  sandboxId: string;\n  /**\n   * An AbortSignal to cancel the operation.\n   */\n  signal?: AbortSignal;\n}\n\n/**\n * Serialized representation of a Sandbox for @workflow/serde.\n */\nexport interface SerializedSandbox {\n  metadata: SandboxSnapshot;\n  routes: SandboxRouteData[];\n}\n\n/** @inline */\ninterface RunCommandParams {\n  /**\n   * The command to execute\n   */\n  cmd: string;\n  /**\n   * Arguments to pass to the command\n   */\n  args?: string[];\n  /**\n   * Working directory to execute the command in\n   */\n  cwd?: string;\n  /**\n   * Environment variables to set for this command\n   */\n  env?: Record<string, string>;\n  /**\n   * If true, execute this command with root privileges. Defaults to false.\n   */\n  sudo?: boolean;\n  /**\n   * If true, the command will return without waiting for `exitCode`\n   */\n  detached?: boolean;\n  /**\n   * A `Writable` stream where `stdout` from the command will be piped\n   */\n  stdout?: Writable;\n  /**\n   * A `Writable` stream where `stderr` from the command will be piped\n   */\n  stderr?: Writable;\n  /**\n   * An AbortSignal to cancel the command execution\n   */\n  signal?: AbortSignal;\n}\n\n// ============================================================================\n// Sandbox class\n// ============================================================================\n\n/**\n * A Sandbox is an isolated Linux MicroVM to run commands in.\n *\n * Use {@link Sandbox.create} or {@link Sandbox.get} to construct.\n * @hideconstructor\n */\nexport class Sandbox {\n  private _client: APIClient | null = null;\n\n  /**\n   * Lazily resolve credentials and construct an API client.\n   * This is used in step contexts where the Sandbox was deserialized\n   * without a client (e.g. when crossing workflow/step boundaries).\n   * Uses getCredentials() which resolves from OIDC or env vars.\n   * @internal\n   */\n  private async ensureClient(): Promise<APIClient> {\n    \"use step\";\n    if (this._client) return this._client;\n    const credentials = await getCredentials();\n    this._client = new APIClient({\n      teamId: credentials.teamId,\n      token: credentials.token,\n    });\n    return this._client;\n  }\n\n  /**\n   * Routes from ports to subdomains.\n  /* @hidden\n   */\n  public readonly routes: SandboxRouteData[];\n\n  /**\n   * A `node:fs/promises`-compatible API for interacting with the sandbox filesystem.\n   *\n   * @example\n   * const content = await sandbox.fs.readFile('/etc/hostname', 'utf8');\n   * await sandbox.fs.writeFile('/tmp/hello.txt', 'Hello, world!');\n   * const files = await sandbox.fs.readdir('/tmp');\n   * const stats = await sandbox.fs.stat('/tmp/hello.txt');\n   */\n  public readonly fs: FileSystem;\n\n  /**\n   * Unique ID of this sandbox.\n   */\n  public get sandboxId(): string {\n    return this.sandbox.id;\n  }\n\n  public get interactivePort(): number | undefined {\n    return this.sandbox.interactivePort ?? undefined;\n  }\n\n  /**\n   * The status of the sandbox.\n   */\n  public get status(): SandboxMetaData[\"status\"] {\n    return this.sandbox.status;\n  }\n\n  /**\n   * The creation date of the sandbox.\n   */\n  public get createdAt(): Date {\n    return new Date(this.sandbox.createdAt);\n  }\n\n  /**\n   * The timeout of the sandbox in milliseconds.\n   */\n  public get timeout(): number {\n    return this.sandbox.timeout;\n  }\n\n  /**\n   * The network policy of the sandbox.\n   */\n  public get networkPolicy(): NetworkPolicy | undefined {\n    return this.sandbox.networkPolicy;\n  }\n\n  /**\n   * If the sandbox was created from a snapshot, the ID of that snapshot.\n   */\n  public get sourceSnapshotId(): string | undefined {\n    return this.sandbox.sourceSnapshotId;\n  }\n\n  /**\n   * The amount of CPU used by the sandbox. Only reported once the VM is stopped.\n   */\n  public get activeCpuUsageMs(): number | undefined {\n    return this.sandbox.activeCpuDurationMs;\n  }\n\n  /**\n   * The amount of network data used by the sandbox. Only reported once the VM is stopped.\n   */\n  public get networkTransfer():\n    | { ingress: number; egress: number }\n    | undefined {\n    return this.sandbox.networkTransfer;\n  }\n\n  /**\n   * Internal metadata about this sandbox.\n   */\n  private sandbox: SandboxSnapshot;\n\n  /**\n   * Allow to get a list of sandboxes for a team narrowed to the given params.\n   * It returns both the sandboxes and the pagination metadata to allow getting\n   * the next page of results.\n   */\n  static async list(\n    params?: Partial<Parameters<APIClient[\"listSandboxes\"]>[0]> &\n      Partial<Credentials> &\n      WithFetchOptions,\n  ) {\n    \"use step\";\n    const credentials = await getCredentials(params);\n    const client = new APIClient({\n      teamId: credentials.teamId,\n      token: credentials.token,\n      fetch: params?.fetch,\n    });\n    return client.listSandboxes({\n      ...credentials,\n      ...params,\n    });\n  }\n\n  /**\n   * Serialize a Sandbox instance to plain data for @workflow/serde.\n   *\n   * @param instance - The Sandbox instance to serialize\n   * @returns A plain object containing sandbox metadata and routes\n   */\n  static [WORKFLOW_SERIALIZE](instance: Sandbox): SerializedSandbox {\n    return {\n      metadata: instance.sandbox,\n      routes: instance.routes,\n    };\n  }\n\n  /**\n   * Deserialize a Sandbox from serialized snapshot data.\n   *\n   * The deserialized instance uses the serialized metadata synchronously and\n   * lazily creates an API client only when methods perform API requests.\n   *\n   * @param data - The serialized sandbox data\n   * @returns The reconstructed Sandbox instance\n   */\n  static [WORKFLOW_DESERIALIZE](data: SerializedSandbox): Sandbox {\n    return new Sandbox({\n      sandbox: data.metadata,\n      routes: data.routes,\n    });\n  }\n\n  /**\n   * Create a new sandbox.\n   *\n   * @param params - Creation parameters and optional credentials.\n   * @returns A promise resolving to the created {@link Sandbox}.\n   * @example\n   * <caption>Create a sandbox and drop it in the end of the block</caption>\n   * async function fn() {\n   *   await using const sandbox = await Sandbox.create();\n   *   // Sandbox automatically stopped at the end of the lexical scope\n   * }\n   */\n  static async create(\n    params?: WithPrivate<\n      CreateSandboxParams | (CreateSandboxParams & Credentials)\n    > &\n      WithFetchOptions,\n  ): Promise<Sandbox & AsyncDisposable> {\n    \"use step\";\n    const credentials = await getCredentials(params);\n    const client = new APIClient({\n      teamId: credentials.teamId,\n      token: credentials.token,\n      fetch: params?.fetch,\n    });\n\n    const privateParams = getPrivateParams(params);\n    const sandbox = await client.createSandbox({\n      source: params?.source,\n      projectId: credentials.projectId,\n      ports: params?.ports ?? [],\n      timeout: params?.timeout,\n      resources: params?.resources,\n      runtime: params && \"runtime\" in params ? params?.runtime : undefined,\n      networkPolicy: params?.networkPolicy,\n      env: params?.env,\n      signal: params?.signal,\n      ...privateParams,\n    });\n\n    return new DisposableSandbox({\n      client,\n      sandbox: toSandboxSnapshot(sandbox.json.sandbox),\n      routes: sandbox.json.routes,\n    });\n  }\n\n  /**\n   * Retrieve an existing sandbox.\n   *\n   * @param params - Get parameters and optional credentials.\n   * @returns A promise resolving to the {@link Sandbox}.\n   */\n  static async get(\n    params: WithPrivate<GetSandboxParams | (GetSandboxParams & Credentials)> &\n      WithFetchOptions,\n  ): Promise<Sandbox> {\n    \"use step\";\n    const credentials = await getCredentials(params);\n    const client = new APIClient({\n      teamId: credentials.teamId,\n      token: credentials.token,\n      fetch: params.fetch,\n    });\n\n    const privateParams = getPrivateParams(params);\n    const sandbox = await client.getSandbox({\n      sandboxId: params.sandboxId,\n      signal: params.signal,\n      ...privateParams,\n    });\n\n    return new Sandbox({\n      client,\n      sandbox: toSandboxSnapshot(sandbox.json.sandbox),\n      routes: sandbox.json.routes,\n    });\n  }\n\n  /**\n   * Create a new Sandbox instance.\n   *\n   * @param params.client - Optional API client. If not provided, will be lazily created using global credentials.\n   * @param params.routes - Port-to-subdomain mappings for exposed ports\n   * @param params.sandbox - Sandbox snapshot metadata\n   */\n  constructor({\n    client,\n    routes,\n    sandbox,\n  }: {\n    client?: APIClient;\n    routes: SandboxRouteData[];\n    sandbox: SandboxSnapshot;\n  }) {\n    this._client = client ?? null;\n    this.routes = routes;\n    this.sandbox = sandbox;\n    this.fs = new FileSystem(this);\n  }\n\n  /**\n   * Get a previously run command by its ID.\n   *\n   * @param cmdId - ID of the command to retrieve\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A {@link Command} instance representing the command\n   */\n  async getCommand(\n    cmdId: string,\n    opts?: { signal?: AbortSignal },\n  ): Promise<Command> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const command = await client.getCommand({\n      sandboxId: this.sandbox.id,\n      cmdId,\n      signal: opts?.signal,\n    });\n\n    return new Command({\n      client,\n      sandboxId: this.sandbox.id,\n      cmd: command.json.command,\n    });\n  }\n\n  /**\n   * Start executing a command in this sandbox.\n   *\n   * @param command - The command to execute.\n   * @param args - Arguments to pass to the command.\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the command execution.\n   * @returns A {@link CommandFinished} result once execution is done.\n   */\n  async runCommand(\n    command: string,\n    args?: string[],\n    opts?: { signal?: AbortSignal },\n  ): Promise<CommandFinished>;\n\n  /**\n   * Start executing a command in detached mode.\n   *\n   * @param params - The command parameters.\n   * @returns A {@link Command} instance for the running command.\n   */\n  async runCommand(\n    params: RunCommandParams & { detached: true },\n  ): Promise<Command>;\n\n  /**\n   * Start executing a command in this sandbox.\n   *\n   * @param params - The command parameters.\n   * @returns A {@link CommandFinished} result once execution is done.\n   */\n  async runCommand(params: RunCommandParams): Promise<CommandFinished>;\n\n  async runCommand(\n    commandOrParams: string | RunCommandParams,\n    args?: string[],\n    opts?: { signal?: AbortSignal },\n  ): Promise<Command | CommandFinished> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const params: RunCommandParams =\n      typeof commandOrParams === \"string\"\n        ? { cmd: commandOrParams, args, signal: opts?.signal }\n        : commandOrParams;\n\n    const wait = params.detached ? false : true;\n    const pipeLogs = async (command: Command): Promise<void> => {\n      if (!params.stdout && !params.stderr) {\n        return;\n      }\n\n      try {\n        for await (const log of command.logs({ signal: params.signal })) {\n          if (log.stream === \"stdout\") {\n            params.stdout?.write(log.data);\n          } else if (log.stream === \"stderr\") {\n            params.stderr?.write(log.data);\n          }\n        }\n      } catch (err) {\n        if (params.signal?.aborted) {\n          return;\n        }\n        throw err;\n      }\n    };\n\n    if (wait) {\n      const commandStream = await client.runCommand({\n        sandboxId: this.sandbox.id,\n        command: params.cmd,\n        args: params.args ?? [],\n        cwd: params.cwd,\n        env: params.env ?? {},\n        sudo: params.sudo ?? false,\n        wait: true,\n        signal: params.signal,\n      });\n\n      const command = new Command({\n        client,\n        sandboxId: this.sandbox.id,\n        cmd: commandStream.command,\n      });\n\n      const [finished] = await Promise.all([\n        commandStream.finished,\n        pipeLogs(command),\n      ]);\n      return new CommandFinished({\n        client,\n        sandboxId: this.sandbox.id,\n        cmd: finished,\n        exitCode: finished.exitCode ?? 0,\n      });\n    }\n\n    const commandResponse = await client.runCommand({\n      sandboxId: this.sandbox.id,\n      command: params.cmd,\n      args: params.args ?? [],\n      cwd: params.cwd,\n      env: params.env ?? {},\n      sudo: params.sudo ?? false,\n      signal: params.signal,\n    });\n\n    const command = new Command({\n      client,\n      sandboxId: this.sandbox.id,\n      cmd: commandResponse.json.command,\n    });\n\n    void pipeLogs(command).catch((err) => {\n      if (params.signal?.aborted) {\n        return;\n      }\n      (params.stderr ?? params.stdout)?.emit(\"error\", err);\n    });\n\n    return command;\n  }\n\n  /**\n   * Create a directory in the filesystem of this sandbox.\n   *\n   * @param path - Path of the directory to create\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   */\n  async mkDir(path: string, opts?: { signal?: AbortSignal }): Promise<void> {\n    \"use step\";\n    const client = await this.ensureClient();\n    await client.mkDir({\n      sandboxId: this.sandbox.id,\n      path: path,\n      signal: opts?.signal,\n    });\n  }\n\n  /**\n   * Read a file from the filesystem of this sandbox as a stream.\n   *\n   * @param file - File to read, with path and optional cwd\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A promise that resolves to a ReadableStream containing the file contents, or null if file not found\n   */\n  async readFile(\n    file: { path: string; cwd?: string },\n    opts?: { signal?: AbortSignal },\n  ): Promise<NodeJS.ReadableStream | null> {\n    \"use step\";\n    const client = await this.ensureClient();\n    return client.readFile({\n      sandboxId: this.sandbox.id,\n      path: file.path,\n      cwd: file.cwd,\n      signal: opts?.signal,\n    });\n  }\n\n  /**\n   * Read a file from the filesystem of this sandbox as a Buffer.\n   *\n   * @param file - File to read, with path and optional cwd\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A promise that resolves to the file contents as a Buffer, or null if file not found\n   */\n  async readFileToBuffer(\n    file: { path: string; cwd?: string },\n    opts?: { signal?: AbortSignal },\n  ): Promise<Buffer | null> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const stream = await client.readFile({\n      sandboxId: this.sandbox.id,\n      path: file.path,\n      cwd: file.cwd,\n      signal: opts?.signal,\n    });\n\n    if (stream === null) {\n      return null;\n    }\n\n    return consumeReadable(stream);\n  }\n\n  /**\n   * Download a file from the sandbox to the local filesystem.\n   *\n   * @param src - Source file on the sandbox, with path and optional cwd\n   * @param dst - Destination file on the local machine, with path and optional cwd\n   * @param opts - Optional parameters.\n   * @param opts.mkdirRecursive - If true, create parent directories for the destination if they don't exist.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns The absolute path to the written file, or null if the source file was not found\n   */\n  async downloadFile(\n    src: { path: string; cwd?: string },\n    dst: { path: string; cwd?: string },\n    opts?: { mkdirRecursive?: boolean; signal?: AbortSignal },\n  ): Promise<string | null> {\n    \"use step\";\n    const client = await this.ensureClient();\n    if (!src?.path) {\n      throw new Error(\"downloadFile: source path is required\");\n    }\n\n    if (!dst?.path) {\n      throw new Error(\"downloadFile: destination path is required\");\n    }\n\n    const stream = await client.readFile({\n      sandboxId: this.sandbox.id,\n      path: src.path,\n      cwd: src.cwd,\n      signal: opts?.signal,\n    });\n\n    if (stream === null) {\n      return null;\n    }\n\n    try {\n      const dstPath = resolve(dst.cwd ?? \"\", dst.path);\n      if (opts?.mkdirRecursive) {\n        await mkdir(dirname(dstPath), { recursive: true });\n      }\n      await pipeline(stream, createWriteStream(dstPath), {\n        signal: opts?.signal,\n      });\n      return dstPath;\n    } finally {\n      stream.destroy();\n    }\n  }\n\n  /**\n   * Write files to the filesystem of this sandbox.\n   * Defaults to writing to /vercel/sandbox unless an absolute path is specified.\n   * Writes files using the `vercel-sandbox` user.\n   *\n   * @param files - Array of files with path, content, and optional mode (permissions)\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A promise that resolves when the files are written\n   *\n   * @example\n   * // Write an executable script\n   * await sandbox.writeFiles([\n   *   { path: \"/usr/local/bin/myscript\", content: \"#!/bin/bash\\necho hello\", mode: 0o755 }\n   * ]);\n   */\n  async writeFiles(\n    files: {\n      path: string;\n      content: string | Uint8Array;\n      mode?: number;\n    }[],\n    opts?: { signal?: AbortSignal },\n  ) {\n    \"use step\";\n    const client = await this.ensureClient();\n    return client.writeFiles({\n      sandboxId: this.sandbox.id,\n      cwd: this.sandbox.cwd,\n      extractDir: \"/\",\n      files: files,\n      signal: opts?.signal,\n    });\n  }\n\n  /**\n   * Get the public domain of a port of this sandbox.\n   *\n   * @param p - Port number to resolve\n   * @returns A full domain (e.g. `https://subdomain.vercel.run`)\n   * @throws If the port has no associated route\n   */\n  domain(p: number): string {\n    const route = this.routes.find(({ port }) => port == p);\n    if (route) {\n      return `https://${route.subdomain}.vercel.run`;\n    } else {\n      throw new Error(`No route for port ${p}`);\n    }\n  }\n\n  /**\n   * Stop the sandbox.\n   *\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @param opts.blocking - If true, poll until the sandbox has fully stopped and return the final state.\n   * @returns The sandbox metadata at the time the stop was acknowledged, or after fully stopped if `blocking` is true.\n   */\n  async stop(opts?: {\n    signal?: AbortSignal;\n    blocking?: boolean;\n  }): Promise<SandboxSnapshot> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const response = await client.stopSandbox({\n      sandboxId: this.sandbox.id,\n      signal: opts?.signal,\n      blocking: opts?.blocking,\n    });\n    this.sandbox = toSandboxSnapshot(response.json.sandbox);\n    return this.sandbox;\n  }\n\n  /**\n   * Update the network policy for this sandbox.\n   *\n   * @param networkPolicy - The new network policy to apply.\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A promise that resolves when the network policy is updated.\n   *\n   * @example\n   * // Restrict to specific domains\n   * await sandbox.updateNetworkPolicy({\n   *   allow: [\"*.npmjs.org\", \"github.com\"],\n   * });\n   *\n   * @example\n   * // Inject credentials with per-domain transformers\n   * await sandbox.updateNetworkPolicy({\n   *   allow: {\n   *     \"ai-gateway.vercel.sh\": [{\n   *       transform: [{\n   *         headers: { authorization: \"Bearer ...\" }\n   *       }]\n   *     }],\n   *     \"*\": []\n   *   }\n   * });\n   *\n   * @example\n   * // Deny all network access\n   * await sandbox.updateNetworkPolicy(\"deny-all\");\n   */\n  async updateNetworkPolicy(\n    networkPolicy: NetworkPolicy,\n    opts?: { signal?: AbortSignal },\n  ): Promise<NetworkPolicy> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const response = await client.updateNetworkPolicy({\n      sandboxId: this.sandbox.id,\n      networkPolicy: networkPolicy,\n      signal: opts?.signal,\n    });\n\n    // Update the internal sandbox metadata with the new timeout value\n    this.sandbox = toSandboxSnapshot(response.json.sandbox);\n    return this.sandbox.networkPolicy!;\n  }\n\n  /**\n   * Extend the timeout of the sandbox by the specified duration.\n   *\n   * This allows you to extend the lifetime of a sandbox up until the maximum\n   * execution timeout for your plan.\n   *\n   * @param duration - The duration in milliseconds to extend the timeout by\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A promise that resolves when the timeout is extended\n   *\n   * @example\n   * const sandbox = await Sandbox.create({ timeout: ms('10m') });\n   * // Extends timeout by 5 minutes, to a total of 15 minutes.\n   * await sandbox.extendTimeout(ms('5m'));\n   */\n  async extendTimeout(\n    duration: number,\n    opts?: { signal?: AbortSignal },\n  ): Promise<void> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const response = await client.extendTimeout({\n      sandboxId: this.sandbox.id,\n      duration,\n      signal: opts?.signal,\n    });\n\n    // Update the internal sandbox metadata with the new timeout value\n    this.sandbox = toSandboxSnapshot(response.json.sandbox);\n  }\n\n  /**\n   * Create a snapshot from this currently running sandbox. New sandboxes can\n   * then be created from this snapshot using {@link Sandbox.createFromSnapshot}.\n   *\n   * Note: this sandbox will be stopped as part of the snapshot creation process.\n   *\n   * @param opts - Optional parameters.\n   * @param opts.expiration - Optional expiration time in milliseconds. Use 0 for no expiration at all.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A promise that resolves to the Snapshot instance\n   */\n  async snapshot(opts?: {\n    expiration?: number;\n    signal?: AbortSignal;\n  }): Promise<Snapshot> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const response = await client.createSnapshot({\n      sandboxId: this.sandbox.id,\n      expiration: opts?.expiration,\n      signal: opts?.signal,\n    });\n\n    this.sandbox = toSandboxSnapshot(response.json.sandbox);\n\n    return new Snapshot({\n      client,\n      snapshot: response.json.snapshot,\n    });\n  }\n}\n\n/**\n * A {@link Sandbox} that can automatically be disposed using a `await using` statement.\n *\n * @example\n * {\n *   await using const sandbox = await Sandbox.create();\n * }\n * // Sandbox is automatically stopped here\n */\nclass DisposableSandbox extends Sandbox implements AsyncDisposable {\n  async [Symbol.asyncDispose]() {\n    await this.stop();\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAoLA,IAAa,UAAb,MAAa,QAAQ;;;;;;;;CAUnB,MAAc,eAAmC;AAC/C;AACA,MAAI,KAAK,QAAS,QAAO,KAAK;EAC9B,MAAM,cAAc,MAAM,gBAAgB;AAC1C,OAAK,UAAU,IAAI,UAAU;GAC3B,QAAQ,YAAY;GACpB,OAAO,YAAY;GACpB,CAAC;AACF,SAAO,KAAK;;;;;CAuBd,IAAW,YAAoB;AAC7B,SAAO,KAAK,QAAQ;;CAGtB,IAAW,kBAAsC;AAC/C,SAAO,KAAK,QAAQ,mBAAmB;;;;;CAMzC,IAAW,SAAoC;AAC7C,SAAO,KAAK,QAAQ;;;;;CAMtB,IAAW,YAAkB;AAC3B,SAAO,IAAI,KAAK,KAAK,QAAQ,UAAU;;;;;CAMzC,IAAW,UAAkB;AAC3B,SAAO,KAAK,QAAQ;;;;;CAMtB,IAAW,gBAA2C;AACpD,SAAO,KAAK,QAAQ;;;;;CAMtB,IAAW,mBAAuC;AAChD,SAAO,KAAK,QAAQ;;;;;CAMtB,IAAW,mBAAuC;AAChD,SAAO,KAAK,QAAQ;;;;;CAMtB,IAAW,kBAEG;AACZ,SAAO,KAAK,QAAQ;;;;;;;CAatB,aAAa,KACX,QAGA;AACA;EACA,MAAM,cAAc,MAAM,eAAe,OAAO;AAMhD,SALe,IAAI,UAAU;GAC3B,QAAQ,YAAY;GACpB,OAAO,YAAY;GACnB,OAAO,QAAQ;GAChB,CAAC,CACY,cAAc;GAC1B,GAAG;GACH,GAAG;GACJ,CAAC;;;;;;;;CASJ,QAAQ,oBAAoB,UAAsC;AAChE,SAAO;GACL,UAAU,SAAS;GACnB,QAAQ,SAAS;GAClB;;;;;;;;;;;CAYH,QAAQ,sBAAsB,MAAkC;AAC9D,SAAO,IAAI,QAAQ;GACjB,SAAS,KAAK;GACd,QAAQ,KAAK;GACd,CAAC;;;;;;;;;;;;;;CAeJ,aAAa,OACX,QAIoC;AACpC;EACA,MAAM,cAAc,MAAM,eAAe,OAAO;EAChD,MAAM,SAAS,IAAI,UAAU;GAC3B,QAAQ,YAAY;GACpB,OAAO,YAAY;GACnB,OAAO,QAAQ;GAChB,CAAC;EAEF,MAAM,gBAAgB,iBAAiB,OAAO;EAC9C,MAAM,UAAU,MAAM,OAAO,cAAc;GACzC,QAAQ,QAAQ;GAChB,WAAW,YAAY;GACvB,OAAO,QAAQ,SAAS,EAAE;GAC1B,SAAS,QAAQ;GACjB,WAAW,QAAQ;GACnB,SAAS,UAAU,aAAa,SAAS,QAAQ,UAAU;GAC3D,eAAe,QAAQ;GACvB,KAAK,QAAQ;GACb,QAAQ,QAAQ;GAChB,GAAG;GACJ,CAAC;AAEF,SAAO,IAAI,kBAAkB;GAC3B;GACA,SAAS,kBAAkB,QAAQ,KAAK,QAAQ;GAChD,QAAQ,QAAQ,KAAK;GACtB,CAAC;;;;;;;;CASJ,aAAa,IACX,QAEkB;AAClB;EACA,MAAM,cAAc,MAAM,eAAe,OAAO;EAChD,MAAM,SAAS,IAAI,UAAU;GAC3B,QAAQ,YAAY;GACpB,OAAO,YAAY;GACnB,OAAO,OAAO;GACf,CAAC;EAEF,MAAM,gBAAgB,iBAAiB,OAAO;EAC9C,MAAM,UAAU,MAAM,OAAO,WAAW;GACtC,WAAW,OAAO;GAClB,QAAQ,OAAO;GACf,GAAG;GACJ,CAAC;AAEF,SAAO,IAAI,QAAQ;GACjB;GACA,SAAS,kBAAkB,QAAQ,KAAK,QAAQ;GAChD,QAAQ,QAAQ,KAAK;GACtB,CAAC;;;;;;;;;CAUJ,YAAY,EACV,QACA,QACA,WAKC;OA1PK,UAA4B;AA2PlC,OAAK,UAAU,UAAU;AACzB,OAAK,SAAS;AACd,OAAK,UAAU;AACf,OAAK,KAAK,IAAI,WAAW,KAAK;;;;;;;;;;CAWhC,MAAM,WACJ,OACA,MACkB;AAClB;EACA,MAAM,SAAS,MAAM,KAAK,cAAc;EACxC,MAAM,UAAU,MAAM,OAAO,WAAW;GACtC,WAAW,KAAK,QAAQ;GACxB;GACA,QAAQ,MAAM;GACf,CAAC;AAEF,SAAO,IAAI,QAAQ;GACjB;GACA,WAAW,KAAK,QAAQ;GACxB,KAAK,QAAQ,KAAK;GACnB,CAAC;;CAoCJ,MAAM,WACJ,iBACA,MACA,MACoC;AACpC;EACA,MAAM,SAAS,MAAM,KAAK,cAAc;EACxC,MAAMA,SACJ,OAAO,oBAAoB,WACvB;GAAE,KAAK;GAAiB;GAAM,QAAQ,MAAM;GAAQ,GACpD;EAEN,MAAM,OAAO,OAAO,WAAW,QAAQ;EACvC,MAAM,WAAW,OAAO,cAAoC;AAC1D,OAAI,CAAC,OAAO,UAAU,CAAC,OAAO,OAC5B;AAGF,OAAI;AACF,eAAW,MAAM,OAAOC,UAAQ,KAAK,EAAE,QAAQ,OAAO,QAAQ,CAAC,CAC7D,KAAI,IAAI,WAAW,SACjB,QAAO,QAAQ,MAAM,IAAI,KAAK;aACrB,IAAI,WAAW,SACxB,QAAO,QAAQ,MAAM,IAAI,KAAK;YAG3B,KAAK;AACZ,QAAI,OAAO,QAAQ,QACjB;AAEF,UAAM;;;AAIV,MAAI,MAAM;GACR,MAAM,gBAAgB,MAAM,OAAO,WAAW;IAC5C,WAAW,KAAK,QAAQ;IACxB,SAAS,OAAO;IAChB,MAAM,OAAO,QAAQ,EAAE;IACvB,KAAK,OAAO;IACZ,KAAK,OAAO,OAAO,EAAE;IACrB,MAAM,OAAO,QAAQ;IACrB,MAAM;IACN,QAAQ,OAAO;IAChB,CAAC;GAEF,MAAMA,YAAU,IAAI,QAAQ;IAC1B;IACA,WAAW,KAAK,QAAQ;IACxB,KAAK,cAAc;IACpB,CAAC;GAEF,MAAM,CAAC,YAAY,MAAM,QAAQ,IAAI,CACnC,cAAc,UACd,SAASA,UAAQ,CAClB,CAAC;AACF,UAAO,IAAI,gBAAgB;IACzB;IACA,WAAW,KAAK,QAAQ;IACxB,KAAK;IACL,UAAU,SAAS,YAAY;IAChC,CAAC;;EAGJ,MAAM,kBAAkB,MAAM,OAAO,WAAW;GAC9C,WAAW,KAAK,QAAQ;GACxB,SAAS,OAAO;GAChB,MAAM,OAAO,QAAQ,EAAE;GACvB,KAAK,OAAO;GACZ,KAAK,OAAO,OAAO,EAAE;GACrB,MAAM,OAAO,QAAQ;GACrB,QAAQ,OAAO;GAChB,CAAC;EAEF,MAAM,UAAU,IAAI,QAAQ;GAC1B;GACA,WAAW,KAAK,QAAQ;GACxB,KAAK,gBAAgB,KAAK;GAC3B,CAAC;AAEF,EAAK,SAAS,QAAQ,CAAC,OAAO,QAAQ;AACpC,OAAI,OAAO,QAAQ,QACjB;AAEF,IAAC,OAAO,UAAU,OAAO,SAAS,KAAK,SAAS,IAAI;IACpD;AAEF,SAAO;;;;;;;;;CAUT,MAAM,MAAM,QAAc,MAAgD;AACxE;AAEA,SADe,MAAM,KAAK,cAAc,EAC3B,MAAM;GACjB,WAAW,KAAK,QAAQ;GACxB,MAAMC;GACN,QAAQ,MAAM;GACf,CAAC;;;;;;;;;;CAWJ,MAAM,SACJ,MACA,MACuC;AACvC;AAEA,UADe,MAAM,KAAK,cAAc,EAC1B,SAAS;GACrB,WAAW,KAAK,QAAQ;GACxB,MAAM,KAAK;GACX,KAAK,KAAK;GACV,QAAQ,MAAM;GACf,CAAC;;;;;;;;;;CAWJ,MAAM,iBACJ,MACA,MACwB;AACxB;EAEA,MAAM,SAAS,OADA,MAAM,KAAK,cAAc,EACZ,SAAS;GACnC,WAAW,KAAK,QAAQ;GACxB,MAAM,KAAK;GACX,KAAK,KAAK;GACV,QAAQ,MAAM;GACf,CAAC;AAEF,MAAI,WAAW,KACb,QAAO;AAGT,SAAO,gBAAgB,OAAO;;;;;;;;;;;;CAahC,MAAM,aACJ,KACA,KACA,MACwB;AACxB;EACA,MAAM,SAAS,MAAM,KAAK,cAAc;AACxC,MAAI,CAAC,KAAK,KACR,OAAM,IAAI,MAAM,wCAAwC;AAG1D,MAAI,CAAC,KAAK,KACR,OAAM,IAAI,MAAM,6CAA6C;EAG/D,MAAM,SAAS,MAAM,OAAO,SAAS;GACnC,WAAW,KAAK,QAAQ;GACxB,MAAM,IAAI;GACV,KAAK,IAAI;GACT,QAAQ,MAAM;GACf,CAAC;AAEF,MAAI,WAAW,KACb,QAAO;AAGT,MAAI;GACF,MAAM,UAAU,QAAQ,IAAI,OAAO,IAAI,IAAI,KAAK;AAChD,OAAI,MAAM,eACR,OAAM,MAAM,QAAQ,QAAQ,EAAE,EAAE,WAAW,MAAM,CAAC;AAEpD,SAAM,SAAS,QAAQ,kBAAkB,QAAQ,EAAE,EACjD,QAAQ,MAAM,QACf,CAAC;AACF,UAAO;YACC;AACR,UAAO,SAAS;;;;;;;;;;;;;;;;;;;CAoBpB,MAAM,WACJ,OAKA,MACA;AACA;AAEA,UADe,MAAM,KAAK,cAAc,EAC1B,WAAW;GACvB,WAAW,KAAK,QAAQ;GACxB,KAAK,KAAK,QAAQ;GAClB,YAAY;GACL;GACP,QAAQ,MAAM;GACf,CAAC;;;;;;;;;CAUJ,OAAO,GAAmB;EACxB,MAAM,QAAQ,KAAK,OAAO,MAAM,EAAE,WAAW,QAAQ,EAAE;AACvD,MAAI,MACF,QAAO,WAAW,MAAM,UAAU;MAElC,OAAM,IAAI,MAAM,qBAAqB,IAAI;;;;;;;;;;CAY7C,MAAM,KAAK,MAGkB;AAC3B;AAOA,OAAK,UAAU,mBALE,OADF,MAAM,KAAK,cAAc,EACV,YAAY;GACxC,WAAW,KAAK,QAAQ;GACxB,QAAQ,MAAM;GACd,UAAU,MAAM;GACjB,CAAC,EACwC,KAAK,QAAQ;AACvD,SAAO,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkCd,MAAM,oBACJ,eACA,MACwB;AACxB;AASA,OAAK,UAAU,mBAPE,OADF,MAAM,KAAK,cAAc,EACV,oBAAoB;GAChD,WAAW,KAAK,QAAQ;GACT;GACf,QAAQ,MAAM;GACf,CAAC,EAGwC,KAAK,QAAQ;AACvD,SAAO,KAAK,QAAQ;;;;;;;;;;;;;;;;;;CAmBtB,MAAM,cACJ,UACA,MACe;AACf;AASA,OAAK,UAAU,mBAPE,OADF,MAAM,KAAK,cAAc,EACV,cAAc;GAC1C,WAAW,KAAK,QAAQ;GACxB;GACA,QAAQ,MAAM;GACf,CAAC,EAGwC,KAAK,QAAQ;;;;;;;;;;;;;CAczD,MAAM,SAAS,MAGO;AACpB;EACA,MAAM,SAAS,MAAM,KAAK,cAAc;EACxC,MAAM,WAAW,MAAM,OAAO,eAAe;GAC3C,WAAW,KAAK,QAAQ;GACxB,YAAY,MAAM;GAClB,QAAQ,MAAM;GACf,CAAC;AAEF,OAAK,UAAU,kBAAkB,SAAS,KAAK,QAAQ;AAEvD,SAAO,IAAI,SAAS;GAClB;GACA,UAAU,SAAS,KAAK;GACzB,CAAC;;;;;;;;;;;;AAaN,IAAM,oBAAN,cAAgC,QAAmC;CACjE,OAAO,OAAO,gBAAgB;AAC5B,QAAM,KAAK,MAAM"}

package/dist/snapshot.cjs

@@ -1,6 +1,8 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
 const require_api_client = require('./api-client/api-client.cjs');
 require('./api-client/index.cjs');
 const require_get_credentials = require('./utils/get-credentials.cjs');
+let __workflow_serde = require("@workflow/serde");
 
 //#region src/snapshot.ts
 /**
@@ -10,6 +12,22 @@ const require_get_credentials = require('./utils/get-credentials.cjs');
 * @hideconstructor
 */
 var Snapshot = class Snapshot {
+	/**
+	* Lazily resolve credentials and construct an API client.
+	* This is used in step contexts where the Snapshot was deserialized
+	* without a client (e.g. when crossing workflow/step boundaries).
+	* @internal
+	*/
+	async ensureClient() {
+		"use step";
+		if (this._client) return this._client;
+		const credentials = await require_get_credentials.getCredentials();
+		this._client = new require_api_client.APIClient({
+			teamId: credentials.teamId,
+			token: credentials.token
+		});
+		return this._client;
+	}
 	/**
 	* Unique ID of this snapshot.
 	*/
@@ -48,13 +66,29 @@ var Snapshot = class Snapshot {
 		return new Date(this.snapshot.expiresAt);
 	}
 	/**
-	* Create a new Snapshot instance.
+	* Serialize a Snapshot instance to plain data for @workflow/serde.
 	*
-	* @param client - API client used to communicate with the backend
-	* @param snapshot - Snapshot metadata
+	* @param instance - The Snapshot instance to serialize
+	* @returns A plain object containing snapshot metadata
 	*/
+	static [__workflow_serde.WORKFLOW_SERIALIZE](instance) {
+		return { snapshot: instance.snapshot };
+	}
+	/**
+	* Deserialize a Snapshot from serialized data.
+	*
+	* The deserialized instance uses the serialized metadata synchronously and
+	* lazily creates an API client only when methods perform API requests.
+	*
+	* @param data - The serialized snapshot data
+	* @returns The reconstructed Snapshot instance
+	*/
+	static [__workflow_serde.WORKFLOW_DESERIALIZE](data) {
+		return new Snapshot({ snapshot: data.snapshot });
+	}
 	constructor({ client, snapshot }) {
-		this.client = client;
+		this._client = null;
+		this._client = client ?? null;
 		this.snapshot = snapshot;
 	}
 	/**
@@ -104,7 +138,7 @@ var Snapshot = class Snapshot {
 	*/
 	async delete(opts) {
 		"use step";
-		this.snapshot = (await this.client.deleteSnapshot({
+		this.snapshot = (await (await this.ensureClient()).deleteSnapshot({
 			snapshotId: this.snapshot.id,
 			signal: opts?.signal
 		})).json.snapshot;

package/dist/snapshot.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"snapshot.cjs","names":["getCredentials","APIClient"],"sources":["../src/snapshot.ts"],"sourcesContent":["import type { WithFetchOptions } from \"./api-client/api-client.js\";\nimport type { SnapshotMetadata } from \"./api-client/index.js\";\nimport { APIClient } from \"./api-client/index.js\";\nimport { type Credentials, getCredentials } from \"./utils/get-credentials.js\";\n\n/** @inline */\ninterface GetSnapshotParams {\n  /**\n   * Unique identifier of the snapshot.\n   */\n  snapshotId: string;\n  /**\n   * An AbortSignal to cancel the operation.\n   */\n  signal?: AbortSignal;\n}\n\n/**\n * A Snapshot is a saved state of a Sandbox that can be used to create new Sandboxes\n *\n * Use {@link Sandbox.snapshot} or {@link Snapshot.get} to construct.\n * @hideconstructor\n */\nexport class Snapshot {\n  private readonly client: APIClient;\n\n  /**\n   * Unique ID of this snapshot.\n   */\n  public get snapshotId(): string {\n    return this.snapshot.id;\n  }\n\n  /**\n   * The ID the sandbox from which this snapshot was created.\n   */\n  public get sourceSandboxId(): string {\n    return this.snapshot.sourceSandboxId;\n  }\n\n  /**\n   * The status of the snapshot.\n   */\n  public get status(): SnapshotMetadata[\"status\"] {\n    return this.snapshot.status;\n  }\n\n  /**\n   * The size of the snapshot in bytes, or null if not available.\n   */\n  public get sizeBytes(): number {\n    return this.snapshot.sizeBytes;\n  }\n\n  /**\n   * The creation date of this snapshot.\n   */\n  public get createdAt(): Date {\n    return new Date(this.snapshot.createdAt);\n  }\n\n  /**\n   * The expiration date of this snapshot, or undefined if it does not expire.\n   */\n  public get expiresAt(): Date | undefined {\n    if (this.snapshot.expiresAt === undefined) {\n      return undefined;\n    }\n\n    return new Date(this.snapshot.expiresAt);\n  }\n\n  /**\n   * Internal metadata about this snapshot.\n   */\n  private snapshot: SnapshotMetadata;\n\n  /**\n   * Create a new Snapshot instance.\n   *\n   * @param client - API client used to communicate with the backend\n   * @param snapshot - Snapshot metadata\n   */\n  constructor({\n    client,\n    snapshot,\n  }: {\n    client: APIClient;\n    snapshot: SnapshotMetadata;\n  }) {\n    this.client = client;\n    this.snapshot = snapshot;\n  }\n\n  /**\n   * Allow to get a list of snapshots for a team narrowed to the given params.\n   * It returns both the snapshots and the pagination metadata to allow getting\n   * the next page of results.\n   */\n  static async list(\n    params?: Partial<Parameters<APIClient[\"listSnapshots\"]>[0]> &\n      Partial<Credentials> &\n      WithFetchOptions,\n  ) {\n    \"use step\";\n    const credentials = await getCredentials(params);\n    const client = new APIClient({\n      teamId: credentials.teamId,\n      token: credentials.token,\n      fetch: params?.fetch,\n    });\n    return client.listSnapshots({\n      ...credentials,\n      ...params,\n    });\n  }\n\n  /**\n   * Retrieve an existing snapshot.\n   *\n   * @param params - Get parameters and optional credentials.\n   * @returns A promise resolving to the {@link Sandbox}.\n   */\n  static async get(\n    params: GetSnapshotParams | (GetSnapshotParams & Credentials),\n  ): Promise<Snapshot> {\n    \"use step\";\n    const credentials = await getCredentials(params);\n    const client = new APIClient({\n      teamId: credentials.teamId,\n      token: credentials.token,\n    });\n\n    const sandbox = await client.getSnapshot({\n      snapshotId: params.snapshotId,\n      signal: params.signal,\n    });\n\n    return new Snapshot({\n      client,\n      snapshot: sandbox.json.snapshot,\n    });\n  }\n\n  /**\n   * Delete this snapshot.\n   *\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A promise that resolves once the snapshot has been deleted.\n   */\n  async delete(opts?: { signal?: AbortSignal }): Promise<void> {\n    \"use step\";\n    const response = await this.client!.deleteSnapshot({\n      snapshotId: this.snapshot.id,\n      signal: opts?.signal,\n    });\n\n    this.snapshot = response.json.snapshot;\n  }\n}\n"],"mappings":";;;;;;;;;;;AAuBA,IAAa,WAAb,MAAa,SAAS;;;;CAMpB,IAAW,aAAqB;AAC9B,SAAO,KAAK,SAAS;;;;;CAMvB,IAAW,kBAA0B;AACnC,SAAO,KAAK,SAAS;;;;;CAMvB,IAAW,SAAqC;AAC9C,SAAO,KAAK,SAAS;;;;;CAMvB,IAAW,YAAoB;AAC7B,SAAO,KAAK,SAAS;;;;;CAMvB,IAAW,YAAkB;AAC3B,SAAO,IAAI,KAAK,KAAK,SAAS,UAAU;;;;;CAM1C,IAAW,YAA8B;AACvC,MAAI,KAAK,SAAS,cAAc,OAC9B;AAGF,SAAO,IAAI,KAAK,KAAK,SAAS,UAAU;;;;;;;;CAc1C,YAAY,EACV,QACA,YAIC;AACD,OAAK,SAAS;AACd,OAAK,WAAW;;;;;;;CAQlB,aAAa,KACX,QAGA;AACA;EACA,MAAM,cAAc,MAAMA,uCAAe,OAAO;AAMhD,SALe,IAAIC,6BAAU;GAC3B,QAAQ,YAAY;GACpB,OAAO,YAAY;GACnB,OAAO,QAAQ;GAChB,CAAC,CACY,cAAc;GAC1B,GAAG;GACH,GAAG;GACJ,CAAC;;;;;;;;CASJ,aAAa,IACX,QACmB;AACnB;EACA,MAAM,cAAc,MAAMD,uCAAe,OAAO;EAChD,MAAM,SAAS,IAAIC,6BAAU;GAC3B,QAAQ,YAAY;GACpB,OAAO,YAAY;GACpB,CAAC;AAOF,SAAO,IAAI,SAAS;GAClB;GACA,WAPc,MAAM,OAAO,YAAY;IACvC,YAAY,OAAO;IACnB,QAAQ,OAAO;IAChB,CAAC,EAIkB,KAAK;GACxB,CAAC;;;;;;;;;CAUJ,MAAM,OAAO,MAAgD;AAC3D;AAMA,OAAK,YALY,MAAM,KAAK,OAAQ,eAAe;GACjD,YAAY,KAAK,SAAS;GAC1B,QAAQ,MAAM;GACf,CAAC,EAEuB,KAAK"}
+{"version":3,"file":"snapshot.cjs","names":["getCredentials","APIClient","WORKFLOW_SERIALIZE","WORKFLOW_DESERIALIZE"],"sources":["../src/snapshot.ts"],"sourcesContent":["import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from \"@workflow/serde\";\nimport type { WithFetchOptions } from \"./api-client/api-client.js\";\nimport type { SnapshotMetadata } from \"./api-client/index.js\";\nimport { APIClient } from \"./api-client/index.js\";\nimport { type Credentials, getCredentials } from \"./utils/get-credentials.js\";\n\nexport interface SerializedSnapshot {\n  snapshot: SnapshotMetadata;\n}\n\n/** @inline */\ninterface GetSnapshotParams {\n  /**\n   * Unique identifier of the snapshot.\n   */\n  snapshotId: string;\n  /**\n   * An AbortSignal to cancel the operation.\n   */\n  signal?: AbortSignal;\n}\n\n/**\n * A Snapshot is a saved state of a Sandbox that can be used to create new Sandboxes\n *\n * Use {@link Sandbox.snapshot} or {@link Snapshot.get} to construct.\n * @hideconstructor\n */\nexport class Snapshot {\n  private _client: APIClient | null = null;\n\n  /**\n   * Lazily resolve credentials and construct an API client.\n   * This is used in step contexts where the Snapshot was deserialized\n   * without a client (e.g. when crossing workflow/step boundaries).\n   * @internal\n   */\n  private async ensureClient(): Promise<APIClient> {\n    \"use step\";\n    if (this._client) return this._client;\n    const credentials = await getCredentials();\n    this._client = new APIClient({\n      teamId: credentials.teamId,\n      token: credentials.token,\n    });\n    return this._client;\n  }\n\n  /**\n   * Unique ID of this snapshot.\n   */\n  public get snapshotId(): string {\n    return this.snapshot.id;\n  }\n\n  /**\n   * The ID the sandbox from which this snapshot was created.\n   */\n  public get sourceSandboxId(): string {\n    return this.snapshot.sourceSandboxId;\n  }\n\n  /**\n   * The status of the snapshot.\n   */\n  public get status(): SnapshotMetadata[\"status\"] {\n    return this.snapshot.status;\n  }\n\n  /**\n   * The size of the snapshot in bytes, or null if not available.\n   */\n  public get sizeBytes(): number {\n    return this.snapshot.sizeBytes;\n  }\n\n  /**\n   * The creation date of this snapshot.\n   */\n  public get createdAt(): Date {\n    return new Date(this.snapshot.createdAt);\n  }\n\n  /**\n   * The expiration date of this snapshot, or undefined if it does not expire.\n   */\n  public get expiresAt(): Date | undefined {\n    if (this.snapshot.expiresAt === undefined) {\n      return undefined;\n    }\n\n    return new Date(this.snapshot.expiresAt);\n  }\n\n  /**\n   * Internal metadata about this snapshot.\n   */\n  private snapshot: SnapshotMetadata;\n\n  /**\n   * Serialize a Snapshot instance to plain data for @workflow/serde.\n   *\n   * @param instance - The Snapshot instance to serialize\n   * @returns A plain object containing snapshot metadata\n   */\n  static [WORKFLOW_SERIALIZE](instance: Snapshot): SerializedSnapshot {\n    return {\n      snapshot: instance.snapshot,\n    };\n  }\n\n  /**\n   * Deserialize a Snapshot from serialized data.\n   *\n   * The deserialized instance uses the serialized metadata synchronously and\n   * lazily creates an API client only when methods perform API requests.\n   *\n   * @param data - The serialized snapshot data\n   * @returns The reconstructed Snapshot instance\n   */\n  static [WORKFLOW_DESERIALIZE](data: SerializedSnapshot): Snapshot {\n    return new Snapshot({\n      snapshot: data.snapshot,\n    });\n  }\n\n  constructor({\n    client,\n    snapshot,\n  }: {\n    client?: APIClient;\n    snapshot: SnapshotMetadata;\n  }) {\n    this._client = client ?? null;\n    this.snapshot = snapshot;\n  }\n\n  /**\n   * Allow to get a list of snapshots for a team narrowed to the given params.\n   * It returns both the snapshots and the pagination metadata to allow getting\n   * the next page of results.\n   */\n  static async list(\n    params?: Partial<Parameters<APIClient[\"listSnapshots\"]>[0]> &\n      Partial<Credentials> &\n      WithFetchOptions,\n  ) {\n    \"use step\";\n    const credentials = await getCredentials(params);\n    const client = new APIClient({\n      teamId: credentials.teamId,\n      token: credentials.token,\n      fetch: params?.fetch,\n    });\n    return client.listSnapshots({\n      ...credentials,\n      ...params,\n    });\n  }\n\n  /**\n   * Retrieve an existing snapshot.\n   *\n   * @param params - Get parameters and optional credentials.\n   * @returns A promise resolving to the {@link Sandbox}.\n   */\n  static async get(\n    params: GetSnapshotParams | (GetSnapshotParams & Credentials),\n  ): Promise<Snapshot> {\n    \"use step\";\n    const credentials = await getCredentials(params);\n    const client = new APIClient({\n      teamId: credentials.teamId,\n      token: credentials.token,\n    });\n\n    const sandbox = await client.getSnapshot({\n      snapshotId: params.snapshotId,\n      signal: params.signal,\n    });\n\n    return new Snapshot({\n      client,\n      snapshot: sandbox.json.snapshot,\n    });\n  }\n\n  /**\n   * Delete this snapshot.\n   *\n   * @param opts - Optional parameters.\n   * @param opts.signal - An AbortSignal to cancel the operation.\n   * @returns A promise that resolves once the snapshot has been deleted.\n   */\n  async delete(opts?: { signal?: AbortSignal }): Promise<void> {\n    \"use step\";\n    const client = await this.ensureClient();\n    const response = await client.deleteSnapshot({\n      snapshotId: this.snapshot.id,\n      signal: opts?.signal,\n    });\n\n    this.snapshot = response.json.snapshot;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;AA4BA,IAAa,WAAb,MAAa,SAAS;;;;;;;CASpB,MAAc,eAAmC;AAC/C;AACA,MAAI,KAAK,QAAS,QAAO,KAAK;EAC9B,MAAM,cAAc,MAAMA,wCAAgB;AAC1C,OAAK,UAAU,IAAIC,6BAAU;GAC3B,QAAQ,YAAY;GACpB,OAAO,YAAY;GACpB,CAAC;AACF,SAAO,KAAK;;;;;CAMd,IAAW,aAAqB;AAC9B,SAAO,KAAK,SAAS;;;;;CAMvB,IAAW,kBAA0B;AACnC,SAAO,KAAK,SAAS;;;;;CAMvB,IAAW,SAAqC;AAC9C,SAAO,KAAK,SAAS;;;;;CAMvB,IAAW,YAAoB;AAC7B,SAAO,KAAK,SAAS;;;;;CAMvB,IAAW,YAAkB;AAC3B,SAAO,IAAI,KAAK,KAAK,SAAS,UAAU;;;;;CAM1C,IAAW,YAA8B;AACvC,MAAI,KAAK,SAAS,cAAc,OAC9B;AAGF,SAAO,IAAI,KAAK,KAAK,SAAS,UAAU;;;;;;;;CAc1C,QAAQC,qCAAoB,UAAwC;AAClE,SAAO,EACL,UAAU,SAAS,UACpB;;;;;;;;;;;CAYH,QAAQC,uCAAsB,MAAoC;AAChE,SAAO,IAAI,SAAS,EAClB,UAAU,KAAK,UAChB,CAAC;;CAGJ,YAAY,EACV,QACA,YAIC;OAvGK,UAA4B;AAwGlC,OAAK,UAAU,UAAU;AACzB,OAAK,WAAW;;;;;;;CAQlB,aAAa,KACX,QAGA;AACA;EACA,MAAM,cAAc,MAAMH,uCAAe,OAAO;AAMhD,SALe,IAAIC,6BAAU;GAC3B,QAAQ,YAAY;GACpB,OAAO,YAAY;GACnB,OAAO,QAAQ;GAChB,CAAC,CACY,cAAc;GAC1B,GAAG;GACH,GAAG;GACJ,CAAC;;;;;;;;CASJ,aAAa,IACX,QACmB;AACnB;EACA,MAAM,cAAc,MAAMD,uCAAe,OAAO;EAChD,MAAM,SAAS,IAAIC,6BAAU;GAC3B,QAAQ,YAAY;GACpB,OAAO,YAAY;GACpB,CAAC;AAOF,SAAO,IAAI,SAAS;GAClB;GACA,WAPc,MAAM,OAAO,YAAY;IACvC,YAAY,OAAO;IACnB,QAAQ,OAAO;IAChB,CAAC,EAIkB,KAAK;GACxB,CAAC;;;;;;;;;CAUJ,MAAM,OAAO,MAAgD;AAC3D;AAOA,OAAK,YALY,OADF,MAAM,KAAK,cAAc,EACV,eAAe;GAC3C,YAAY,KAAK,SAAS;GAC1B,QAAQ,MAAM;GACf,CAAC,EAEuB,KAAK"}

package/dist/snapshot.d.cts

@@ -2,8 +2,12 @@ import { Parsed } from "./api-client/base-client.cjs";
 import { SnapshotMetadata } from "./api-client/validators.cjs";
 import { APIClient, WithFetchOptions } from "./api-client/api-client.cjs";
 import { Credentials } from "./utils/get-credentials.cjs";
+import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from "@workflow/serde";
 
 //#region src/snapshot.d.ts
+interface SerializedSnapshot {
+  snapshot: SnapshotMetadata;
+}
 /** @inline */
 interface GetSnapshotParams {
   /**
@@ -22,7 +26,14 @@ interface GetSnapshotParams {
  * @hideconstructor
  */
 declare class Snapshot {
-  private readonly client;
+  private _client;
+  /**
+   * Lazily resolve credentials and construct an API client.
+   * This is used in step contexts where the Snapshot was deserialized
+   * without a client (e.g. when crossing workflow/step boundaries).
+   * @internal
+   */
+  private ensureClient;
   /**
    * Unique ID of this snapshot.
    */
@@ -52,16 +63,27 @@ declare class Snapshot {
    */
   private snapshot;
   /**
-   * Create a new Snapshot instance.
+   * Serialize a Snapshot instance to plain data for @workflow/serde.
+   *
+   * @param instance - The Snapshot instance to serialize
+   * @returns A plain object containing snapshot metadata
+   */
+  static [WORKFLOW_SERIALIZE](instance: Snapshot): SerializedSnapshot;
+  /**
+   * Deserialize a Snapshot from serialized data.
+   *
+   * The deserialized instance uses the serialized metadata synchronously and
+   * lazily creates an API client only when methods perform API requests.
    *
-   * @param client - API client used to communicate with the backend
-   * @param snapshot - Snapshot metadata
+   * @param data - The serialized snapshot data
+   * @returns The reconstructed Snapshot instance
    */
+  static [WORKFLOW_DESERIALIZE](data: SerializedSnapshot): Snapshot;
   constructor({
     client,
     snapshot
   }: {
-    client: APIClient;
+    client?: APIClient;
     snapshot: SnapshotMetadata;
   });
   /**
@@ -105,5 +127,5 @@ declare class Snapshot {
   }): Promise<void>;
 }
 //#endregion
-export { Snapshot };
+export { SerializedSnapshot, Snapshot };
 //# sourceMappingURL=snapshot.d.cts.map