@gigadrive/sdk 0.9.5 → 0.10.0

package/dist/index.mjs

@@ -466,6 +466,16 @@ var HttpClient = class {
     }
     return response;
   }
+  /**
+   * Fetch an arbitrary URL without authentication and without throwing on a
+   * non-2xx status, using the client's configured `fetch`. Used to probe
+   * public URLs such as microVM preview URLs.
+   *
+   * @internal
+   */
+  async fetchPublic(url, init) {
+    return this.fetchFn(url, init);
+  }
   async request(method, path, options) {
     const response = await this.fetchWithAuth(method, path, options);
     return this.handleResponse(response);
@@ -490,8 +500,9 @@ var HttpClient = class {
       }
     }
     const signal = options?.signal;
-    const response = await this.fetchFn(url, { method, headers, body: requestBody, signal });
     const bodyIsOneShot = typeof ReadableStream !== "undefined" && requestBody instanceof ReadableStream;
+    const init = bodyIsOneShot ? { method, headers, body: requestBody, signal, duplex: "half" } : { method, headers, body: requestBody, signal };
+    const response = await this.fetchFn(url, init);
     if (response.status === 401 && !bodyIsOneShot) {
       this.tokenManager.invalidate();
       const retryToken = await this.tokenManager.getToken();
@@ -552,12 +563,265 @@ var HttpClient = class {
   }
 };
 
+// src/resources/base-resource.ts
+var BaseResource = class {
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  httpClient;
+};
+
+// src/microvms/duration.ts
+var PATTERN = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h)$/;
+var UNIT_MS = { ms: 1, s: 1e3, m: 6e4, h: 36e5 };
+var durationToMs = (value) => {
+  let ms;
+  if (typeof value === "number") {
+    ms = value;
+  } else {
+    const match = PATTERN.exec(value.trim());
+    if (!match)
+      throw new RangeError(`Invalid duration "${value}". Use milliseconds or a string such as 30s, 10m or 2h.`);
+    ms = Number(match[1]) * UNIT_MS[match[2]];
+  }
+  if (!Number.isFinite(ms) || ms < 0) throw new RangeError(`Invalid duration "${String(value)}"`);
+  return Math.ceil(ms);
+};
+var MICROVM_MAX_TIMEOUT_MS = 24 * 36e5;
+var microvmTimeoutMs = (value) => {
+  const ms = durationToMs(value);
+  if (ms < 1 || ms > MICROVM_MAX_TIMEOUT_MS) {
+    throw new RangeError(`A microVM timeout must be between 1 ms and 24 hours (got ${String(value)}).`);
+  }
+  return ms;
+};
+var sleep = (ms, signal) => new Promise((resolve, reject) => {
+  if (signal?.aborted) {
+    reject(abortReason(signal));
+    return;
+  }
+  const onAbort = () => {
+    clearTimeout(timer);
+    reject(abortReason(signal));
+  };
+  const timer = setTimeout(() => {
+    signal?.removeEventListener("abort", onAbort);
+    resolve();
+  }, ms);
+  signal?.addEventListener("abort", onAbort, { once: true });
+});
+var abortReason = (signal) => {
+  const reason = signal?.reason;
+  if (reason instanceof Error) return reason;
+  const error = new Error(typeof reason === "string" ? reason : "The operation was aborted");
+  error.name = "AbortError";
+  return error;
+};
+
+// src/microvms/errors.ts
+var MicroVmNotRunningError = class extends ApiError {
+  constructor(message = "The microVM is not running", code = "microvm_not_running", reason) {
+    super(message, 409, code, reason);
+    this.name = "MicroVmNotRunningError";
+  }
+};
+var MicroVmNotFoundError = class extends ApiError {
+  constructor(message = "Not found", code, reason) {
+    super(message, 404, code, reason);
+    this.name = "MicroVmNotFoundError";
+  }
+};
+var MicroVmFileNotFoundError = class extends MicroVmNotFoundError {
+  /** The path that was not found. */
+  path;
+  constructor(path, message = `No such file or directory: ${path}`, code) {
+    super(message, code);
+    this.name = "MicroVmFileNotFoundError";
+    this.path = path;
+  }
+};
+var MicroVmBusyError = class extends ApiError {
+  constructor(message, status, code = "microvm_busy", reason) {
+    super(message, status, code, reason);
+    this.name = "MicroVmBusyError";
+  }
+};
+var MicroVmUnreachableError = class extends ApiError {
+  constructor(message, code = "microvm_unreachable", reason) {
+    super(message, 502, code, reason);
+    this.name = "MicroVmUnreachableError";
+  }
+};
+var MicroVmImageNotReadyError = class extends ApiError {
+  constructor(message, code = "image_not_ready", reason) {
+    super(message, 409, code, reason);
+    this.name = "MicroVmImageNotReadyError";
+  }
+};
+var MicroVmQuotaExceededError = class extends ApiError {
+  constructor(message, status, code, reason) {
+    super(message, status, code, reason);
+    this.name = "MicroVmQuotaExceededError";
+  }
+};
+var CommandFailedError = class _CommandFailedError extends GigadriveError {
+  commandId;
+  /** Exit code, or `null` when a signal killed the process. */
+  exitCode;
+  signal;
+  stdout;
+  stderr;
+  constructor(output, label = "Command") {
+    const how = output.exitCode !== null ? `exited with code ${output.exitCode}` : `was killed by ${output.signal ?? "a signal"}`;
+    const tail = output.stderr.trim().split("\n").slice(-5).join("\n");
+    super(tail ? `${label} ${how}:
+${tail}` : `${label} ${how}`);
+    this.name = "CommandFailedError";
+    this.commandId = output.commandId;
+    this.exitCode = output.exitCode;
+    this.signal = output.signal;
+    this.stdout = output.stdout;
+    this.stderr = output.stderr;
+  }
+  /** Builds the error from a finished command whose output was not collected. */
+  static fromInfo(info) {
+    return new _CommandFailedError({
+      commandId: info.id,
+      exitCode: info.exitCode,
+      signal: info.signal,
+      stdout: "",
+      stderr: "",
+      durationMs: 0
+    });
+  }
+};
+var MicroVmTimeoutError = class extends GigadriveError {
+  constructor(message) {
+    super(message);
+    this.name = "MicroVmTimeoutError";
+  }
+};
+var MicroVmPortNotExposedError = class extends GigadriveError {
+  port;
+  constructor(port, exposed) {
+    super(
+      exposed.length === 0 ? `Port ${port} is not exposed: this microVM exposes no ports. Pass \`ports: [${port}]\` when creating it.` : `Port ${port} is not exposed. Exposed ports: ${exposed.join(", ")}.`
+    );
+    this.name = "MicroVmPortNotExposedError";
+    this.port = port;
+  }
+};
+var MicroVmStartError = class extends GigadriveError {
+  microvmId;
+  status;
+  stopReason;
+  constructor(microvmId, status, stopReason) {
+    super(`The microVM ${microvmId} is ${status}${stopReason ? ` (${stopReason})` : ""}`);
+    this.name = "MicroVmStartError";
+    this.microvmId = microvmId;
+    this.status = status;
+    this.stopReason = stopReason;
+  }
+};
+var MicroVmCleanupError = class extends GigadriveError {
+  microvmId;
+  /** Why deleting the microVM failed. {@link Error.cause} is why creating it failed. */
+  cleanupError;
+  constructor(microvmId, cause, cleanupError) {
+    super(
+      `Creating the microVM ${microvmId} failed and deleting it failed too. Delete it with MicroVM.get('${microvmId}') and delete().`
+    );
+    this.name = "MicroVmCleanupError";
+    this.microvmId = microvmId;
+    this.cleanupError = cleanupError;
+    this.cause = cause;
+  }
+};
+var MicroVmImageBuildError = class extends GigadriveError {
+  imageId;
+  constructor(imageId, message) {
+    super(`The image build failed${message ? `: ${message}` : ""}`);
+    this.name = "MicroVmImageBuildError";
+    this.imageId = imageId;
+  }
+};
+var NOT_RUNNING = /microvm[_ ]not[_ ]running|not running/i;
+var toMicroVmError = (error, filePath) => {
+  if (!(error instanceof ApiError) || Object.getPrototypeOf(error) !== ApiError.prototype) return error;
+  const { message, status, code, reason } = error;
+  if (code === "microvm_busy") return new MicroVmBusyError(message, status, code, reason);
+  if (code === "microvm_unreachable") return new MicroVmUnreachableError(message, code, reason);
+  if (code === "image_not_ready") return new MicroVmImageNotReadyError(message, code, reason);
+  if (code === "quota_exceeded" || code === "plan_limit_exceeded") {
+    return new MicroVmQuotaExceededError(message, status, code, reason);
+  }
+  if (status === 409 && (code === "microvm_not_running" || code === void 0 && NOT_RUNNING.test(message))) {
+    return new MicroVmNotRunningError(message, code ?? "microvm_not_running", reason);
+  }
+  if (status === 404) {
+    const vmMissing = code === "not_found" || code === "microvm_not_found";
+    return filePath !== void 0 && !vmMissing ? new MicroVmFileNotFoundError(filePath, message, code) : new MicroVmNotFoundError(message, code, reason);
+  }
+  return error;
+};
+
+// src/queues/encoding.ts
+var DURATION_PATTERN = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)$/;
+var UNIT_SECONDS = { ms: 1e-3, s: 1, m: 60, h: 3600, d: 86400 };
+var durationToSeconds = (value) => {
+  let seconds;
+  if (typeof value === "number") {
+    seconds = value;
+  } else {
+    const match = DURATION_PATTERN.exec(value.trim());
+    if (!match) throw new Error(`Invalid duration "${value}". Use seconds or a string such as 30s, 10m, 12h or 7d.`);
+    seconds = Number(match[1]) * UNIT_SECONDS[match[2]];
+  }
+  if (!Number.isFinite(seconds) || seconds < 0) throw new Error(`Invalid duration "${String(value)}"`);
+  return Math.ceil(seconds);
+};
+var textEncoder = new TextEncoder();
+var textDecoder = new TextDecoder();
+var utf8Encode = (value) => textEncoder.encode(value);
+var utf8Decode = (bytes) => textDecoder.decode(bytes);
+var bytesToBase64 = (bytes) => {
+  let binary = "";
+  for (let index = 0; index < bytes.length; index += 32768) {
+    binary += String.fromCharCode(...bytes.subarray(index, index + 32768));
+  }
+  return btoa(binary);
+};
+var base64ToBytes = (value) => {
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
+  return bytes;
+};
+var toHex = (buffer) => Array.from(new Uint8Array(buffer), (byte) => byte.toString(16).padStart(2, "0")).join("");
+var toArrayBuffer = (bytes) => {
+  const copy = new ArrayBuffer(bytes.byteLength);
+  new Uint8Array(copy).set(bytes);
+  return copy;
+};
+
 // src/streaming.ts
-var extractData = (rawEvent) => {
-  const dataLines = rawEvent.split("\n").filter((line) => line.startsWith("data:")).map((line) => line.slice("data:".length).replace(/^ /, ""));
-  if (dataLines.length === 0) return null;
-  const joined = dataLines.join("\n");
-  return joined.trim().length === 0 ? null : joined;
+var parseBlock = (rawEvent) => {
+  let event = "message";
+  let id;
+  let retry;
+  const data = [];
+  for (const line of rawEvent.split("\n")) {
+    if (line === "" || line.startsWith(":")) continue;
+    const colon = line.indexOf(":");
+    const field = colon === -1 ? line : line.slice(0, colon);
+    const value = colon === -1 ? "" : line.slice(colon + 1).replace(/^ /, "");
+    if (field === "data") data.push(value);
+    else if (field === "event") event = value || "message";
+    else if (field === "id" && !value.includes("\0")) id = value;
+    else if (field === "retry" && /^\d+$/.test(value)) retry = Number(value);
+  }
+  if (data.length === 0) return null;
+  return { event, data: data.join("\n"), id, retry };
 };
 var parseEvent = (data) => {
   try {
@@ -567,7 +831,7 @@ var parseEvent = (data) => {
     throw new Error(`Failed to parse streamed SSE data as JSON: ${message}`);
   }
 };
-async function* parseSSEStream(response) {
+async function* readEventBlocks(response) {
   const body = response.body;
   if (!body) {
     throw new Error("The response has no readable body to stream.");
@@ -575,44 +839,546 @@ async function* parseSSEStream(response) {
   const reader = body.getReader();
   const decoder = new TextDecoder();
   let buffer = "";
-  const drain = function* (flush) {
-    let separator = buffer.indexOf("\n\n");
-    while (separator !== -1) {
-      const rawEvent = buffer.slice(0, separator);
-      buffer = buffer.slice(separator + 2);
-      const data = extractData(rawEvent);
-      if (data !== null && data !== "[DONE]") {
-        yield parseEvent(data);
-      }
-      separator = buffer.indexOf("\n\n");
-    }
-    if (flush) {
-      const data = extractData(buffer);
-      buffer = "";
-      if (data !== null && data !== "[DONE]") {
-        yield parseEvent(data);
-      }
-    }
-  };
   try {
     for (; ; ) {
       const { done, value } = await reader.read();
       if (done) break;
       buffer = (buffer + decoder.decode(value, { stream: true })).replace(/\r\n/g, "\n");
-      yield* drain(false);
+      let separator = buffer.indexOf("\n\n");
+      while (separator !== -1) {
+        yield buffer.slice(0, separator);
+        buffer = buffer.slice(separator + 2);
+        separator = buffer.indexOf("\n\n");
+      }
     }
-    yield* drain(true);
+    buffer += decoder.decode();
+    if (buffer.length > 0) yield buffer;
   } finally {
     await reader.cancel().catch(() => void 0);
   }
 }
+async function* parseSSEEvents(response) {
+  for await (const block of readEventBlocks(response)) {
+    const event = parseBlock(block);
+    if (event) yield event;
+  }
+}
+async function* parseSSEStream(response) {
+  for await (const event of parseSSEEvents(response)) {
+    if (event.data.trim().length === 0 || event.data === "[DONE]") continue;
+    yield parseEvent(event.data);
+  }
+}
 
-// src/resources/base-resource.ts
-var BaseResource = class {
-  constructor(httpClient) {
-    this.httpClient = httpClient;
+// src/microvms/logs.ts
+var RECONNECT_DELAYS_MS = [100, 250, 500, 1e3, 2e3];
+var isRetryable = (error) => {
+  if (error instanceof ApiError) return error.status === 408 || error.status === 429 || error.status >= 500;
+  if (error instanceof Error && error.name === "AbortError") return false;
+  return true;
+};
+var parseJson = (data) => {
+  try {
+    const value = JSON.parse(data);
+    return value !== null && typeof value === "object" ? value : null;
+  } catch {
+    return null;
+  }
+};
+async function* streamCommandLogs(open, options = {}) {
+  const follow = options.follow ?? true;
+  const reconnect = options.reconnect ?? true;
+  const maxAttempts = options.maxReconnectAttempts ?? 5;
+  const next = {
+    stdout: options.stdoutOffset ?? 0,
+    stderr: options.stderrOffset ?? 0
+  };
+  let failures = 0;
+  for (; ; ) {
+    let progressed = false;
+    let serverError;
+    try {
+      const response = await open({
+        follow,
+        stdoutOffset: next.stdout,
+        stderrOffset: next.stderr,
+        signal: options.signal
+      });
+      for await (const event of parseSSEEvents(response)) {
+        if (event.event === "stdout" || event.event === "stderr") {
+          const payload = parseJson(event.data);
+          if (!payload || typeof payload.data !== "string") continue;
+          const stream = event.event;
+          let data = base64ToBytes(payload.data);
+          let offset = typeof payload.offset === "number" ? payload.offset : next[stream];
+          progressed = true;
+          if (offset < next[stream]) {
+            const skip = next[stream] - offset;
+            if (skip >= data.length) continue;
+            data = data.subarray(skip);
+            offset = next[stream];
+          }
+          next[stream] = offset + data.length;
+          if (data.length > 0) yield { type: "output", stream, data, offset };
+        } else if (event.event === "truncated") {
+          progressed = true;
+          yield { type: "truncated" };
+        } else if (event.event === "end") {
+          const payload = parseJson(event.data);
+          yield { type: "end", reason: typeof payload?.reason === "string" ? payload.reason : "snapshot" };
+          return;
+        } else if (event.event === "exit") {
+          const payload = parseJson(event.data) ?? {};
+          yield {
+            type: "exit",
+            exitCode: typeof payload.exitCode === "number" ? payload.exitCode : null,
+            signal: typeof payload.signal === "string" ? payload.signal : null,
+            ...typeof payload.timedOut === "boolean" && { timedOut: payload.timedOut },
+            ...(typeof payload.finishedAt === "string" || payload.finishedAt === null) && {
+              finishedAt: payload.finishedAt
+            }
+          };
+          return;
+        } else if (event.event === "error") {
+          const payload = parseJson(event.data);
+          const message = typeof payload?.message === "string" ? payload.message : typeof payload?.error === "string" ? payload.error : event.data;
+          const failure = new ApiError(message, 502, typeof payload?.code === "string" ? payload.code : void 0);
+          if (payload?.retryable !== true) serverError = failure;
+          throw failure;
+        }
+      }
+      if (!follow || !reconnect) return;
+      const exit = progressed ? null : await options.resolveExit?.();
+      if (exit) {
+        yield { type: "exit", exitCode: exit.exitCode, signal: exit.signal };
+        return;
+      }
+    } catch (error) {
+      if (error === serverError || options.signal?.aborted || !reconnect || !isRetryable(error)) throw error;
+      if (!progressed && failures >= maxAttempts) throw error;
+    }
+    failures = progressed ? 0 : failures + 1;
+    if (failures > maxAttempts) {
+      throw new ApiError("The command log stream kept closing without output", 502, "log_stream_closed");
+    }
+    await sleep(RECONNECT_DELAYS_MS[Math.min(failures, RECONNECT_DELAYS_MS.length - 1)], options.signal);
+  }
+}
+
+// src/microvms/resource.ts
+var vmPath = (microvmId) => `/microvms/${encodeURIComponent(microvmId)}`;
+var commandPath = (microvmId, commandId) => `${vmPath(microvmId)}/commands/${encodeURIComponent(commandId)}`;
+var typed = (promise, filePath) => promise.catch((error) => {
+  throw toMicroVmError(error, filePath);
+});
+var BUSY_RETRY_DELAYS_MS = [250, 500, 1e3, 2e3, 4e3];
+var read = async (run, signal, filePath) => {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      return await typed(run(), filePath);
+    } catch (error) {
+      if (!(error instanceof MicroVmBusyError) || attempt >= BUSY_RETRY_DELAYS_MS.length || signal?.aborted) {
+        throw error;
+      }
+      await sleep(BUSY_RETRY_DELAYS_MS[attempt], signal);
+    }
+  }
+};
+var unwrapList = (body, key = "data") => {
+  if (Array.isArray(body)) return body;
+  if (body && typeof body === "object") {
+    const record = body;
+    const list = record[key] ?? record.data ?? record.items;
+    if (Array.isArray(list)) return list;
+  }
+  return [];
+};
+var normalizeCommand = (raw) => {
+  const withId = raw.id === void 0 && raw.commandId !== void 0 ? { ...raw, id: raw.commandId } : raw;
+  return typeof withId.timedOut === "boolean" ? withId : { ...withId, timedOut: false };
+};
+var MicroVmCommandsResource = class extends BaseResource {
+  /**
+   * Run a command and wait for it to exit (`POST /microvms/:id/commands`, `wait: true`).
+   *
+   * @example
+   * ```ts
+   * const { exitCode, stdout } = await client.microvms.commands.run(id, { cmd: 'node', args: ['-v'] });
+   * ```
+   */
+  run(microvmId, input, options = {}) {
+    return typed(
+      this.httpClient.post(`${vmPath(microvmId)}/commands`, { ...input, wait: true }, options)
+    );
+  }
+  /**
+   * Start a detached command and return at once (`POST /microvms/:id/commands`, `wait: false`).
+   * Follow its output with {@link logs}.
+   */
+  async start(microvmId, input, options = {}) {
+    const raw = await typed(
+      this.httpClient.post(`${vmPath(microvmId)}/commands`, { ...input, wait: false }, options)
+    );
+    return normalizeCommand(raw);
+  }
+  /** List the microVM's commands, newest first (`GET /microvms/:id/commands`). */
+  async list(microvmId, options = {}) {
+    const body = await read(
+      () => this.httpClient.get(`${vmPath(microvmId)}/commands`, options),
+      options.signal
+    );
+    return unwrapList(body).map(normalizeCommand);
+  }
+  /** Get one command (`GET /microvms/:id/commands/:cmdId`). */
+  async get(microvmId, commandId, options = {}) {
+    return normalizeCommand(
+      await read(() => this.httpClient.get(commandPath(microvmId, commandId), options), options.signal)
+    );
+  }
+  /**
+   * Stream a command's output (`GET /microvms/:id/commands/:cmdId/logs`, SSE).
+   *
+   * Yields `output` events with the raw bytes and a final `exit` event. A
+   * dropped connection is reopened from the last received offsets, so no byte
+   * is lost or repeated; pass `reconnect: false` to disable that.
+   *
+   * @example
+   * ```ts
+   * for await (const event of client.microvms.commands.logs(id, commandId)) {
+   *   if (event.type === 'output') process.stdout.write(event.data);
+   *   else console.log('exit', event.exitCode);
+   * }
+   * ```
+   */
+  logs(microvmId, commandId, options = {}) {
+    return streamCommandLogs(
+      ({ follow, stdoutOffset, stderrOffset, signal }) => typed(
+        this.httpClient.requestStream("GET", `${commandPath(microvmId, commandId)}/logs`, {
+          query: { follow, stdoutOffset, stderrOffset },
+          headers: { Accept: "text/event-stream" },
+          signal
+        })
+      ),
+      {
+        ...options,
+        resolveExit: options.resolveExit ?? (async () => {
+          const info = await this.get(microvmId, commandId);
+          return info.status === "exited" ? { exitCode: info.exitCode, signal: info.signal } : null;
+        })
+      }
+    );
+  }
+  /**
+   * Wait up to `timeoutMs` (at most 60000) for the command to exit
+   * (`POST /microvms/:id/commands/:cmdId/wait`). The returned command is still
+   * `running` when the wait timed out.
+   */
+  async wait(microvmId, commandId, options = {}) {
+    const { signal, timeoutMs } = options;
+    const raw = await read(
+      () => this.httpClient.post(
+        `${commandPath(microvmId, commandId)}/wait`,
+        timeoutMs === void 0 ? {} : { timeoutMs },
+        { signal }
+      ),
+      signal
+    );
+    return normalizeCommand(raw);
+  }
+  /**
+   * Write to the command's stdin (`POST /microvms/:id/commands/:cmdId/stdin`).
+   * The command must have been started with `stdin: true` or a `pty`.
+   *
+   * @param options.eof - Close stdin after writing.
+   */
+  async stdin(microvmId, commandId, data, options = {}) {
+    await typed(
+      this.httpClient.post(`${commandPath(microvmId, commandId)}/stdin`, data, {
+        headers: { "Content-Type": "application/octet-stream" },
+        query: { eof: options.eof ? true : void 0 },
+        signal: options.signal
+      })
+    );
+  }
+  /** Send a signal to the command's process group (`POST /microvms/:id/commands/:cmdId/signal`). */
+  async signal(microvmId, commandId, signal, options = {}) {
+    await typed(this.httpClient.post(`${commandPath(microvmId, commandId)}/signal`, { signal }, options));
+  }
+  /** Resize a PTY command's terminal (`POST /microvms/:id/commands/:cmdId/resize`). */
+  async resize(microvmId, commandId, size, options = {}) {
+    await typed(
+      this.httpClient.post(
+        `${commandPath(microvmId, commandId)}/resize`,
+        { cols: size.cols, rows: size.rows },
+        options
+      )
+    );
+  }
+};
+var modeString = (mode) => typeof mode === "number" ? mode.toString(8).padStart(4, "0") : mode;
+var MicroVmFilesResource = class extends BaseResource {
+  /** Read a file as bytes (`GET /microvms/:id/files/content`). */
+  async read(microvmId, path, options = {}) {
+    const response = await this.open(microvmId, path, options);
+    return new Uint8Array(await response.arrayBuffer());
+  }
+  /** Read a file as a stream of bytes, without buffering it (`GET /microvms/:id/files/content`). */
+  async readStream(microvmId, path, options = {}) {
+    const response = await this.open(microvmId, path, options);
+    if (!response.body) return new Blob([]).stream();
+    return response.body;
+  }
+  /**
+   * Write a file, replacing it atomically (`PUT /microvms/:id/files/content`).
+   * Missing parent directories are created unless `mkdirs: false`.
+   */
+  write(microvmId, path, content, options = {}) {
+    return typed(
+      this.httpClient.put(`${vmPath(microvmId)}/files/content`, content, {
+        headers: { "Content-Type": "application/octet-stream" },
+        query: { path, mode: modeString(options.mode), mkdirs: options.mkdirs === false ? false : void 0 },
+        signal: options.signal
+      }),
+      path
+    );
+  }
+  /**
+   * List a directory (`GET /microvms/:id/files`). `truncated` is set when the
+   * listing hit its size limit; list a narrower directory then.
+   */
+  async list(microvmId, path, options = {}) {
+    const body = await read(
+      () => this.httpClient.get(`${vmPath(microvmId)}/files`, {
+        query: { path, recursive: options.recursive ? true : void 0, depth: options.depth },
+        signal: options.signal
+      }),
+      options.signal,
+      path
+    );
+    const truncated = body?.truncated === true;
+    return { entries: unwrapList(body, "entries"), truncated };
+  }
+  /** Describe a file or directory without following a final symlink (`GET /microvms/:id/files/stat`). */
+  stat(microvmId, path, options = {}) {
+    return read(
+      () => this.httpClient.get(`${vmPath(microvmId)}/files/stat`, { query: { path }, signal: options.signal }),
+      options.signal,
+      path
+    );
+  }
+  /** Create a directory, with its parents unless `parents: false` (`POST /microvms/:id/files/mkdir`). */
+  mkdir(microvmId, path, options = {}) {
+    const body = options.parents === void 0 ? { path } : { path, parents: options.parents };
+    return typed(this.httpClient.post(`${vmPath(microvmId)}/files/mkdir`, body, options), path);
+  }
+  /** Move or rename a file or directory (`POST /microvms/:id/files/move`). */
+  move(microvmId, from, to, options = {}) {
+    return typed(this.httpClient.post(`${vmPath(microvmId)}/files/move`, { from, to }, options), from);
+  }
+  /** Delete a file, or a directory (non-empty ones need `recursive`) (`DELETE /microvms/:id/files`). */
+  async remove(microvmId, path, options = {}) {
+    await typed(
+      this.httpClient.delete(`${vmPath(microvmId)}/files`, {
+        query: { path, recursive: options.recursive ? true : void 0 },
+        signal: options.signal
+      }),
+      path
+    );
+  }
+  open(microvmId, path, options) {
+    return read(
+      () => this.httpClient.requestStream("GET", `${vmPath(microvmId)}/files/content`, {
+        query: { path, offset: options.offset, length: options.length },
+        signal: options.signal
+      }),
+      options.signal,
+      path
+    );
+  }
+};
+var toImageSource = (input) => {
+  if (input.source) return input.source;
+  const from = input.from;
+  if (typeof from === "string") return { type: "registry", ref: from };
+  if (from && "dockerfile" in from) return { type: "dockerfile", dockerfile: from.dockerfile };
+  if (from && "registry" in from) return { type: "registry", ref: from.registry };
+  throw new TypeError("Pass `from` (a registry reference or { dockerfile }) or `source` to create an image.");
+};
+var MicroVmImagesResource = class extends BaseResource {
+  defaultApplicationId;
+  constructor(httpClient, defaultApplicationId) {
+    super(httpClient);
+    this.defaultApplicationId = defaultApplicationId || void 0;
+  }
+  /** List the built-in images and the application's custom images (`GET /microvm-images`). */
+  async list(query = {}, options = {}) {
+    const body = await read(
+      () => this.httpClient.get("/microvm-images", {
+        query: { applicationId: query.applicationId ?? this.defaultApplicationId },
+        signal: options.signal
+      }),
+      options.signal
+    );
+    return unwrapList(body);
+  }
+  /**
+   * Start building a custom image (`POST /microvm-images`). The image is
+   * `building` until {@link waitUntilReady} resolves.
+   *
+   * @example
+   * ```ts
+   * const image = await client.microvms.images.create({ name: 'py-ml', from: 'python:3.13' });
+   * await client.microvms.images.waitUntilReady(image.id);
+   * const vm = await MicroVM.create({ image: 'py-ml' });
+   * ```
+   */
+  async create(input, options = {}) {
+    const applicationId = input.applicationId ?? this.defaultApplicationId;
+    const source = toImageSource(input);
+    return await typed(
+      this.httpClient.post(
+        "/microvm-images",
+        { ...applicationId ? { applicationId } : {}, name: input.name, source },
+        options
+      )
+    );
+  }
+  /** Get one image (`GET /microvm-images/:id`). */
+  get(imageId, options = {}) {
+    return read(
+      () => this.httpClient.get(`/microvm-images/${encodeURIComponent(imageId)}`, options),
+      options.signal
+    );
+  }
+  /** Delete a custom image (`DELETE /microvm-images/:id`). */
+  async delete(imageId, options = {}) {
+    await typed(this.httpClient.delete(`/microvm-images/${encodeURIComponent(imageId)}`, options));
+  }
+  /**
+   * Poll an image until its build finished.
+   *
+   * @throws {@link MicroVmImageBuildError} when the build failed.
+   * @throws {@link MicroVmTimeoutError} when it is still building after `timeout`.
+   */
+  async waitUntilReady(imageId, options = {}) {
+    const deadline = Date.now() + durationToMs(options.timeout ?? "15m");
+    const interval = durationToMs(options.interval ?? "2s");
+    let lastStatus;
+    for (; ; ) {
+      if (options.signal?.aborted) throw abortReason(options.signal);
+      const image = await this.get(imageId, { signal: options.signal });
+      if (image.status !== lastStatus) {
+        lastStatus = image.status;
+        options.onStatus?.(image);
+      }
+      if (image.status === "ready") return image;
+      if (image.status === "failed") throw new MicroVmImageBuildError(image.id, image.error);
+      if (Date.now() + interval > deadline) {
+        throw new MicroVmTimeoutError(`The image ${image.name} is still ${image.status}; gave up waiting.`);
+      }
+      await sleep(interval, options.signal);
+    }
+  }
+};
+var MicroVmsResource = class extends BaseResource {
+  /** Commands: run, start, logs, wait, stdin, signal, resize. */
+  commands;
+  /** Files: read, write, list, stat, mkdir, move, remove. */
+  files;
+  /** Built-in and custom images. */
+  images;
+  defaultApplicationId;
+  constructor(httpClient, defaultApplicationId) {
+    super(httpClient);
+    this.defaultApplicationId = defaultApplicationId || void 0;
+    this.commands = new MicroVmCommandsResource(httpClient);
+    this.files = new MicroVmFilesResource(httpClient);
+    this.images = new MicroVmImagesResource(httpClient, defaultApplicationId);
+  }
+  /**
+   * Create a microVM (`POST /microvms`). Resolves once it is `running`; with
+   * `wait: false` it resolves at once with a `starting` microVM.
+   *
+   * `applicationId` defaults to the client's `applicationId` or
+   * `GIGADRIVE_APPLICATION_ID`, and may be omitted entirely with application
+   * or deployment credentials.
+   */
+  create(input = {}, options = {}) {
+    const applicationId = input.applicationId ?? this.defaultApplicationId;
+    return typed(
+      this.httpClient.post("/microvms", applicationId ? { ...input, applicationId } : input, {
+        query: { wait: options.wait === false ? false : void 0 },
+        signal: options.signal
+      })
+    );
+  }
+  /** List one page of microVMs, newest first (`GET /microvms`). */
+  async list(query = {}, options = {}) {
+    const body = await read(
+      () => this.httpClient.get("/microvms", {
+        query: {
+          applicationId: query.applicationId ?? this.defaultApplicationId,
+          status: query.status,
+          cursor: query.cursor,
+          limit: query.limit
+        },
+        signal: options.signal
+      }),
+      options.signal
+    );
+    const nextCursor = body.pagination?.nextCursor ?? body.nextCursor ?? void 0;
+    const hasMore = body.pagination?.hasMore ?? nextCursor !== void 0;
+    return {
+      items: body.data ?? body.items ?? [],
+      ...nextCursor && hasMore ? { nextCursor } : {},
+      hasMore: hasMore && nextCursor !== void 0
+    };
+  }
+  /**
+   * Iterate every microVM across all pages.
+   *
+   * @example
+   * ```ts
+   * for await (const vm of client.microvms.listAll({ status: 'running' })) console.log(vm.id);
+   * ```
+   */
+  async *listAll(query = {}, options = {}) {
+    let cursor;
+    do {
+      const page = await this.list({ ...query, cursor }, options);
+      yield* page.items;
+      cursor = page.nextCursor;
+    } while (cursor);
+  }
+  /** Get one microVM (`GET /microvms/:id`). */
+  get(microvmId, options = {}) {
+    return read(() => this.httpClient.get(vmPath(microvmId), options), options.signal);
+  }
+  /**
+   * Set the remaining lifetime to `timeoutMs` from now (`POST /microvms/:id/timeout`),
+   * up to the plan's maximum lifetime.
+   */
+  extendTimeout(microvmId, timeoutMs, options = {}) {
+    return typed(this.httpClient.post(`${vmPath(microvmId)}/timeout`, { timeoutMs }, options));
+  }
+  /** Stop a microVM (`POST /microvms/:id/stop`). Its disk and memory are discarded. */
+  stop(microvmId, options = {}) {
+    return typed(this.httpClient.post(`${vmPath(microvmId)}/stop`, void 0, options));
+  }
+  /** Delete a microVM, stopping it first if needed (`DELETE /microvms/:id`). */
+  async delete(microvmId, options = {}) {
+    await typed(this.httpClient.delete(vmPath(microvmId), options));
+  }
+  /**
+   * Request a public preview URL with the client's `fetch`, without
+   * credentials and without throwing on error statuses. Used by
+   * `MicroVM.waitForPort`.
+   *
+   * @internal
+   */
+  fetchPreview(url, init) {
+    return this.httpClient.fetchPublic(url, init);
   }
-  httpClient;
 };
 
 // src/resources/ai-gateway/index.ts
@@ -897,7 +1663,7 @@ var ApplicationRequestsResource = class extends BaseResource {
 
 // src/upload/checksum.ts
 var EMPTY_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
-var toHex = (buffer) => {
+var toHex2 = (buffer) => {
   const bytes = new Uint8Array(buffer);
   let hex = "";
   for (let i = 0; i < bytes.length; i++) {
@@ -905,7 +1671,7 @@ var toHex = (buffer) => {
   }
   return hex;
 };
-var subtleDigest = async (algorithm, bytes) => toHex(await crypto.subtle.digest(algorithm, bytes));
+var subtleDigest = async (algorithm, bytes) => toHex2(await crypto.subtle.digest(algorithm, bytes));
 var importNodeCrypto = async () => {
   if (typeof process === "undefined" || !process.versions?.node) return null;
   try {
@@ -1714,7 +2480,7 @@ var pollSignal = (ms, signal) => {
     }
   };
 };
-var sleep = (ms, signal) => new Promise((resolve, reject) => {
+var sleep2 = (ms, signal) => new Promise((resolve, reject) => {
   if (signal?.aborted) {
     reject(signal.reason instanceof Error ? signal.reason : new GigadriveError("Aborted"));
     return;
@@ -1838,7 +2604,7 @@ var ApplicationDomainsResource = class extends BaseResource {
         if (last) throw new DomainNotActiveError(last, "timeout");
         throw new GigadriveError("Timed out before the domain could be read");
       }
-      await sleep(Math.min(intervalMs, untilDeadline), signal);
+      await sleep2(Math.min(intervalMs, untilDeadline), signal);
     }
   }
 };
@@ -2624,48 +3390,9 @@ var OrganizationsResource = class extends BaseResource {
    * console.log(org.id, org.slug);
    * ```
    */
-  async create(input) {
-    return this.httpClient.post("/organizations", input);
-  }
-};
-
-// src/queues/encoding.ts
-var DURATION_PATTERN = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)$/;
-var UNIT_SECONDS = { ms: 1e-3, s: 1, m: 60, h: 3600, d: 86400 };
-var durationToSeconds = (value) => {
-  let seconds;
-  if (typeof value === "number") {
-    seconds = value;
-  } else {
-    const match = DURATION_PATTERN.exec(value.trim());
-    if (!match) throw new Error(`Invalid duration "${value}". Use seconds or a string such as 30s, 10m, 12h or 7d.`);
-    seconds = Number(match[1]) * UNIT_SECONDS[match[2]];
-  }
-  if (!Number.isFinite(seconds) || seconds < 0) throw new Error(`Invalid duration "${String(value)}"`);
-  return Math.ceil(seconds);
-};
-var textEncoder = new TextEncoder();
-var textDecoder = new TextDecoder();
-var utf8Encode = (value) => textEncoder.encode(value);
-var utf8Decode = (bytes) => textDecoder.decode(bytes);
-var bytesToBase64 = (bytes) => {
-  let binary = "";
-  for (let index = 0; index < bytes.length; index += 32768) {
-    binary += String.fromCharCode(...bytes.subarray(index, index + 32768));
+  async create(input) {
+    return this.httpClient.post("/organizations", input);
   }
-  return btoa(binary);
-};
-var base64ToBytes = (value) => {
-  const binary = atob(value);
-  const bytes = new Uint8Array(binary.length);
-  for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
-  return bytes;
-};
-var toHex2 = (buffer) => Array.from(new Uint8Array(buffer), (byte) => byte.toString(16).padStart(2, "0")).join("");
-var toArrayBuffer = (bytes) => {
-  const copy = new ArrayBuffer(bytes.byteLength);
-  new Uint8Array(copy).set(bytes);
-  return copy;
 };
 
 // src/queues/errors.ts
@@ -2697,11 +3424,11 @@ var hmacSha256Hex = async (secret, payload) => {
     false,
     ["sign"]
   );
-  return toHex2(await crypto.subtle.sign("HMAC", key, toArrayBuffer(utf8Encode(payload))));
+  return toHex(await crypto.subtle.sign("HMAC", key, toArrayBuffer(utf8Encode(payload))));
 };
 var signedPayload = async (input, timestamp) => {
   const body = typeof input.body === "string" ? utf8Encode(input.body) : input.body;
-  const bodyHash = toHex2(await crypto.subtle.digest("SHA-256", toArrayBuffer(body)));
+  const bodyHash = toHex(await crypto.subtle.digest("SHA-256", toArrayBuffer(body)));
   return `${String(timestamp)}.${input.queue}.${input.messageId}.${String(input.attempt)}.${bodyHash}`;
 };
 var safeEqual = (left, right) => {
@@ -2784,7 +3511,7 @@ var ACK_FLUSH_MS = 25;
 var ACK_RETRY_DELAYS_MS = [200, 1e3];
 var EMPTY_POLL_MIN_MS = 1e3;
 var EMPTY_POLL_MAX_MS = 5e3;
-var sleep2 = (ms, signal) => new Promise((resolve) => {
+var sleep3 = (ms, signal) => new Promise((resolve) => {
   if (signal?.aborted) return resolve();
   const timer = setTimeout(done, ms);
   function done() {
@@ -2979,7 +3706,7 @@ var Queue = class {
           const retryable = !(error instanceof ApiError) || error.status >= 500 || error.status === 429;
           const delay2 = ACK_RETRY_DELAYS_MS[attempt];
           if (!retryable || delay2 === void 0) throw error;
-          await sleep2(delay2, void 0);
+          await sleep3(delay2, void 0);
         }
       }
     };
@@ -3019,7 +3746,7 @@ var Queue = class {
       if (messages.length === 0) {
         if (options.stopWhenEmpty) return;
         const remaining = Math.max(waitMs, EMPTY_POLL_MIN_MS) - (Date.now() - started);
-        if (remaining > 0) await sleep2(Math.min(remaining, EMPTY_POLL_MAX_MS), options.signal);
+        if (remaining > 0) await sleep3(Math.min(remaining, EMPTY_POLL_MAX_MS), options.signal);
         continue;
       }
       await Promise.all(
@@ -3455,6 +4182,12 @@ var GigadriveClient = class {
    * handle bound to one queue.
    */
   queues;
+  /**
+   * microVMs: isolated Linux machines to run commands in, move files to and
+   * from, and expose ports from. This is the low-level REST surface; the
+   * {@link MicroVM} class (`MicroVM.create({ client })`) is the friendlier API.
+   */
+  microvms;
   constructor(config = {}) {
     const baseUrl = config.baseUrl ?? readEnv("GIGADRIVE_API_BASE_URL") ?? DEFAULT_BASE_URL2;
     const applicationId = config.applicationId ?? readEnv("GIGADRIVE_APPLICATION_ID");
@@ -3471,6 +4204,687 @@ var GigadriveClient = class {
     this.stickySessions = new StickySessionsResource(httpClient);
     this.imageOptimization = new ImageOptimizationResource(httpClient);
     this.queues = new QueuesResource(httpClient, applicationId);
+    this.microvms = new MicroVmsResource(httpClient, applicationId);
+  }
+};
+
+// src/microvms/command.ts
+var MAX_WAIT_MS = 6e4;
+var toMs = (value) => {
+  if (value === null || value === void 0) return null;
+  const ms = typeof value === "number" ? value : Date.parse(value);
+  return Number.isFinite(ms) ? ms : null;
+};
+var commandDurationMs = (info) => {
+  const started = toMs(info.startedAt);
+  const finished = toMs(info.finishedAt);
+  return started !== null && finished !== null ? Math.max(0, finished - started) : null;
+};
+var Command = class {
+  /** @internal Use {@link MicroVM.spawn} or `vm.commands.get(id)`. */
+  constructor(resource, microvmId, info) {
+    this.resource = resource;
+    this.microvmId = microvmId;
+    this.current = info;
+  }
+  resource;
+  microvmId;
+  current;
+  pump;
+  pumpError;
+  skippedOutput = false;
+  /** Command id (`cmd_...`). Pass it to `vm.commands.get(id)` to reattach later. */
+  get id() {
+    return this.current.id;
+  }
+  /** The latest known state. Updated by {@link refresh}, {@link wait} and the end of {@link logs}. */
+  get info() {
+    return this.current;
+  }
+  get status() {
+    return this.current.status;
+  }
+  /** Exit code once exited; `null` while running or when a signal killed it. */
+  get exitCode() {
+    return this.current.exitCode;
+  }
+  /** Signal that killed the process, if any. */
+  get signal() {
+    return this.current.signal;
+  }
+  get pid() {
+    return this.current.pid;
+  }
+  /** Whether the command was killed because it ran past its `timeout`. */
+  get timedOut() {
+    return this.current.timedOut;
+  }
+  /**
+   * Whether a {@link logs} read found older output already dropped (each
+   * stream keeps its last 8 MiB), so what it delivered starts mid-stream.
+   */
+  get truncated() {
+    return this.skippedOutput;
+  }
+  /** Fetch the latest state from the API. */
+  async refresh() {
+    this.current = await this.resource.get(this.microvmId, this.id);
+    return this.current;
+  }
+  /**
+   * Stream the command's output, from the beginning of the retained output by
+   * default, until it exits. With `follow: false` it delivers what is
+   * buffered and ends, even while the command keeps running. Reconnects transparently after a dropped
+   * connection. Breaking out of the loop closes the stream; the command keeps
+   * running.
+   *
+   * @example
+   * ```ts
+   * for await (const { stream, text } of command.logs()) {
+   *   (stream === 'stdout' ? process.stdout : process.stderr).write(text);
+   * }
+   * ```
+   */
+  async *logs(options = {}) {
+    const decoders = { stdout: new TextDecoder(), stderr: new TextDecoder() };
+    for await (const event of this.resource.logs(this.microvmId, this.id, options)) {
+      if (event.type === "exit") {
+        this.current = {
+          ...this.current,
+          status: "exited",
+          exitCode: event.exitCode,
+          signal: event.signal,
+          ...event.timedOut !== void 0 && { timedOut: event.timedOut },
+          ...event.finishedAt !== void 0 && { finishedAt: event.finishedAt }
+        };
+        continue;
+      }
+      if (event.type === "truncated") {
+        this.skippedOutput = true;
+        continue;
+      }
+      if (event.type === "end") continue;
+      const text = decoders[event.stream].decode(event.data, { stream: true });
+      yield { stream: event.stream, data: event.data, text, offset: event.offset };
+    }
+  }
+  /**
+   * Collect the output from the start until the command exits.
+   *
+   * @example
+   * ```ts
+   * const { stdout } = await (await vm.spawn('ls', ['-la'])).output();
+   * ```
+   */
+  async output(options = {}) {
+    let stdout = "";
+    let stderr = "";
+    for await (const chunk of this.logs(options)) {
+      if (chunk.stream === "stdout") stdout += chunk.text;
+      else stderr += chunk.text;
+    }
+    return { stdout, stderr };
+  }
+  /** The complete stdout as text, once the command exited. */
+  async stdout(options = {}) {
+    return (await this.output(options)).stdout;
+  }
+  /** The complete stderr as text, once the command exited. */
+  async stderr(options = {}) {
+    return (await this.output(options)).stderr;
+  }
+  /**
+   * Wait for the command to exit and return its final state. Output callbacks
+   * given to `spawn` have received all output when this resolves.
+   *
+   * @throws {@link MicroVmTimeoutError} when `timeout` elapses first (the command keeps running).
+   * @throws {@link CommandFailedError} with `throwOnError` when it exits non-zero or is killed.
+   */
+  async wait(options = {}) {
+    const deadline = options.timeout === void 0 ? Infinity : Date.now() + durationToMs(options.timeout);
+    while (this.current.status !== "exited") {
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) {
+        throw new MicroVmTimeoutError(`The command ${this.id} is still running; gave up waiting.`);
+      }
+      this.current = await this.resource.wait(this.microvmId, this.id, {
+        timeoutMs: Math.min(MAX_WAIT_MS, remaining),
+        signal: options.signal
+      });
+    }
+    if (this.pump) {
+      await this.pump;
+      if (this.pumpError) throw this.pumpError;
+    }
+    if (options.throwOnError && this.current.exitCode !== 0) {
+      throw CommandFailedError.fromInfo(this.current);
+    }
+    return this.current;
+  }
+  /**
+   * Send a signal to the command's process group. Default `SIGTERM`; use
+   * `SIGKILL` to stop it unconditionally.
+   */
+  async kill(signal = "SIGTERM") {
+    await this.resource.signal(this.microvmId, this.id, signal);
+  }
+  /**
+   * Write to stdin. The command must have been spawned with `stdin: true` or a `pty`.
+   *
+   * @example
+   * ```ts
+   * const cat = await vm.spawn('cat', [], { stdin: true });
+   * await cat.write('hello\n');
+   * await cat.end();
+   * console.log(await cat.stdout()); // "hello\n"
+   * ```
+   */
+  async write(data) {
+    await this.resource.stdin(this.microvmId, this.id, data);
+  }
+  /** Close stdin, optionally writing a last piece of data first. */
+  async end(data = new Uint8Array(0)) {
+    await this.resource.stdin(this.microvmId, this.id, data, { eof: true });
+  }
+  /** Resize the terminal of a PTY command. */
+  async resize(cols, rows) {
+    await this.resource.resize(this.microvmId, this.id, { cols, rows });
+  }
+  /** JSON form: the command's latest state. */
+  toJSON() {
+    return this.current;
+  }
+  /**
+   * Deliver output to callbacks in the background, for `spawn` with
+   * `onStdout`/`onStderr`. {@link wait} waits for it and rethrows its error.
+   *
+   * @internal
+   */
+  startOutputPump(onStdout, onStderr) {
+    this.pump = (async () => {
+      for await (const chunk of this.logs()) {
+        await (chunk.stream === "stdout" ? onStdout : onStderr)?.(chunk.text, chunk);
+      }
+    })().catch((error) => {
+      this.pumpError = error instanceof Error ? error : new Error(String(error));
+    });
+  }
+};
+
+// src/microvms/microvm.ts
+var defaultClient;
+var resolveClient = (client) => {
+  if (client instanceof GigadriveClient) return client;
+  if (client) return new GigadriveClient(client);
+  defaultClient ??= new GigadriveClient();
+  return defaultClient;
+};
+var CREATE_WAIT_TIMEOUT = "10m";
+var NOT_LISTENING = /* @__PURE__ */ new Set([502, 503, 504]);
+var PROBE_TIMEOUT_MS = 5e3;
+var TERMINAL = ["stopping", "stopped", "failed"];
+var toStartInput = (cmd, args, options) => {
+  const user = options.sudo ? "root" : options.user;
+  return {
+    cmd,
+    ...args ? { args } : {},
+    ...options.cwd !== void 0 ? { cwd: options.cwd } : {},
+    ...options.env ? { env: options.env } : {},
+    ...user !== void 0 ? { user } : {},
+    ...options.timeout !== void 0 ? { timeoutMs: durationToMs(options.timeout) } : {}
+  };
+};
+var failIfRequested = (result, throwOnError) => {
+  if (throwOnError && result.exitCode !== 0) throw new CommandFailedError(result);
+  return result;
+};
+var MicroVmFiles = class {
+  /** @internal */
+  constructor(resource, microvmId) {
+    this.resource = resource;
+    this.microvmId = microvmId;
+  }
+  resource;
+  microvmId;
+  /** Read a file as bytes. @throws {@link MicroVmFileNotFoundError} */
+  read(path, options) {
+    return this.resource.read(this.microvmId, path, options);
+  }
+  /** Read a file as UTF-8 text. */
+  async readText(path, options) {
+    return new TextDecoder().decode(await this.read(path, options));
+  }
+  /** Read a file as a stream, for files too large to buffer. */
+  readStream(path, options) {
+    return this.resource.readStream(this.microvmId, path, options);
+  }
+  /**
+   * Write a file atomically, creating parent directories.
+   *
+   * @example
+   * ```ts
+   * await vm.files.write('/app/index.js', 'console.log("hi")');
+   * await vm.files.write('/app/logo.png', await (await fetch(url)).blob());
+   * ```
+   */
+  write(path, content, options) {
+    return this.resource.write(this.microvmId, path, content, options);
+  }
+  /**
+   * Write several files, a few at a time. Resolves in input order once all
+   * succeeded; rejects with the first failure.
+   *
+   * @example
+   * ```ts
+   * await vm.files.writeMany([
+   *   { path: 'app/package.json', content: JSON.stringify(pkg) },
+   *   { path: 'app/run.sh', content: '#!/bin/sh\nnode .', mode: '0755' },
+   * ]);
+   * ```
+   */
+  async writeMany(files, options = {}) {
+    const results = new Array(files.length);
+    let next = 0;
+    const worker = async () => {
+      while (next < files.length) {
+        const index = next++;
+        const file = files[index];
+        results[index] = await this.write(file.path, file.content, { mode: file.mode, signal: options.signal });
+      }
+    };
+    const workers = Math.max(1, Math.min(options.concurrency ?? 4, files.length));
+    await Promise.all(Array.from({ length: workers }, worker));
+    return results;
+  }
+  /**
+   * List a directory. `recursive` descends into subdirectories (up to `depth`
+   * levels). Very large listings are cut off; `client.microvms.files.list`
+   * reports that as `truncated`.
+   */
+  async list(path = ".", options) {
+    return (await this.resource.list(this.microvmId, path, options)).entries;
+  }
+  /** Describe a file or directory. @throws {@link MicroVmFileNotFoundError} */
+  stat(path) {
+    return this.resource.stat(this.microvmId, path);
+  }
+  /** Whether a file or directory exists. */
+  async exists(path) {
+    try {
+      await this.stat(path);
+      return true;
+    } catch (error) {
+      if (error instanceof MicroVmFileNotFoundError) return false;
+      throw error;
+    }
+  }
+  /** Create a directory and its parents (pass `parents: false` to require the parent). */
+  mkdir(path, options) {
+    return this.resource.mkdir(this.microvmId, path, options);
+  }
+  /** Delete a file, or a directory with `recursive: true`. */
+  remove(path, options) {
+    return this.resource.remove(this.microvmId, path, options);
+  }
+  /** Move or rename a file or directory. */
+  move(from, to) {
+    return this.resource.move(this.microvmId, from, to);
+  }
+};
+var MicroVmCommands = class {
+  /** @internal */
+  constructor(resource, microvmId) {
+    this.resource = resource;
+    this.microvmId = microvmId;
+  }
+  resource;
+  microvmId;
+  /**
+   * Reattach to a command, for example one spawned by another process.
+   *
+   * @example
+   * ```ts
+   * const command = await vm.commands.get(savedCommandId);
+   * for await (const chunk of command.logs()) process.stdout.write(chunk.data);
+   * ```
+   */
+  async get(commandId) {
+    return new Command(this.resource, this.microvmId, await this.resource.get(this.microvmId, commandId));
+  }
+  /** All commands the microVM still remembers, newest first. */
+  async list() {
+    const infos = await this.resource.list(this.microvmId);
+    return infos.map((info) => new Command(this.resource, this.microvmId, info));
+  }
+};
+var MicroVM = class _MicroVM {
+  /** @internal Use {@link MicroVM.create} or {@link MicroVM.get}. */
+  constructor(resource, info) {
+    this.resource = resource;
+    this.current = info;
+    this.files = new MicroVmFiles(resource.files, info.id);
+    this.commands = new MicroVmCommands(resource.commands, info.id);
+  }
+  resource;
+  /** Files inside the microVM. */
+  files;
+  /** Reattach to commands by id. */
+  commands;
+  current;
+  /**
+   * Create a microVM and wait until it runs.
+   *
+   * @throws {RangeError} When `timeout` is longer than 24 hours.
+   *
+   * The application is taken from `applicationId`, the client's
+   * `applicationId` or `GIGADRIVE_APPLICATION_ID`; inside a Gigadrive
+   * deployment or Function nothing needs configuring.
+   *
+   * @example
+   * ```ts
+   * const vm = await MicroVM.create({
+   *   image: 'python3.13',
+   *   vcpus: 2,
+   *   memoryMb: 4096,
+   *   timeout: '15m',
+   *   ports: [8000],
+   *   env: { PYTHONUNBUFFERED: '1' },
+   *   metadata: { user: 'u_123' },
+   *   network: 'deny',
+   * });
+   * ```
+   */
+  static async create(options = {}) {
+    const { client, timeout, timeoutMs, network, wait, signal, ...input } = options;
+    const resource = resolveClient(client).microvms;
+    const info = await resource.create(
+      {
+        ...input,
+        ...timeout !== void 0 ? { timeoutMs: microvmTimeoutMs(timeout) } : timeoutMs !== void 0 ? { timeoutMs } : {},
+        ...network !== void 0 ? { network: typeof network === "string" ? { egress: network } : network } : {}
+      },
+      // Never hold one request open for the whole boot: a create can wait
+      // minutes for capacity, longer than proxies in front of the API keep a
+      // response open. Start it, then poll.
+      { wait: false, signal }
+    );
+    const vm = new _MicroVM(resource, info);
+    if (wait === false) return vm;
+    try {
+      return await vm.waitUntilRunning({ timeout: CREATE_WAIT_TIMEOUT, signal });
+    } catch (error) {
+      if (error instanceof MicroVmStartError) throw error;
+      try {
+        await vm.delete();
+      } catch (cleanupError) {
+        throw new MicroVmCleanupError(vm.id, error, cleanupError);
+      }
+      throw error;
+    }
+  }
+  /**
+   * Connect to an existing microVM by id.
+   *
+   * @throws {@link MicroVmNotFoundError} when it does not exist.
+   */
+  static async get(microvmId, options = {}) {
+    const resource = resolveClient(options.client).microvms;
+    return new _MicroVM(resource, await resource.get(microvmId));
+  }
+  /** Alias of {@link MicroVM.get}. */
+  static connect(microvmId, options = {}) {
+    return _MicroVM.get(microvmId, options);
+  }
+  /**
+   * Iterate microVMs, newest first, across all pages.
+   *
+   * @example
+   * ```ts
+   * for await (const vm of MicroVM.list({ status: 'running' })) {
+   *   console.log(vm.id, vm.metadata);
+   * }
+   * ```
+   */
+  static async *list(options = {}) {
+    const { client, ...query } = options;
+    const resource = resolveClient(client).microvms;
+    for await (const info of resource.listAll(query)) yield new _MicroVM(resource, info);
+  }
+  /** Stable UUID. */
+  get id() {
+    return this.current.id;
+  }
+  /** Label used in preview URLs. */
+  get slug() {
+    return this.current.slug;
+  }
+  get applicationId() {
+    return this.current.applicationId;
+  }
+  /** Status as of the last API response; call {@link refresh} for the current one. */
+  get status() {
+    return this.current.status;
+  }
+  /** Exposed ports. */
+  get ports() {
+    return this.current.ports.map((entry) => entry.port);
+  }
+  get metadata() {
+    return this.current.metadata;
+  }
+  /** When the microVM stops automatically. */
+  get expiresAt() {
+    return this.current.expiresAt ? new Date(this.current.expiresAt) : null;
+  }
+  /** The full API object as of the last response. */
+  get info() {
+    return this.current;
+  }
+  /**
+   * The public preview URL of an exposed port.
+   *
+   * @throws {@link MicroVmPortNotExposedError} when the port was not in `ports` at create.
+   *
+   * @example
+   * ```ts
+   * vm.url(3000); // "https://3000-k3j9x2m1q8zt.vm.gigadrive.app"
+   * ```
+   */
+  url(port) {
+    const entry = this.current.ports.find((candidate) => candidate.port === port);
+    if (!entry) throw new MicroVmPortNotExposedError(port, this.ports);
+    return entry.url;
+  }
+  /** Fetch the latest state. */
+  async refresh(options = {}) {
+    this.current = await this.resource.get(this.id, { signal: options.signal });
+    return this.current;
+  }
+  async run(cmd, argsOrOptions, maybeOptions) {
+    const args = Array.isArray(argsOrOptions) ? argsOrOptions : void 0;
+    const options = (Array.isArray(argsOrOptions) ? maybeOptions : argsOrOptions) ?? {};
+    const input = toStartInput(cmd, args, options);
+    const streaming = options.onStdout !== void 0 || options.onStderr !== void 0 || options.stdin !== void 0 || options.signal !== void 0;
+    if (!streaming) {
+      const raw = await this.resource.commands.run(this.id, input);
+      return failIfRequested(
+        {
+          commandId: raw.id,
+          exitCode: raw.exitCode,
+          signal: raw.signal ?? null,
+          timedOut: raw.timedOut === true,
+          stdout: raw.stdout,
+          stderr: raw.stderr,
+          truncated: raw.truncated,
+          durationMs: raw.durationMs
+        },
+        options.throwOnError
+      );
+    }
+    const { signal } = options;
+    if (signal?.aborted) throw abortReason(signal);
+    const startedAt = Date.now();
+    const info = await this.resource.commands.start(
+      this.id,
+      { ...input, ...options.stdin !== void 0 ? { stdin: true } : {} },
+      { signal }
+    );
+    const command = new Command(this.resource.commands, this.id, info);
+    const kill = () => void command.kill("SIGKILL").catch(() => void 0);
+    signal?.addEventListener("abort", kill, { once: true });
+    try {
+      if (options.stdin !== void 0) await command.end(options.stdin);
+      const output = { stdout: "", stderr: "" };
+      const expected = { stdout: 0, stderr: 0 };
+      let truncated = false;
+      for await (const chunk of command.logs({ signal })) {
+        if (chunk.offset > expected[chunk.stream]) truncated = true;
+        expected[chunk.stream] = chunk.offset + chunk.data.length;
+        output[chunk.stream] += chunk.text;
+        await (chunk.stream === "stdout" ? options.onStdout : options.onStderr)?.(chunk.text, chunk);
+      }
+      const final = command.status === "exited" ? command.info : await command.wait({ signal });
+      return failIfRequested(
+        {
+          commandId: command.id,
+          exitCode: final.exitCode,
+          signal: final.signal,
+          timedOut: final.timedOut === true,
+          ...output,
+          truncated: truncated || command.truncated,
+          durationMs: commandDurationMs(final) ?? Date.now() - startedAt
+        },
+        options.throwOnError
+      );
+    } finally {
+      signal?.removeEventListener("abort", kill);
+    }
+  }
+  async spawn(cmd, argsOrOptions, maybeOptions) {
+    const args = Array.isArray(argsOrOptions) ? argsOrOptions : void 0;
+    const options = (Array.isArray(argsOrOptions) ? maybeOptions : argsOrOptions) ?? {};
+    const pty = options.pty === true ? { cols: 80, rows: 24 } : options.pty || void 0;
+    const info = await this.resource.commands.start(this.id, {
+      ...toStartInput(cmd, args, options),
+      ...options.stdin ? { stdin: true } : {},
+      ...pty ? { pty } : {}
+    });
+    const command = new Command(this.resource.commands, this.id, info);
+    if (options.onStdout || options.onStderr) command.startOutputPump(options.onStdout, options.onStderr);
+    return command;
+  }
+  /**
+   * Set the remaining lifetime to `duration` from now (up to the plan's
+   * maximum lifetime).
+   *
+   * @example
+   * ```ts
+   * await vm.extendTimeout('30m');
+   * ```
+   */
+  async extendTimeout(duration) {
+    this.current = await this.resource.extendTimeout(this.id, microvmTimeoutMs(duration));
+    return this.current;
+  }
+  /** Stop the microVM. Its disk, memory and running commands are discarded. */
+  async stop() {
+    this.current = await this.resource.stop(this.id);
+    return this.current;
+  }
+  /** Delete the microVM, stopping it first if needed. */
+  async delete() {
+    await this.resource.delete(this.id);
+  }
+  /**
+   * Poll until the microVM is running, for microVMs created with `wait: false`.
+   *
+   * @throws {@link MicroVmStartError} when it failed or stopped instead.
+   * @throws {@link MicroVmTimeoutError} when it is still starting after `timeout`.
+   */
+  async waitUntilRunning(options = {}) {
+    const deadline = Date.now() + durationToMs(options.timeout ?? "2m");
+    const interval = durationToMs(options.interval ?? "500ms");
+    while (this.current.status !== "running") {
+      if (TERMINAL.includes(this.current.status)) {
+        throw new MicroVmStartError(this.id, this.current.status, this.current.stopReason);
+      }
+      if (Date.now() + interval > deadline) {
+        throw new MicroVmTimeoutError(`The microVM ${this.id} is still ${this.current.status}; gave up waiting.`);
+      }
+      await sleep(interval, options.signal);
+      await this.refresh({ signal: options.signal });
+      if (options.signal?.aborted) throw abortReason(options.signal);
+    }
+    return this;
+  }
+  /**
+   * Poll an exposed port's preview URL until a server answers (any status
+   * other than 502, 503 or 504, which the gateway returns while nothing
+   * listens).
+   *
+   * @returns The preview URL.
+   * @throws {@link MicroVmPortNotExposedError} when the port is not exposed.
+   * @throws {@link MicroVmNotRunningError} when the microVM has stopped.
+   * @throws {@link MicroVmTimeoutError} when nothing answers within `timeout`.
+   *
+   * @example
+   * ```ts
+   * await vm.spawn('python3', ['-m', 'http.server', '8000']);
+   * const url = await vm.waitForPort(8000);
+   * ```
+   */
+  async waitForPort(port, options = {}) {
+    const base = this.url(port);
+    const path = options.path ?? "/";
+    const target = `${base.replace(/\/$/, "")}${path.startsWith("/") ? path : `/${path}`}`;
+    const deadline = Date.now() + durationToMs(options.timeout ?? "60s");
+    const interval = durationToMs(options.interval ?? "500ms");
+    for (; ; ) {
+      if (options.signal?.aborted) throw abortReason(options.signal);
+      const controller = new AbortController();
+      const timer = setTimeout(
+        () => controller.abort(),
+        Math.min(PROBE_TIMEOUT_MS, Math.max(1, deadline - Date.now()))
+      );
+      const forward = () => controller.abort();
+      options.signal?.addEventListener("abort", forward, { once: true });
+      let stopped = false;
+      try {
+        const response = await this.resource.fetchPreview(target, {
+          method: "GET",
+          redirect: "manual",
+          signal: controller.signal
+        });
+        await response.body?.cancel().catch(() => void 0);
+        stopped = response.status === 410 && response.headers.get("x-gigadrive-error") === "EDGE_MICROVM_STOPPED";
+        if (!stopped && !NOT_LISTENING.has(response.status)) return base;
+      } catch {
+        if (options.signal?.aborted) throw abortReason(options.signal);
+      } finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", forward);
+      }
+      if (stopped) {
+        throw new MicroVmNotRunningError(`The microVM ${this.id} has stopped; nothing will answer on port ${port}.`);
+      }
+      if (Date.now() + interval > deadline) {
+        throw new MicroVmTimeoutError(`Nothing answered on port ${port} of the microVM ${this.id}.`);
+      }
+      await sleep(interval, options.signal);
+    }
+  }
+  /** Stops the microVM at the end of an `await using` block. Already stopped microVMs are fine. */
+  async [Symbol.asyncDispose]() {
+    try {
+      await this.stop();
+    } catch (error) {
+      if (error instanceof MicroVmNotRunningError || error instanceof MicroVmNotFoundError) return;
+      throw error;
+    }
+  }
+  /** JSON form: the API object. */
+  toJSON() {
+    return this.current;
   }
 };
 
@@ -3487,10 +4901,10 @@ async function* paginate(fetchPage) {
 }
 
 // src/queues/default-client.ts
-var defaultClient;
+var defaultClient2;
 var defaultQueuesResource = () => {
-  defaultClient ??= new GigadriveClient();
-  return defaultClient.queues;
+  defaultClient2 ??= new GigadriveClient();
+  return defaultClient2.queues;
 };
 function queue(name, options = {}) {
   const { client, ...queueOptions } = options;
@@ -3514,7 +4928,7 @@ var decodeWorkflowMessage = (text) => JSON.parse(text, (_key, value) => {
   return value;
 });
 var readEnv2 = (name) => globalThis.process?.env?.[name] || void 0;
-var deduplicationKeyFor = async (idempotencyKey) => idempotencyKey.length <= 256 ? idempotencyKey : `wkf:sha256:${toHex2(await crypto.subtle.digest("SHA-256", toArrayBuffer(utf8Encode(idempotencyKey))))}`;
+var deduplicationKeyFor = async (idempotencyKey) => idempotencyKey.length <= 256 ? idempotencyKey : `wkf:sha256:${toHex(await crypto.subtle.digest("SHA-256", toArrayBuffer(utf8Encode(idempotencyKey))))}`;
 function createWorkflowQueue(options = {}) {
   const resource = () => options.client?.queues ?? defaultQueuesResource();
   const scope = { applicationId: options.applicationId, environment: options.environment };
@@ -3655,12 +5069,34 @@ export {
   ApplicationStorageResource,
   ApplicationsResource,
   AuthenticationError,
+  Command,
+  CommandFailedError,
   ConfigurationError,
   DeploymentsResource,
   DomainNotActiveError,
   GigadriveClient,
   GigadriveError,
   ImageOptimizationResource,
+  MICROVM_MAX_TIMEOUT_MS,
+  MicroVM,
+  MicroVmBusyError,
+  MicroVmCleanupError,
+  MicroVmCommands,
+  MicroVmCommandsResource,
+  MicroVmFileNotFoundError,
+  MicroVmFiles,
+  MicroVmFilesResource,
+  MicroVmImageBuildError,
+  MicroVmImageNotReadyError,
+  MicroVmImagesResource,
+  MicroVmNotFoundError,
+  MicroVmNotRunningError,
+  MicroVmPortNotExposedError,
+  MicroVmQuotaExceededError,
+  MicroVmStartError,
+  MicroVmTimeoutError,
+  MicroVmUnreachableError,
+  MicroVmsResource,
   NonRetryableError,
   OrganizationAiGatewayResource,
   OrganizationDomainsResource,
@@ -3688,8 +5124,10 @@ export {
   createManagedImageUrl,
   createWorkflowQueue,
   defaultQueueCodec,
+  durationToMs,
   durationToSeconds,
   paginate,
+  parseSSEEvents,
   parseSSEStream,
   queue,
   signQueueDelivery,