freestyle-sandboxes 0.1.41 → 0.1.43

package/index.cjs

@@ -3763,6 +3763,9 @@ class ApiClient {
     };
     return this.fetchFn(url, finalOptions);
   }
+  resolveUrl(path, params, query) {
+    return this.buildUrl(path, params, query);
+  }
   getRaw(path, options) {
     const url = this.buildUrl(path, options?.params, options?.query);
     return this.requestRaw("GET", url, void 0, options?.headers);
@@ -3777,6 +3780,11 @@ class ApiClient {
     const url = this.buildUrl(path, options?.params, options?.query);
     return this.request("POST", url, options?.body, options?.headers);
   }
+  postRaw(path, ...args) {
+    const options = args[0];
+    const url = this.buildUrl(path, options?.params, options?.query);
+    return this.requestRaw("POST", url, options?.body, options?.headers);
+  }
   put(path, ...args) {
     const options = args[0];
     const url = this.buildUrl(path, options?.params, options?.query);
@@ -5648,6 +5656,7 @@ function composeCreateVmOptions(arr) {
       result.activityThresholdBytes = options.activityThresholdBytes;
     if (options.discriminator !== void 0)
       result.discriminator = options.discriminator;
+    if (options.skipCache !== void 0) result.skipCache = options.skipCache;
     if (options.persistence !== void 0)
       result.persistence = options.persistence;
     if (options.ports !== void 0) {
@@ -5795,6 +5804,7 @@ function composeCreateVmOptions(arr) {
           aptDeps: newTemplate.aptDeps ?? baseTemplate.aptDeps,
           vcpuCount: newTemplate.vcpuCount !== void 0 ? newTemplate.vcpuCount : baseTemplate.vcpuCount,
           discriminator: newTemplate.discriminator ?? baseTemplate.discriminator,
+          skipCache: newTemplate.skipCache ?? baseTemplate.skipCache,
           workdir: newTemplate.workdir !== void 0 ? newTemplate.workdir : baseTemplate.workdir,
           idleTimeoutSeconds: newTemplate.idleTimeoutSeconds !== void 0 ? newTemplate.idleTimeoutSeconds : baseTemplate.idleTimeoutSeconds,
           waitForReadySignal: newTemplate.waitForReadySignal !== void 0 ? newTemplate.waitForReadySignal : baseTemplate.waitForReadySignal,
@@ -6011,6 +6021,94 @@ function composeVmSpecs(specs) {
 const DEFAULT_CONFIGURE_BASE_IMAGE = "FROM debian:trixie-slim";
 const RUN_COMMANDS_SYSTEMD_SERVICE_PREFIX = "freestyle-run-command";
 const WAIT_FOR_SYSTEMD_SERVICE_PREFIX = "freestyle-wait-for";
+const BACKGROUND_AFTER_SECS_HEADER = "x-freestyle-background-after-secs";
+const BACKGROUND_REQUEST_ID_HEADER = "x-freestyle-background-request-id";
+const DEFAULT_BACKGROUND_AFTER_SECS = 5;
+const DEFAULT_BACKGROUND_POLL_INTERVAL_MS = 2e3;
+function delay(ms) {
+  const timerApi = globalThis;
+  return new Promise((resolve) => timerApi.setTimeout(resolve, ms));
+}
+function extractBackgroundRequestId(response, body) {
+  return response.headers.get(BACKGROUND_REQUEST_ID_HEADER) ?? body?.requestId ?? body?.request_id;
+}
+async function parseJsonResponse(response) {
+  return await response.json();
+}
+async function readResponseError(response, fallbackMessage) {
+  const responseText = await response.text();
+  if (!responseText) {
+    return fallbackMessage;
+  }
+  try {
+    const errorBody = JSON.parse(responseText);
+    return errorBody.message ?? errorBody.error ?? responseText;
+  } catch {
+    return responseText;
+  }
+}
+async function emitBackgroundLogs(apiClient, requestId, logger, seenLogs) {
+  const response = await apiClient.fetch(
+    apiClient.resolveUrl("/observability/v1/logs", void 0, { requestId }),
+    { method: "GET" }
+  );
+  if (!response.ok) {
+    return;
+  }
+  const payload = await response.json();
+  for (const entry of payload.logs ?? []) {
+    const key = `${entry.timestamp}	${entry.message}`;
+    if (seenLogs.has(key)) {
+      continue;
+    }
+    seenLogs.add(key);
+    logger(`[${entry.timestamp}] ${entry.message}`);
+  }
+}
+async function waitForBackgroundRequest(apiClient, requestId, logger) {
+  const seenLogs = /* @__PURE__ */ new Set();
+  const resultUrl = apiClient.resolveUrl(
+    `/auth/v1/background-requests/${encodeURIComponent(requestId)}`
+  );
+  while (true) {
+    await emitBackgroundLogs(apiClient, requestId, logger, seenLogs);
+    const response = await apiClient.fetch(resultUrl, { method: "GET" });
+    if (response.status === 202) {
+      await delay(DEFAULT_BACKGROUND_POLL_INTERVAL_MS);
+      continue;
+    }
+    if (!response.ok) {
+      const message = await readResponseError(
+        response,
+        `Background request ${requestId} failed`
+      );
+      throw new Error(message);
+    }
+    return parseJsonResponse(response);
+  }
+}
+async function postWithBackgroundLogger(apiClient, path, options, logger) {
+  const response = await apiClient.postRaw(path, {
+    ...options,
+    headers: logger ? {
+      ...options.headers ?? {},
+      [BACKGROUND_AFTER_SECS_HEADER]: String(DEFAULT_BACKGROUND_AFTER_SECS)
+    } : options.headers
+  });
+  if (response.status !== 202 || !logger) {
+    return parseJsonResponse(response);
+  }
+  const accepted = await parseJsonResponse(
+    response
+  );
+  const requestId = extractBackgroundRequestId(response, accepted);
+  if (!requestId) {
+    throw new Error(
+      `Background request response for ${path} did not include a request ID`
+    );
+  }
+  return waitForBackgroundRequest(apiClient, requestId, logger);
+}
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -6392,9 +6490,9 @@ class Vm {
   ref({ vmId }) {
     return new Vm({ vmId, freestyle: this._freestyle });
   }
-  async delete({ vmId }) {
+  async delete() {
     return this.apiClient.delete("/v1/vms/{vm_id}", {
-      params: { vm_id: vmId }
+      params: { vm_id: this.vmId }
     });
   }
 }
@@ -6545,7 +6643,10 @@ class VmSpec {
   }
   ensureSnapshot() {
     if (!isVmSpecLike$1(this.raw.snapshot)) {
-      this.raw.snapshot = this.raw.discriminator !== void 0 ? new VmSpec({ discriminator: this.raw.discriminator }) : new VmSpec();
+      this.raw.snapshot = new VmSpec({
+        discriminator: this.raw.discriminator,
+        skipCache: this.raw.skipCache
+      });
     }
     return this.raw.snapshot;
   }
@@ -6574,6 +6675,9 @@ class VmSpec {
   discriminator(value) {
     return this.mergeRaw({ discriminator: value });
   }
+  skipCache() {
+    return this.mergeRaw({ skipCache: true });
+  }
   workdir(path) {
     return this.mergeRaw({ workdir: path });
   }
@@ -6800,7 +6904,10 @@ async function processOuterSpecBuilders(spec) {
           snapshotSpec = spec.raw.snapshot;
         } else {
           const inheritedDiscriminator = spec.getBuilderDiscriminator(key) ?? spec.raw.discriminator;
-          snapshotSpec = inheritedDiscriminator !== void 0 ? new VmSpec({ discriminator: inheritedDiscriminator }) : new VmSpec({});
+          snapshotSpec = new VmSpec({
+            discriminator: inheritedDiscriminator,
+            skipCache: spec.raw.skipCache
+          });
           spec.raw.snapshot = snapshotSpec;
         }
         spec.raw.snapshot = await builder.configureSnapshotSpec(snapshotSpec);
@@ -6827,7 +6934,10 @@ async function processSpecTree(spec) {
           snapshotSpec = spec.raw.snapshot;
         } else {
           const inheritedDiscriminator = spec.getBuilderDiscriminator(key) ?? spec.raw.discriminator;
-          snapshotSpec = inheritedDiscriminator !== void 0 ? new VmSpec({ discriminator: inheritedDiscriminator }) : new VmSpec({});
+          snapshotSpec = new VmSpec({
+            discriminator: inheritedDiscriminator,
+            skipCache: spec.raw.skipCache
+          });
           spec.raw.snapshot = snapshotSpec;
         }
         spec.raw.snapshot = await builder.configureSnapshotSpec(snapshotSpec);
@@ -6872,9 +6982,15 @@ class VmsNamespace {
   }
   snapshots;
   async create(options = {}) {
+    let logger;
     if (isVmSpecLike$1(options)) {
       options = { spec: cloneVmSpecTree(options) };
     } else {
+      logger = options.logger;
+      if ("logger" in options) {
+        const { logger: _logger, ...rest } = options;
+        options = rest;
+      }
       if (isVmSpecLike$1(options.spec)) {
         options.spec = cloneVmSpecTree(options.spec);
       }
@@ -6954,7 +7070,8 @@ class VmsNamespace {
     if (isVmTemplateLike$1(config.template)) {
       config.template = await ensureNestedTemplates(
         config.template,
-        this.snapshots
+        this.snapshots,
+        logger
       );
     }
     const keys = Object.keys(builders);
@@ -6995,16 +7112,21 @@ class VmsNamespace {
       template: _template,
       ...requestConfig
     } = config;
-    const response = await this.freestyle._apiClient.post("/v1/vms", {
-      body: {
-        ...requestConfig,
-        template: normalizedRequestTemplate,
-        // Cast systemd since we've processed SystemdServiceInput[] to RawSystemdService[]
-        systemd: config.systemd,
-        // Normalize git options - default config to {}
-        git: normalizeGitOptions(config.git)
-      }
-    }).catch((e) => {
+    const response = await postWithBackgroundLogger(
+      this.freestyle._apiClient,
+      "/v1/vms",
+      {
+        body: {
+          ...requestConfig,
+          template: normalizedRequestTemplate,
+          // Cast systemd since we've processed SystemdServiceInput[] to RawSystemdService[]
+          systemd: config.systemd,
+          // Normalize git options - default config to {}
+          git: normalizeGitOptions(config.git)
+        }
+      },
+      logger
+    ).catch((e) => {
       enhanceError(e);
       throw e;
     });
@@ -7160,11 +7282,12 @@ class VmSnapshotsNamespace {
     this.apiClient = apiClient;
   }
   async ensure(options) {
+    const { logger, ...restOptions } = options;
     let requestOptions = {
-      ...options,
-      spec: isVmSpecLike$1(options.spec) ? cloneVmSpecTree(options.spec) : void 0,
-      snapshot: isVmSpecLike$1(options.snapshot) ? cloneVmSpecTree(options.snapshot) : void 0,
-      template: isVmTemplateLike$1(options.template) ? cloneVmTemplateTree(options.template) : options.template
+      ...restOptions,
+      spec: isVmSpecLike$1(restOptions.spec) ? cloneVmSpecTree(restOptions.spec) : void 0,
+      snapshot: isVmSpecLike$1(restOptions.snapshot) ? cloneVmSpecTree(restOptions.snapshot) : void 0,
+      template: isVmTemplateLike$1(restOptions.template) ? cloneVmTemplateTree(restOptions.template) : restOptions.template
     };
     if (isVmSpecLike$1(requestOptions.snapshot)) {
       if (isVmSpecLike$1(requestOptions.spec)) {
@@ -7202,7 +7325,8 @@ class VmSnapshotsNamespace {
       if (isVmTemplateLike$1(processedTemplate.raw.template)) {
         requestOptions.template = await ensureNestedTemplates(
           processedTemplate,
-          this
+          this,
+          logger
         );
       }
     }
@@ -7211,18 +7335,43 @@ class VmSnapshotsNamespace {
         "snapshots.ensure requires a template or spec to build a snapshot"
       );
     }
-    return this.apiClient.post("/v1/vms/snapshots", {
-      body: {
-        ...requestOptions,
-        template: normalizeTemplateForRequest(
-          isVmTemplateLike$1(requestOptions.template) ? requestOptions.template.raw : requestOptions.template
-        )
-      }
-    }).catch((e) => {
+    return postWithBackgroundLogger(
+      this.apiClient,
+      "/v1/vms/snapshots",
+      {
+        body: {
+          ...requestOptions,
+          template: normalizeTemplateForRequest(
+            isVmTemplateLike$1(requestOptions.template) ? requestOptions.template.raw : requestOptions.template
+          )
+        }
+      },
+      logger
+    ).catch((e) => {
       enhanceError(e);
       throw e;
     });
   }
+  async create(options) {
+    return this.ensure(options);
+  }
+  async delete({ snapshotId }) {
+    const path = "/v1/vms/snapshots/{snapshot_id}";
+    const response = await this.apiClient.fetch(
+      this.apiClient.resolveUrl(path, { snapshot_id: snapshotId }),
+      { method: "DELETE" }
+    );
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => null);
+      if (errorBody?.code) {
+        throw errorFromJSON(errorBody);
+      }
+      throw new Error(
+        `Failed to delete snapshot: ${response.status} ${response.statusText}`
+      );
+    }
+    return await response.json();
+  }
 }
 async function processTemplateTree(template) {
   if (template.raw.baseImage) {
@@ -7294,24 +7443,24 @@ async function processTemplateTree(template) {
   }
   return template;
 }
-async function ensureNestedTemplates(template, snapshots) {
+async function ensureNestedTemplates(template, snapshots, logger) {
   const templates = [template];
   while (isVmTemplateLike$1(templates.at(-1)?.raw.template)) {
     const innerTemplate = templates.at(-1).raw.template;
     templates.at(-1).raw.template = void 0;
     templates.push(innerTemplate);
   }
-  return await layerTemplates(templates, snapshots);
+  return await layerTemplates(templates, snapshots, logger);
 }
-async function layerTemplates(templates, snapshots) {
+async function layerTemplates(templates, snapshots, logger) {
   if (templates.length === 1) {
     return templates[0];
   }
-  let lastSnapshotId = (await snapshots.ensure({ template: templates.pop() })).snapshotId;
+  let lastSnapshotId = (await snapshots.ensure({ template: templates.pop(), logger })).snapshotId;
   while (templates.length > 1) {
     const template = templates.pop();
     template.raw.snapshotId = lastSnapshotId;
-    lastSnapshotId = (await snapshots.ensure({ template })).snapshotId;
+    lastSnapshotId = (await snapshots.ensure({ template, logger })).snapshotId;
   }
   const outermost = templates.pop();
   outermost.raw.snapshotId = lastSnapshotId;

package/index.d.cts

@@ -4467,6 +4467,12 @@ interface PostV1VmsRequestBody {
          * These packages will be installed using `apt-get install` on VM startup.
          */
         aptDeps?: string[] | null;
+        /**
+         * When true, bypasses the snapshot cache and always creates a new snapshot.
+         * The new snapshot still stores the template hash, so it becomes the updated
+         * cache entry for future requests that do not set skipCache.
+         */
+        skipCache?: boolean | null;
     };
     /**
      * @deprecated
@@ -4883,6 +4889,12 @@ interface PostV1VmsSnapshotsRequestBody {
          * These packages will be installed using `apt-get install` on VM startup.
          */
         aptDeps?: string[] | null;
+        /**
+         * When true, bypasses the snapshot cache and always creates a new snapshot.
+         * The new snapshot still stores the template hash, so it becomes the updated
+         * cache entry for future requests that do not set skipCache.
+         */
+        skipCache?: boolean | null;
     };
     persistence?: null | ({
         priority?: number | null;
@@ -6695,9 +6707,11 @@ declare class ApiClient {
     private requestRaw;
     private request;
     fetch(url: string, options?: RequestInit): Promise<Response>;
+    resolveUrl(path: string, params?: Record<string, string>, query?: Record<string, any>): string;
     getRaw<P extends keyof GetPathMap>(path: P, options?: GetPathMap[P]["options"]): Promise<Response>;
     get<P extends keyof GetPathMap>(path: P, ...args: GetPathMap[P]["options"] extends undefined ? [options?: GetPathMap[P]["options"]] : [options: GetPathMap[P]["options"]]): Promise<GetPathMap[P]["response"]>;
     post<P extends keyof PostPathMap>(path: P, ...args: PostPathMap[P]["options"] extends undefined ? [options?: PostPathMap[P]["options"]] : [options: PostPathMap[P]["options"]]): Promise<PostPathMap[P]["response"]>;
+    postRaw<P extends keyof PostPathMap>(path: P, ...args: PostPathMap[P]["options"] extends undefined ? [options?: PostPathMap[P]["options"]] : [options: PostPathMap[P]["options"]]): Promise<Response>;
     put<P extends keyof PutPathMap>(path: P, ...args: PutPathMap[P]["options"] extends undefined ? [options?: PutPathMap[P]["options"]] : [options: PutPathMap[P]["options"]]): Promise<PutPathMap[P]["response"]>;
     delete<P extends keyof DeletePathMap>(path: P, ...args: DeletePathMap[P]["options"] extends undefined ? [options?: DeletePathMap[P]["options"]] : [options: DeletePathMap[P]["options"]]): Promise<DeletePathMap[P]["response"]>;
     patch<P extends keyof PatchPathMap>(path: P, ...args: PatchPathMap[P]["options"] extends undefined ? [options?: PatchPathMap[P]["options"]] : [options: PatchPathMap[P]["options"]]): Promise<PatchPathMap[P]["response"]>;
@@ -11909,6 +11923,12 @@ interface CreateSnapshotRequest {
          * These packages will be installed using `apt-get install` on VM startup.
          */
         aptDeps?: string[] | null;
+        /**
+         * When true, bypasses the snapshot cache and always creates a new snapshot.
+         * The new snapshot still stores the template hash, so it becomes the updated
+         * cache entry for future requests that do not set skipCache.
+         */
+        skipCache?: boolean | null;
     };
     persistence?: null | ({
         priority?: number | null;
@@ -12295,6 +12315,16 @@ type SystemdServiceInput = Omit<RawSystemdService, "mode" | "exec"> & {
 type VmWaitForConfig = Omit<SystemdServiceInput, "mode" | "exec" | "bash" | "deleteAfterSuccess"> & {
     intervalSeconds?: number;
 };
+type BackgroundRequestLogger = (message: string) => void;
+type SnapshotCreateOptions<T extends Record<string, VmWithLike> = {}> = Omit<PostV1VmsSnapshotsRequestBody, "template"> & {
+    template?: VmTemplate<T> | PostV1VmsSnapshotsRequestBody["template"];
+    spec?: VmSpec<T>;
+    snapshot?: VmSpec<T>;
+    logger?: BackgroundRequestLogger;
+};
+type SnapshotDeleteResponse = {
+    snapshotId: string;
+};
 /**
  * Terminal management operations for a VM.
  */
@@ -12428,9 +12458,7 @@ declare class Vm {
     ref({ vmId }: {
         vmId: string;
     }): Vm;
-    delete({ vmId }: {
-        vmId: string;
-    }): Promise<ResponseDeleteV1VmsVmId200>;
+    delete(): Promise<ResponseDeleteV1VmsVmId200>;
 }
 /**
  * Git configuration with optional config (defaults to {})
@@ -12496,6 +12524,7 @@ declare class VmSpec<T extends Record<string, VmWithLike> = {}> {
     readySignalTimeoutSeconds(value: number): this;
     waitForReadySignal(value: boolean): this;
     discriminator(value: string): this;
+    skipCache(): this;
     workdir(path: string): this;
     aptDeps(...deps: string[]): this;
     users(users: NonNullable<CreateVmOptions["users"]>): this;
@@ -12532,6 +12561,7 @@ declare class VmsNamespace {
         template?: VmTemplate<T>;
         spec?: VmSpec<T>;
         snapshot?: VmSpec<T>;
+        logger?: BackgroundRequestLogger;
     }): Promise<Omit<ResponsePostV1Vms200, "consoleUrl"> & {
         vmId: string;
         vm: Vm & {
@@ -12575,11 +12605,11 @@ declare class VmsNamespace {
 declare class VmSnapshotsNamespace {
     private apiClient;
     constructor(apiClient: ApiClient);
-    ensure<T extends Record<string, VmWithLike>>(options: Omit<PostV1VmsSnapshotsRequestBody, "template"> & {
-        template?: VmTemplate<T> | PostV1VmsSnapshotsRequestBody["template"];
-        spec?: VmSpec<T>;
-        snapshot?: VmSpec<T>;
-    }): Promise<ResponsePostV1VmsSnapshots200>;
+    ensure<T extends Record<string, VmWithLike>>(options: SnapshotCreateOptions<T>): Promise<ResponsePostV1VmsSnapshots200>;
+    create<T extends Record<string, VmWithLike>>(options: SnapshotCreateOptions<T>): Promise<ResponsePostV1VmsSnapshots200>;
+    delete({ snapshotId }: {
+        snapshotId: string;
+    }): Promise<SnapshotDeleteResponse>;
 }
 type CreateVmOptions = Omit<PostV1VmsRequestBody, "template" | "systemd" | "git"> & {
     rootfsSizeGb?: number | null;
@@ -12595,6 +12625,8 @@ type CreateVmOptions = Omit<PostV1VmsRequestBody, "template" | "systemd" | "git"
     };
     git?: null | GitOptions;
     discriminator?: CreateSnapshotRequest["template"]["discriminator"];
+    skipCache?: CreateSnapshotRequest["template"]["skipCache"];
+    logger?: BackgroundRequestLogger;
 };
 
 type CronSchedule = {
@@ -12743,4 +12775,4 @@ declare class Freestyle {
 declare const freestyle: Freestyle;
 
 export { CronNamespace, Deployment, errors as Errors, FileSystem, Freestyle, GitRepo, Identity, requests as Requests, responses as Responses, Systemd, SystemdService, Vm, VmBaseImage, VmBuilder, VmService, VmSpec, VmTemplate, VmWith, VmWithInstance, debugCreateRequests, freestyle, readFiles };
-export type { CreateVmOptions, CronSchedule, FreestyleOptions, SystemdServiceInput, VmWaitForConfig, VmWithDefaultFieldRecord };
+export type { BackgroundRequestLogger, CreateVmOptions, CronSchedule, FreestyleOptions, SystemdServiceInput, VmWaitForConfig, VmWithDefaultFieldRecord };

package/index.d.mts

@@ -4467,6 +4467,12 @@ interface PostV1VmsRequestBody {
          * These packages will be installed using `apt-get install` on VM startup.
          */
         aptDeps?: string[] | null;
+        /**
+         * When true, bypasses the snapshot cache and always creates a new snapshot.
+         * The new snapshot still stores the template hash, so it becomes the updated
+         * cache entry for future requests that do not set skipCache.
+         */
+        skipCache?: boolean | null;
     };
     /**
      * @deprecated
@@ -4883,6 +4889,12 @@ interface PostV1VmsSnapshotsRequestBody {
          * These packages will be installed using `apt-get install` on VM startup.
          */
         aptDeps?: string[] | null;
+        /**
+         * When true, bypasses the snapshot cache and always creates a new snapshot.
+         * The new snapshot still stores the template hash, so it becomes the updated
+         * cache entry for future requests that do not set skipCache.
+         */
+        skipCache?: boolean | null;
     };
     persistence?: null | ({
         priority?: number | null;
@@ -6695,9 +6707,11 @@ declare class ApiClient {
     private requestRaw;
     private request;
     fetch(url: string, options?: RequestInit): Promise<Response>;
+    resolveUrl(path: string, params?: Record<string, string>, query?: Record<string, any>): string;
     getRaw<P extends keyof GetPathMap>(path: P, options?: GetPathMap[P]["options"]): Promise<Response>;
     get<P extends keyof GetPathMap>(path: P, ...args: GetPathMap[P]["options"] extends undefined ? [options?: GetPathMap[P]["options"]] : [options: GetPathMap[P]["options"]]): Promise<GetPathMap[P]["response"]>;
     post<P extends keyof PostPathMap>(path: P, ...args: PostPathMap[P]["options"] extends undefined ? [options?: PostPathMap[P]["options"]] : [options: PostPathMap[P]["options"]]): Promise<PostPathMap[P]["response"]>;
+    postRaw<P extends keyof PostPathMap>(path: P, ...args: PostPathMap[P]["options"] extends undefined ? [options?: PostPathMap[P]["options"]] : [options: PostPathMap[P]["options"]]): Promise<Response>;
     put<P extends keyof PutPathMap>(path: P, ...args: PutPathMap[P]["options"] extends undefined ? [options?: PutPathMap[P]["options"]] : [options: PutPathMap[P]["options"]]): Promise<PutPathMap[P]["response"]>;
     delete<P extends keyof DeletePathMap>(path: P, ...args: DeletePathMap[P]["options"] extends undefined ? [options?: DeletePathMap[P]["options"]] : [options: DeletePathMap[P]["options"]]): Promise<DeletePathMap[P]["response"]>;
     patch<P extends keyof PatchPathMap>(path: P, ...args: PatchPathMap[P]["options"] extends undefined ? [options?: PatchPathMap[P]["options"]] : [options: PatchPathMap[P]["options"]]): Promise<PatchPathMap[P]["response"]>;
@@ -11909,6 +11923,12 @@ interface CreateSnapshotRequest {
          * These packages will be installed using `apt-get install` on VM startup.
          */
         aptDeps?: string[] | null;
+        /**
+         * When true, bypasses the snapshot cache and always creates a new snapshot.
+         * The new snapshot still stores the template hash, so it becomes the updated
+         * cache entry for future requests that do not set skipCache.
+         */
+        skipCache?: boolean | null;
     };
     persistence?: null | ({
         priority?: number | null;
@@ -12295,6 +12315,16 @@ type SystemdServiceInput = Omit<RawSystemdService, "mode" | "exec"> & {
 type VmWaitForConfig = Omit<SystemdServiceInput, "mode" | "exec" | "bash" | "deleteAfterSuccess"> & {
     intervalSeconds?: number;
 };
+type BackgroundRequestLogger = (message: string) => void;
+type SnapshotCreateOptions<T extends Record<string, VmWithLike> = {}> = Omit<PostV1VmsSnapshotsRequestBody, "template"> & {
+    template?: VmTemplate<T> | PostV1VmsSnapshotsRequestBody["template"];
+    spec?: VmSpec<T>;
+    snapshot?: VmSpec<T>;
+    logger?: BackgroundRequestLogger;
+};
+type SnapshotDeleteResponse = {
+    snapshotId: string;
+};
 /**
  * Terminal management operations for a VM.
  */
@@ -12428,9 +12458,7 @@ declare class Vm {
     ref({ vmId }: {
         vmId: string;
     }): Vm;
-    delete({ vmId }: {
-        vmId: string;
-    }): Promise<ResponseDeleteV1VmsVmId200>;
+    delete(): Promise<ResponseDeleteV1VmsVmId200>;
 }
 /**
  * Git configuration with optional config (defaults to {})
@@ -12496,6 +12524,7 @@ declare class VmSpec<T extends Record<string, VmWithLike> = {}> {
     readySignalTimeoutSeconds(value: number): this;
     waitForReadySignal(value: boolean): this;
     discriminator(value: string): this;
+    skipCache(): this;
     workdir(path: string): this;
     aptDeps(...deps: string[]): this;
     users(users: NonNullable<CreateVmOptions["users"]>): this;
@@ -12532,6 +12561,7 @@ declare class VmsNamespace {
         template?: VmTemplate<T>;
         spec?: VmSpec<T>;
         snapshot?: VmSpec<T>;
+        logger?: BackgroundRequestLogger;
     }): Promise<Omit<ResponsePostV1Vms200, "consoleUrl"> & {
         vmId: string;
         vm: Vm & {
@@ -12575,11 +12605,11 @@ declare class VmsNamespace {
 declare class VmSnapshotsNamespace {
     private apiClient;
     constructor(apiClient: ApiClient);
-    ensure<T extends Record<string, VmWithLike>>(options: Omit<PostV1VmsSnapshotsRequestBody, "template"> & {
-        template?: VmTemplate<T> | PostV1VmsSnapshotsRequestBody["template"];
-        spec?: VmSpec<T>;
-        snapshot?: VmSpec<T>;
-    }): Promise<ResponsePostV1VmsSnapshots200>;
+    ensure<T extends Record<string, VmWithLike>>(options: SnapshotCreateOptions<T>): Promise<ResponsePostV1VmsSnapshots200>;
+    create<T extends Record<string, VmWithLike>>(options: SnapshotCreateOptions<T>): Promise<ResponsePostV1VmsSnapshots200>;
+    delete({ snapshotId }: {
+        snapshotId: string;
+    }): Promise<SnapshotDeleteResponse>;
 }
 type CreateVmOptions = Omit<PostV1VmsRequestBody, "template" | "systemd" | "git"> & {
     rootfsSizeGb?: number | null;
@@ -12595,6 +12625,8 @@ type CreateVmOptions = Omit<PostV1VmsRequestBody, "template" | "systemd" | "git"
     };
     git?: null | GitOptions;
     discriminator?: CreateSnapshotRequest["template"]["discriminator"];
+    skipCache?: CreateSnapshotRequest["template"]["skipCache"];
+    logger?: BackgroundRequestLogger;
 };
 
 type CronSchedule = {
@@ -12743,4 +12775,4 @@ declare class Freestyle {
 declare const freestyle: Freestyle;
 
 export { CronNamespace, Deployment, errors as Errors, FileSystem, Freestyle, GitRepo, Identity, requests as Requests, responses as Responses, Systemd, SystemdService, Vm, VmBaseImage, VmBuilder, VmService, VmSpec, VmTemplate, VmWith, VmWithInstance, debugCreateRequests, freestyle, readFiles };
-export type { CreateVmOptions, CronSchedule, FreestyleOptions, SystemdServiceInput, VmWaitForConfig, VmWithDefaultFieldRecord };
+export type { BackgroundRequestLogger, CreateVmOptions, CronSchedule, FreestyleOptions, SystemdServiceInput, VmWaitForConfig, VmWithDefaultFieldRecord };

package/index.mjs

@@ -3761,6 +3761,9 @@ class ApiClient {
     };
     return this.fetchFn(url, finalOptions);
   }
+  resolveUrl(path, params, query) {
+    return this.buildUrl(path, params, query);
+  }
   getRaw(path, options) {
     const url = this.buildUrl(path, options?.params, options?.query);
     return this.requestRaw("GET", url, void 0, options?.headers);
@@ -3775,6 +3778,11 @@ class ApiClient {
     const url = this.buildUrl(path, options?.params, options?.query);
     return this.request("POST", url, options?.body, options?.headers);
   }
+  postRaw(path, ...args) {
+    const options = args[0];
+    const url = this.buildUrl(path, options?.params, options?.query);
+    return this.requestRaw("POST", url, options?.body, options?.headers);
+  }
   put(path, ...args) {
     const options = args[0];
     const url = this.buildUrl(path, options?.params, options?.query);
@@ -5646,6 +5654,7 @@ function composeCreateVmOptions(arr) {
       result.activityThresholdBytes = options.activityThresholdBytes;
     if (options.discriminator !== void 0)
       result.discriminator = options.discriminator;
+    if (options.skipCache !== void 0) result.skipCache = options.skipCache;
     if (options.persistence !== void 0)
       result.persistence = options.persistence;
     if (options.ports !== void 0) {
@@ -5793,6 +5802,7 @@ function composeCreateVmOptions(arr) {
           aptDeps: newTemplate.aptDeps ?? baseTemplate.aptDeps,
           vcpuCount: newTemplate.vcpuCount !== void 0 ? newTemplate.vcpuCount : baseTemplate.vcpuCount,
           discriminator: newTemplate.discriminator ?? baseTemplate.discriminator,
+          skipCache: newTemplate.skipCache ?? baseTemplate.skipCache,
           workdir: newTemplate.workdir !== void 0 ? newTemplate.workdir : baseTemplate.workdir,
           idleTimeoutSeconds: newTemplate.idleTimeoutSeconds !== void 0 ? newTemplate.idleTimeoutSeconds : baseTemplate.idleTimeoutSeconds,
           waitForReadySignal: newTemplate.waitForReadySignal !== void 0 ? newTemplate.waitForReadySignal : baseTemplate.waitForReadySignal,
@@ -6009,6 +6019,94 @@ function composeVmSpecs(specs) {
 const DEFAULT_CONFIGURE_BASE_IMAGE = "FROM debian:trixie-slim";
 const RUN_COMMANDS_SYSTEMD_SERVICE_PREFIX = "freestyle-run-command";
 const WAIT_FOR_SYSTEMD_SERVICE_PREFIX = "freestyle-wait-for";
+const BACKGROUND_AFTER_SECS_HEADER = "x-freestyle-background-after-secs";
+const BACKGROUND_REQUEST_ID_HEADER = "x-freestyle-background-request-id";
+const DEFAULT_BACKGROUND_AFTER_SECS = 5;
+const DEFAULT_BACKGROUND_POLL_INTERVAL_MS = 2e3;
+function delay(ms) {
+  const timerApi = globalThis;
+  return new Promise((resolve) => timerApi.setTimeout(resolve, ms));
+}
+function extractBackgroundRequestId(response, body) {
+  return response.headers.get(BACKGROUND_REQUEST_ID_HEADER) ?? body?.requestId ?? body?.request_id;
+}
+async function parseJsonResponse(response) {
+  return await response.json();
+}
+async function readResponseError(response, fallbackMessage) {
+  const responseText = await response.text();
+  if (!responseText) {
+    return fallbackMessage;
+  }
+  try {
+    const errorBody = JSON.parse(responseText);
+    return errorBody.message ?? errorBody.error ?? responseText;
+  } catch {
+    return responseText;
+  }
+}
+async function emitBackgroundLogs(apiClient, requestId, logger, seenLogs) {
+  const response = await apiClient.fetch(
+    apiClient.resolveUrl("/observability/v1/logs", void 0, { requestId }),
+    { method: "GET" }
+  );
+  if (!response.ok) {
+    return;
+  }
+  const payload = await response.json();
+  for (const entry of payload.logs ?? []) {
+    const key = `${entry.timestamp}	${entry.message}`;
+    if (seenLogs.has(key)) {
+      continue;
+    }
+    seenLogs.add(key);
+    logger(`[${entry.timestamp}] ${entry.message}`);
+  }
+}
+async function waitForBackgroundRequest(apiClient, requestId, logger) {
+  const seenLogs = /* @__PURE__ */ new Set();
+  const resultUrl = apiClient.resolveUrl(
+    `/auth/v1/background-requests/${encodeURIComponent(requestId)}`
+  );
+  while (true) {
+    await emitBackgroundLogs(apiClient, requestId, logger, seenLogs);
+    const response = await apiClient.fetch(resultUrl, { method: "GET" });
+    if (response.status === 202) {
+      await delay(DEFAULT_BACKGROUND_POLL_INTERVAL_MS);
+      continue;
+    }
+    if (!response.ok) {
+      const message = await readResponseError(
+        response,
+        `Background request ${requestId} failed`
+      );
+      throw new Error(message);
+    }
+    return parseJsonResponse(response);
+  }
+}
+async function postWithBackgroundLogger(apiClient, path, options, logger) {
+  const response = await apiClient.postRaw(path, {
+    ...options,
+    headers: logger ? {
+      ...options.headers ?? {},
+      [BACKGROUND_AFTER_SECS_HEADER]: String(DEFAULT_BACKGROUND_AFTER_SECS)
+    } : options.headers
+  });
+  if (response.status !== 202 || !logger) {
+    return parseJsonResponse(response);
+  }
+  const accepted = await parseJsonResponse(
+    response
+  );
+  const requestId = extractBackgroundRequestId(response, accepted);
+  if (!requestId) {
+    throw new Error(
+      `Background request response for ${path} did not include a request ID`
+    );
+  }
+  return waitForBackgroundRequest(apiClient, requestId, logger);
+}
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -6390,9 +6488,9 @@ class Vm {
   ref({ vmId }) {
     return new Vm({ vmId, freestyle: this._freestyle });
   }
-  async delete({ vmId }) {
+  async delete() {
     return this.apiClient.delete("/v1/vms/{vm_id}", {
-      params: { vm_id: vmId }
+      params: { vm_id: this.vmId }
     });
   }
 }
@@ -6543,7 +6641,10 @@ class VmSpec {
   }
   ensureSnapshot() {
     if (!isVmSpecLike$1(this.raw.snapshot)) {
-      this.raw.snapshot = this.raw.discriminator !== void 0 ? new VmSpec({ discriminator: this.raw.discriminator }) : new VmSpec();
+      this.raw.snapshot = new VmSpec({
+        discriminator: this.raw.discriminator,
+        skipCache: this.raw.skipCache
+      });
     }
     return this.raw.snapshot;
   }
@@ -6572,6 +6673,9 @@ class VmSpec {
   discriminator(value) {
     return this.mergeRaw({ discriminator: value });
   }
+  skipCache() {
+    return this.mergeRaw({ skipCache: true });
+  }
   workdir(path) {
     return this.mergeRaw({ workdir: path });
   }
@@ -6798,7 +6902,10 @@ async function processOuterSpecBuilders(spec) {
           snapshotSpec = spec.raw.snapshot;
         } else {
           const inheritedDiscriminator = spec.getBuilderDiscriminator(key) ?? spec.raw.discriminator;
-          snapshotSpec = inheritedDiscriminator !== void 0 ? new VmSpec({ discriminator: inheritedDiscriminator }) : new VmSpec({});
+          snapshotSpec = new VmSpec({
+            discriminator: inheritedDiscriminator,
+            skipCache: spec.raw.skipCache
+          });
           spec.raw.snapshot = snapshotSpec;
         }
         spec.raw.snapshot = await builder.configureSnapshotSpec(snapshotSpec);
@@ -6825,7 +6932,10 @@ async function processSpecTree(spec) {
           snapshotSpec = spec.raw.snapshot;
         } else {
           const inheritedDiscriminator = spec.getBuilderDiscriminator(key) ?? spec.raw.discriminator;
-          snapshotSpec = inheritedDiscriminator !== void 0 ? new VmSpec({ discriminator: inheritedDiscriminator }) : new VmSpec({});
+          snapshotSpec = new VmSpec({
+            discriminator: inheritedDiscriminator,
+            skipCache: spec.raw.skipCache
+          });
           spec.raw.snapshot = snapshotSpec;
         }
         spec.raw.snapshot = await builder.configureSnapshotSpec(snapshotSpec);
@@ -6870,9 +6980,15 @@ class VmsNamespace {
   }
   snapshots;
   async create(options = {}) {
+    let logger;
     if (isVmSpecLike$1(options)) {
       options = { spec: cloneVmSpecTree(options) };
     } else {
+      logger = options.logger;
+      if ("logger" in options) {
+        const { logger: _logger, ...rest } = options;
+        options = rest;
+      }
       if (isVmSpecLike$1(options.spec)) {
         options.spec = cloneVmSpecTree(options.spec);
       }
@@ -6952,7 +7068,8 @@ class VmsNamespace {
     if (isVmTemplateLike$1(config.template)) {
       config.template = await ensureNestedTemplates(
         config.template,
-        this.snapshots
+        this.snapshots,
+        logger
       );
     }
     const keys = Object.keys(builders);
@@ -6993,16 +7110,21 @@ class VmsNamespace {
       template: _template,
       ...requestConfig
     } = config;
-    const response = await this.freestyle._apiClient.post("/v1/vms", {
-      body: {
-        ...requestConfig,
-        template: normalizedRequestTemplate,
-        // Cast systemd since we've processed SystemdServiceInput[] to RawSystemdService[]
-        systemd: config.systemd,
-        // Normalize git options - default config to {}
-        git: normalizeGitOptions(config.git)
-      }
-    }).catch((e) => {
+    const response = await postWithBackgroundLogger(
+      this.freestyle._apiClient,
+      "/v1/vms",
+      {
+        body: {
+          ...requestConfig,
+          template: normalizedRequestTemplate,
+          // Cast systemd since we've processed SystemdServiceInput[] to RawSystemdService[]
+          systemd: config.systemd,
+          // Normalize git options - default config to {}
+          git: normalizeGitOptions(config.git)
+        }
+      },
+      logger
+    ).catch((e) => {
       enhanceError(e);
       throw e;
     });
@@ -7158,11 +7280,12 @@ class VmSnapshotsNamespace {
     this.apiClient = apiClient;
   }
   async ensure(options) {
+    const { logger, ...restOptions } = options;
     let requestOptions = {
-      ...options,
-      spec: isVmSpecLike$1(options.spec) ? cloneVmSpecTree(options.spec) : void 0,
-      snapshot: isVmSpecLike$1(options.snapshot) ? cloneVmSpecTree(options.snapshot) : void 0,
-      template: isVmTemplateLike$1(options.template) ? cloneVmTemplateTree(options.template) : options.template
+      ...restOptions,
+      spec: isVmSpecLike$1(restOptions.spec) ? cloneVmSpecTree(restOptions.spec) : void 0,
+      snapshot: isVmSpecLike$1(restOptions.snapshot) ? cloneVmSpecTree(restOptions.snapshot) : void 0,
+      template: isVmTemplateLike$1(restOptions.template) ? cloneVmTemplateTree(restOptions.template) : restOptions.template
     };
     if (isVmSpecLike$1(requestOptions.snapshot)) {
       if (isVmSpecLike$1(requestOptions.spec)) {
@@ -7200,7 +7323,8 @@ class VmSnapshotsNamespace {
       if (isVmTemplateLike$1(processedTemplate.raw.template)) {
         requestOptions.template = await ensureNestedTemplates(
           processedTemplate,
-          this
+          this,
+          logger
         );
       }
     }
@@ -7209,18 +7333,43 @@ class VmSnapshotsNamespace {
         "snapshots.ensure requires a template or spec to build a snapshot"
       );
     }
-    return this.apiClient.post("/v1/vms/snapshots", {
-      body: {
-        ...requestOptions,
-        template: normalizeTemplateForRequest(
-          isVmTemplateLike$1(requestOptions.template) ? requestOptions.template.raw : requestOptions.template
-        )
-      }
-    }).catch((e) => {
+    return postWithBackgroundLogger(
+      this.apiClient,
+      "/v1/vms/snapshots",
+      {
+        body: {
+          ...requestOptions,
+          template: normalizeTemplateForRequest(
+            isVmTemplateLike$1(requestOptions.template) ? requestOptions.template.raw : requestOptions.template
+          )
+        }
+      },
+      logger
+    ).catch((e) => {
       enhanceError(e);
       throw e;
     });
   }
+  async create(options) {
+    return this.ensure(options);
+  }
+  async delete({ snapshotId }) {
+    const path = "/v1/vms/snapshots/{snapshot_id}";
+    const response = await this.apiClient.fetch(
+      this.apiClient.resolveUrl(path, { snapshot_id: snapshotId }),
+      { method: "DELETE" }
+    );
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => null);
+      if (errorBody?.code) {
+        throw errorFromJSON(errorBody);
+      }
+      throw new Error(
+        `Failed to delete snapshot: ${response.status} ${response.statusText}`
+      );
+    }
+    return await response.json();
+  }
 }
 async function processTemplateTree(template) {
   if (template.raw.baseImage) {
@@ -7292,24 +7441,24 @@ async function processTemplateTree(template) {
   }
   return template;
 }
-async function ensureNestedTemplates(template, snapshots) {
+async function ensureNestedTemplates(template, snapshots, logger) {
   const templates = [template];
   while (isVmTemplateLike$1(templates.at(-1)?.raw.template)) {
     const innerTemplate = templates.at(-1).raw.template;
     templates.at(-1).raw.template = void 0;
     templates.push(innerTemplate);
   }
-  return await layerTemplates(templates, snapshots);
+  return await layerTemplates(templates, snapshots, logger);
 }
-async function layerTemplates(templates, snapshots) {
+async function layerTemplates(templates, snapshots, logger) {
   if (templates.length === 1) {
     return templates[0];
   }
-  let lastSnapshotId = (await snapshots.ensure({ template: templates.pop() })).snapshotId;
+  let lastSnapshotId = (await snapshots.ensure({ template: templates.pop(), logger })).snapshotId;
   while (templates.length > 1) {
     const template = templates.pop();
     template.raw.snapshotId = lastSnapshotId;
-    lastSnapshotId = (await snapshots.ensure({ template })).snapshotId;
+    lastSnapshotId = (await snapshots.ensure({ template, logger })).snapshotId;
   }
   const outermost = templates.pop();
   outermost.raw.snapshotId = lastSnapshotId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "freestyle-sandboxes",
-  "version": "0.1.41",
+  "version": "0.1.43",
   "type": "module",
   "exports": {
     "require": {