@computesdk/archil 0.4.27 → 0.4.29

package/dist/index.mjs

@@ -1,5 +1,5 @@
 // src/index.ts
-import { defineProvider } from "@computesdk/provider";
+import { defineProvider, InstanceSizeError } from "@computesdk/provider";
 import { Archil as ArchilClient, ArchilError } from "disk";
 import { randomUUID } from "crypto";
 import { posix } from "path";
@@ -21,6 +21,21 @@ function regionToBaseUrl(region) {
   const color = REGION_COLORS[region] ?? "green";
   return `https://control.${color}.${suffix}.${cloud}.prod.archil.com`;
 }
+function vmInstance(client, vm, resolved) {
+  return {
+    client,
+    disk: { id: vm.id },
+    vm,
+    resolved,
+    createdAt: /* @__PURE__ */ new Date(),
+    pause: async () => {
+      await vm.pause();
+    },
+    resume: async () => {
+      await vm.resume();
+    }
+  };
+}
 function resolveConfig(config) {
   const apiKey = config.apiKey ?? process.env.ARCHIL_API_KEY;
   const region = config.region ?? process.env.ARCHIL_REGION;
@@ -38,7 +53,16 @@ function resolveConfig(config) {
     }
     baseUrl = regionToBaseUrl(region);
   }
-  return { apiKey, baseUrl, execution: config.execution ?? "exec" };
+  return { apiKey, baseUrl, execution: resolveExecution(config) };
+}
+function resolveExecution(config) {
+  if (config.execution) return config.execution;
+  const fromEnv = process.env.ARCHIL_EXECUTION?.trim().toLowerCase();
+  if (!fromEnv) return "persistent";
+  if (fromEnv === "exec" || fromEnv === "persistent") return fromEnv;
+  throw new Error(
+    `Invalid ARCHIL_EXECUTION "${process.env.ARCHIL_EXECUTION}". Expected "persistent" (default) or "exec".`
+  );
 }
 function createClient(config, resolved) {
   const region = config.region ?? process.env.ARCHIL_REGION ?? "aws-us-east-1";
@@ -53,10 +77,6 @@ function resolveCreateDiskId(options) {
   }
   return diskId;
 }
-async function forkSandboxVm(client, sourceId, name) {
-  const source = await client.sandboxes.get(sourceId);
-  return source.fork({ name });
-}
 function shellEscape(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
@@ -136,15 +156,15 @@ function maxWriteChunkSize(parent, tempPath, diskPath) {
 }
 function wrapCommand(command, options) {
   let wrapped = command;
+  if (options?.cwd) {
+    wrapped = `cd ${shellEscape(options.cwd)} && ${wrapped}`;
+  }
   const envEntries = Object.entries(options?.env ?? {});
   if (!envEntries.some(([key]) => key === "HOME")) {
     envEntries.unshift(["HOME", process.env.HOME || "/tmp"]);
   }
-  const envPrefix = envEntries.map(([k, v]) => `${k}=${shellEscape(String(v))}`).join(" ");
-  wrapped = `${envPrefix} ${wrapped}`;
-  if (options?.cwd) {
-    wrapped = `cd ${shellEscape(options.cwd)} && ${wrapped}`;
-  }
+  const exports = envEntries.map(([k, v]) => `${k}=${shellEscape(String(v))}`).join(" ");
+  wrapped = `export ${exports}; ${wrapped}`;
   if (options?.background) {
     wrapped = `nohup sh -c ${shellEscape(wrapped)} > /dev/null 2>&1 &`;
   }
@@ -153,15 +173,9 @@ function wrapCommand(command, options) {
 async function execOnDisk(sandbox, command) {
   return sandbox.client.disks.exec(sandbox.disk.id, command);
 }
-function wrapSandboxCommand(command, options) {
-  let wrapped = command;
-  if (options?.cwd) {
-    wrapped = `cd ${shellEscape(options.cwd)} && ${wrapped}`;
-  }
-  if (options?.background) {
-    wrapped = `nohup sh -c ${shellEscape(wrapped)} > /dev/null 2>&1 &`;
-  }
-  return wrapped;
+function withCwd(command, cwd) {
+  return cwd ? `cd ${shellEscape(cwd)} || exit 1
+${command}` : command;
 }
 async function ensureVmRunning(vm) {
   await vm.refresh();
@@ -172,12 +186,30 @@ async function ensureVmRunning(vm) {
     await vm.start();
   }
 }
+function requireVm(sandbox, action) {
+  if (!sandbox.vm) {
+    throw new Error(
+      `Archil disk exec handles cannot ${action}; create a persistent VM (ephemeral: false) instead.`
+    );
+  }
+  return sandbox.vm;
+}
 async function stopAndDeleteVm(vm) {
   if (vm.status === "deleting" || vm.status === "deleted") return;
-  if (vm.status !== "stopped" && vm.status !== "exited" && vm.status !== "failed") {
-    await vm.stop();
+  try {
+    if (vm.status !== "stopped" && vm.status !== "exited" && vm.status !== "failed") {
+      await vm.stop();
+    }
+    await vm.delete();
+  } catch (error) {
+    if (error instanceof ArchilError && error.status === 404) return;
+    if (error instanceof ArchilError && error.status === 409) {
+      throw new Error(
+        `Archil refused to delete sandbox ${vm.id} (409): ${error.message}. Delete its forks and snapshots first; Archil deletes forks before their parent.`
+      );
+    }
+    throw error;
   }
-  await vm.delete();
 }
 function toSandboxRequest(options) {
   const request = {
@@ -195,148 +227,237 @@ function toSandboxRequest(options) {
   }
   return request;
 }
+var SNAPSHOT_NAME_PREFIX = "csdk-snap-";
+function snapshotName(name) {
+  const suffix = randomUUID().slice(0, 8);
+  const slug = (name ?? "").toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 63 - SNAPSHOT_NAME_PREFIX.length - suffix.length - 1).replace(/-+$/g, "");
+  return `${SNAPSHOT_NAME_PREFIX}${slug ? `${slug}-` : ""}${suffix}`;
+}
+function isSnapshotVm(vm) {
+  return vm.name?.startsWith(SNAPSHOT_NAME_PREFIX) ?? false;
+}
+function isDiskId(id) {
+  return id.startsWith("dsk-");
+}
 var sandboxModes = /* @__PURE__ */ new Map();
+function modeForId(id, resolved) {
+  return sandboxModes.get(id) ?? (isDiskId(id) ? "exec" : resolved.execution);
+}
+function diskInstance(client, disk, resolved) {
+  return { client, disk, resolved, createdAt: /* @__PURE__ */ new Date() };
+}
+var TIMEOUT_EXIT_CODE = 124;
+var KILLED_EXIT_CODE = 137;
+function mapProcessResult(result, timedOut, killSignal) {
+  if (timedOut || result.status === "timed_out") {
+    return { exitCode: TIMEOUT_EXIT_CODE, signal: "SIGKILL", stderrSuffix: "" };
+  }
+  if (result.status === "cancelled") {
+    return { exitCode: KILLED_EXIT_CODE, signal: killSignal ?? "SIGKILL", stderrSuffix: "" };
+  }
+  if (result.status === "failed") {
+    return {
+      exitCode: result.exitCode ?? 1,
+      signal: null,
+      stderrSuffix: result.exitReason ?? ""
+    };
+  }
+  return { exitCode: result.exitCode ?? 0, signal: null, stderrSuffix: "" };
+}
+async function startVmProcess(vm, command, options) {
+  await ensureVmRunning(vm);
+  const decoders = { stdout: new TextDecoder(), stderr: new TextDecoder() };
+  const output = { stdout: "", stderr: "" };
+  const emit = (stream, text) => {
+    if (!text) return;
+    output[stream] += text;
+    (stream === "stdout" ? options.onStdout : options.onStderr)?.(text);
+  };
+  const proc = await vm.processes.start(withCwd(command, options.cwd), {
+    env: options.env,
+    collectOutput: false,
+    timeoutSeconds: options.timeout !== void 0 ? Math.max(1, Math.ceil(options.timeout / 1e3)) : void 0,
+    onOutput: (chunk) => emit(chunk.stream, decoders[chunk.stream].decode(chunk.data, { stream: true }))
+  });
+  const state = { timedOut: false, killSignal: null };
+  let timer;
+  if (options.timeout !== void 0) {
+    timer = setTimeout(() => {
+      state.timedOut = true;
+      proc.kill().catch(() => {
+      });
+    }, options.timeout);
+  }
+  const done = proc.wait().then((result) => {
+    emit("stdout", decoders.stdout.decode());
+    emit("stderr", decoders.stderr.decode());
+    const mapped = mapProcessResult(result, state.timedOut, state.killSignal);
+    return {
+      stdout: output.stdout,
+      stderr: mapped.stderrSuffix ? `${output.stderr}${output.stderr && !output.stderr.endsWith("\n") ? "\n" : ""}${mapped.stderrSuffix}` : output.stderr,
+      exitCode: mapped.exitCode,
+      signal: mapped.signal
+    };
+  }).catch((error) => ({
+    stdout: output.stdout,
+    stderr: `${output.stderr}${error instanceof Error ? error.message : String(error)}`,
+    exitCode: 1,
+    signal: null
+  })).finally(() => {
+    if (timer) clearTimeout(timer);
+  });
+  return { proc, done, state, output };
+}
+async function runVmCommand(vm, command, options) {
+  const startTime = Date.now();
+  if (options?.background) {
+    await ensureVmRunning(vm);
+    const proc = await vm.processes.start(withCwd(command, options.cwd), {
+      env: options.env,
+      collectOutput: false
+    });
+    await proc.disconnect();
+    return { stdout: "", stderr: "", exitCode: 0, durationMs: Date.now() - startTime };
+  }
+  const { done } = await startVmProcess(vm, command, {
+    cwd: options?.cwd,
+    env: options?.env,
+    timeout: options?.timeout,
+    onStdout: options?.onStdout,
+    onStderr: options?.onStderr
+  });
+  const result = await done;
+  return {
+    stdout: result.stdout,
+    stderr: result.stderr,
+    exitCode: result.exitCode,
+    durationMs: Date.now() - startTime
+  };
+}
+function commandError(error, startTime) {
+  return {
+    stdout: "",
+    stderr: error instanceof Error ? error.message : String(error),
+    exitCode: 1,
+    durationMs: Date.now() - startTime
+  };
+}
+function resolveSizingExecution(config, options) {
+  if (options?.ephemeral !== void 0) return options.ephemeral ? "exec" : "persistent";
+  return resolveExecution(config);
+}
 var _provider = defineProvider({
   name: "archil",
+  sizes: (config, profile, options) => {
+    if (options?.sandbox !== void 0 && (options.sandbox === null || typeof options.sandbox !== "object" || Array.isArray(options.sandbox))) {
+      throw new InstanceSizeError("invalid", "sandbox must be an object when requesting sizeClass");
+    }
+    if (options?.vcpuCount !== void 0 || options?.memSizeMiB !== void 0 || options?.vcpu_count !== void 0 || options?.mem_size_mib !== void 0 || options?.sandbox?.vcpu_count !== void 0 || options?.sandbox?.mem_size_mib !== void 0 || options?.sandbox?.vcpuCount !== void 0 || options?.sandbox?.memSizeMiB !== void 0) {
+      throw new InstanceSizeError("conflict", "cannot combine sizeClass with native Archil CPU/memory fields");
+    }
+    if (options?.snapshotId !== void 0 || options?.sandboxId !== void 0 || options?.instanceId !== void 0) {
+      return { status: "unsupported", reason: "Archil attach/fork does not apply CPU/RAM overrides; create a new persistent VM to request a standard size." };
+    }
+    if (resolveSizingExecution(config, options) !== "persistent") {
+      return { status: "unavailable", reason: 'Archil exec containers do not expose VM sizing. Drop execution: "exec" (persistent VMs are the default) or set ephemeral: false.' };
+    }
+    if (profile.sizeClass === "xs" || profile.sizeClass === "2xl") {
+      return { status: "unknown", reason: "This adapter has not verified this standard shape." };
+    }
+    return { status: "supported", nativeOptions: { vcpus: profile.vcpus, memoryMiB: profile.memoryMiB } };
+  },
   methods: {
     instances: {
       create: async (config, options) => {
         const resolved = resolveConfig(config);
         const client = createClient(config, resolved);
         const execution = options?.ephemeral !== void 0 ? options.ephemeral ? "exec" : "persistent" : resolved.execution;
-        if (options?.snapshotId && options?.ephemeral === true) {
+        if (options?.snapshotId && execution === "exec") {
           throw new Error(
-            "Archil cannot combine ephemeral: true with snapshotId \u2014 snapshots fork persistent VMs. Drop ephemeral or set it to false."
+            'Archil snapshots fork persistent VMs and cannot be restored in exec mode. Drop execution: "exec" / ephemeral: true.'
           );
         }
-        if (execution === "persistent" || options?.snapshotId) {
-          let vm;
-          if (options?.snapshotId) {
-            vm = await forkSandboxVm(client, options.snapshotId, options?.name);
-          } else if (options?.sandboxId) {
-            if (options?.signal) {
-              throw new Error(
-                "create({ sandboxId }) attaches to an existing sandbox and cannot be combined with an abort signal"
-              );
-            }
-            vm = await client.sandboxes.get(options.sandboxId);
-            await ensureVmRunning(vm);
-          } else {
-            vm = await client.sandboxes.create(toSandboxRequest(options), {
-              wait: true
-            });
+        if (execution === "exec") {
+          const diskId = resolveCreateDiskId(options);
+          sandboxModes.set(diskId, "exec");
+          return { instance: diskInstance(client, { id: diskId }, resolved), instanceId: diskId };
+        }
+        if (options?.diskId) {
+          throw new Error(
+            'Archil create({ diskId }) attaches a disk exec handle, which is opt-in now that persistent VMs are the default.\n\nOpt in with archil({ execution: "exec" }) (or ARCHIL_EXECUTION=exec), or pass ephemeral: true.'
+          );
+        }
+        let vm;
+        if (options?.snapshotId) {
+          const source = await client.sandboxes.get(options.snapshotId);
+          vm = await source.fork({ name: options?.name });
+        } else if (options?.sandboxId) {
+          if (options?.signal) {
+            throw new Error(
+              "create({ sandboxId }) attaches to an existing sandbox and cannot be combined with an abort signal"
+            );
           }
-          sandboxModes.set(vm.id, "persistent");
-          return {
-            instance: {
-              client,
-              disk: { id: vm.id },
-              vm,
-              resolved,
-              createdAt: /* @__PURE__ */ new Date()
-            },
-            instanceId: vm.id
-          };
+          vm = await client.sandboxes.get(options.sandboxId);
+          await ensureVmRunning(vm);
+        } else {
+          vm = await client.sandboxes.create(toSandboxRequest(options), {
+            wait: true
+          });
         }
-        const diskId = resolveCreateDiskId(options);
-        sandboxModes.set(diskId, "exec");
-        return {
-          instance: {
-            client,
-            disk: { id: diskId },
-            resolved,
-            createdAt: /* @__PURE__ */ new Date()
-          },
-          instanceId: diskId
-        };
+        if (vm.status === "failed") {
+          throw new Error(`Archil sandbox ${vm.id} failed to start${vm.exitReason ? `: ${vm.exitReason}` : ""}`);
+        }
+        sandboxModes.set(vm.id, "persistent");
+        return { instance: vmInstance(client, vm, resolved), instanceId: vm.id };
       },
       getById: async (config, sandboxId) => {
         const resolved = resolveConfig(config);
         const client = createClient(config, resolved);
         try {
-          if (resolved.execution === "persistent") {
-            const vm = await client.sandboxes.get(sandboxId);
-            await ensureVmRunning(vm);
-            return {
-              instance: {
-                client,
-                disk: { id: vm.id },
-                vm,
-                resolved,
-                createdAt: /* @__PURE__ */ new Date()
-              },
-              instanceId: vm.id
-            };
+          if (modeForId(sandboxId, resolved) === "exec") {
+            const disk = await client.disks.get(sandboxId);
+            return { instance: diskInstance(client, disk, resolved), instanceId: disk.id };
           }
-          const disk = await client.disks.get(sandboxId);
-          return {
-            instance: { client, disk, resolved, createdAt: /* @__PURE__ */ new Date() },
-            instanceId: disk.id
-          };
+          const vm = await client.sandboxes.get(sandboxId);
+          await ensureVmRunning(vm);
+          return { instance: vmInstance(client, vm, resolved), instanceId: vm.id };
         } catch {
           return null;
         }
       },
+      // Archil's list endpoints return every sandbox (and the SDK follows disk
+      // pagination), so a single call yields the full account listing.
       list: async (config) => {
         const resolved = resolveConfig(config);
         const client = createClient(config, resolved);
-        if (resolved.execution === "persistent") {
-          const vms = await client.sandboxes.list();
-          return vms.map((vm) => ({
-            instance: {
-              client,
-              disk: { id: vm.id },
-              vm,
-              resolved,
-              createdAt: /* @__PURE__ */ new Date()
-            },
-            instanceId: vm.id
-          }));
+        if (resolved.execution === "exec") {
+          const disks = await client.disks.list();
+          return disks.map((disk) => ({ instance: diskInstance(client, disk, resolved), instanceId: disk.id }));
         }
-        const disks = await client.disks.list();
-        return disks.map((disk) => ({
-          instance: { client, disk, resolved, createdAt: /* @__PURE__ */ new Date() },
-          instanceId: disk.id
-        }));
+        const vms = await client.sandboxes.list();
+        return vms.filter((vm) => !isSnapshotVm(vm) && vm.status !== "deleting" && vm.status !== "deleted").map((vm) => ({ instance: vmInstance(client, vm, resolved), instanceId: vm.id }));
       },
       destroy: async (config, sandboxId) => {
         const resolved = resolveConfig(config);
-        const mode = sandboxModes.get(sandboxId) ?? resolved.execution;
-        if (mode === "persistent") {
-          const client = createClient(config, resolved);
-          const vm = await client.sandboxes.get(sandboxId);
-          await stopAndDeleteVm(vm);
-        }
+        const mode = modeForId(sandboxId, resolved);
         sandboxModes.delete(sandboxId);
+        if (mode === "exec") return;
+        const client = createClient(config, resolved);
+        let vm;
+        try {
+          vm = await client.sandboxes.get(sandboxId);
+        } catch (error) {
+          if (error instanceof ArchilError && (error.status === 404 || error.status === 400)) return;
+          throw error;
+        }
+        await stopAndDeleteVm(vm);
       },
       runCommand: async (sandbox, command, options) => {
         const startTime = Date.now();
         try {
           if (sandbox.vm) {
-            await ensureVmRunning(sandbox.vm);
-            const wrapped = wrapSandboxCommand(command, options);
-            if (options?.background) {
-              const proc = await sandbox.vm.processes.start(wrapped, {
-                env: options?.env
-              });
-              await proc.disconnect();
-              return {
-                stdout: "",
-                stderr: "",
-                exitCode: 0,
-                durationMs: Date.now() - startTime
-              };
-            }
-            const result2 = await sandbox.vm.exec(wrapped, {
-              env: options?.env,
-              timeoutSeconds: options?.timeout !== void 0 ? Math.ceil(options.timeout / 1e3) : void 0
-            });
-            return {
-              stdout: result2.stdout,
-              stderr: result2.stderr,
-              exitCode: result2.exitCode ?? (result2.status === "completed" ? 0 : 1),
-              durationMs: Date.now() - startTime
-            };
+            const { onStdout: _out, onStderr: _err, ...rest } = options ?? {};
+            return await runVmCommand(sandbox.vm, command, rest);
           }
           const result = await execOnDisk(sandbox, wrapCommand(command, options));
           return {
@@ -346,13 +467,93 @@ var _provider = defineProvider({
             durationMs: Date.now() - startTime
           };
         } catch (error) {
+          return commandError(error, startTime);
+        }
+      },
+      // Persistent VMs stream through the process WebSocket. Disk exec only
+      // returns output once the command exits, so it is delivered at the end.
+      streamCommand: async (sandbox, command, options) => {
+        const startTime = Date.now();
+        try {
+          if (sandbox.vm) return await runVmCommand(sandbox.vm, command, options);
+          const result = await execOnDisk(sandbox, wrapCommand(command, options));
+          if (result.stdout) options.onStdout?.(result.stdout);
+          if (result.stderr) options.onStderr?.(result.stderr);
           return {
-            stdout: "",
-            stderr: error instanceof Error ? error.message : String(error),
-            exitCode: 1,
+            stdout: result.stdout ?? "",
+            stderr: result.stderr ?? "",
+            exitCode: result.exitCode,
             durationMs: Date.now() - startTime
           };
+        } catch (error) {
+          return commandError(error, startTime);
+        }
+      },
+      startProcess: async (sandbox, command, options) => {
+        if (!sandbox.vm) {
+          throw new Error(
+            "Archil exec mode runs each command in a fresh container, so it cannot host background processes. Use a persistent VM (the default)."
+          );
         }
+        const startTime = Date.now();
+        const { proc, done, state, output } = await startVmProcess(sandbox.vm, command, {
+          cwd: options.cwd,
+          env: options.env,
+          onStdout: options.onStdout,
+          onStderr: options.onStderr
+        });
+        if (!options.stdin) await proc.closeStdin().catch(() => {
+        });
+        let exited;
+        const finished = done.then((result) => {
+          exited = result;
+          options.onExit?.({ exitCode: result.exitCode, signal: result.signal });
+          return result;
+        });
+        const toResult = (result) => ({
+          stdout: result.stdout,
+          stderr: result.stderr,
+          exitCode: result.exitCode,
+          signal: result.signal,
+          durationMs: Date.now() - startTime
+        });
+        return {
+          pid: null,
+          jobId: proc.id,
+          runtime: "native",
+          write: async (data) => {
+            if (!options.stdin) {
+              throw new Error("Process was started without stdin: true");
+            }
+            await proc.sendInput(data);
+          },
+          closeStdin: async () => {
+            if (options.stdin && !exited) await proc.closeStdin();
+          },
+          status: async () => exited ? { status: "exited", exitCode: exited.exitCode, signal: exited.signal, stdout: exited.stdout, stderr: exited.stderr } : { status: "running", exitCode: null, signal: null, stdout: output.stdout, stderr: output.stderr },
+          wait: async (waitOptions) => {
+            if (waitOptions?.timeout === void 0) return toResult(await finished);
+            let timer;
+            const timeout = new Promise((_, reject) => {
+              timer = setTimeout(
+                () => reject(new Error(`Process ${proc.id} did not exit within ${waitOptions.timeout}ms`)),
+                waitOptions.timeout
+              );
+            });
+            try {
+              return toResult(await Promise.race([finished, timeout]));
+            } finally {
+              clearTimeout(timer);
+            }
+          },
+          // Archil's process control only cancels (SIGKILL semantics); the
+          // requested signal name is what the result reports.
+          kill: async (signal) => {
+            if (exited) return;
+            state.killSignal = signal ?? "SIGKILL";
+            await proc.kill();
+          }
+        };
       },
       getInfo: async (sandbox) => {
         if (sandbox.vm) {
@@ -599,33 +800,64 @@ var _provider = defineProvider({
           }
         }
       },
+      // Native pause keeps CPU and memory: files anywhere (including /tmp)
+      // and running processes survive. Processes must outlive the command
+      // that started them (startProcess, or setsid): Archil reaps a command's
+      // process group when it exits. Disk exec handles have no VM to pause.
+      pause: async (sandbox) => {
+        await requireVm(sandbox, "pause").pause();
+      },
+      resume: async (sandbox) => {
+        await requireVm(sandbox, "resume").resume();
+      },
+      pauseCapabilities: { memory: true, createOptions: { ephemeral: false } },
       getInstance: (sandbox) => sandbox
     },
-    // Archil has no separate snapshot resource: a "snapshot" is a sandbox
-    // fork (an isolated writable branch of the source sandbox's state), so
-    // snapshot ids are ordinary sandbox ids that create() forks again.
+    // Archil has no separate snapshot resource. A snapshot is a fork of the
+    // source VM (memory and disk), paused so it holds state without running,
+    // and named with SNAPSHOT_NAME_PREFIX so it can be listed. create({
+    // snapshotId }) forks it again. Forks must be deleted before their parent.
     snapshot: {
+      // A fork copies the VM's memory and whole disk, so restores keep the
+      // rootfs (including /tmp) and running processes; the source keeps running.
+      capabilities: {
+        scope: "rootfs",
+        memory: true,
+        destroysSource: false,
+        createOptions: { ephemeral: false }
+      },
       create: async (config, sandboxId, options) => {
         const resolved = resolveConfig(config);
         const client = createClient(config, resolved);
+        let fork;
         try {
-          const fork = await forkSandboxVm(client, sandboxId, options?.name);
+          const source = await client.sandboxes.get(sandboxId);
+          fork = await source.fork({ name: snapshotName(options?.name) });
+          if (fork.status === "running") await fork.pause();
           return {
             id: fork.id,
             provider: "archil",
             createdAt: fork.createdAt ?? /* @__PURE__ */ new Date(),
-            metadata: { name: fork.name }
+            metadata: { name: options?.name, archilName: fork.name, sourceId: sandboxId }
           };
         } catch (error) {
+          if (fork) await stopAndDeleteVm(fork).catch(() => {
+          });
           throw new Error(
             `Failed to create Archil snapshot: ${error instanceof Error ? error.message : String(error)}`
           );
         }
       },
-      list: async (_config) => {
-        throw new Error(
-          "Archil provider does not support listing snapshots."
-        );
+      list: async (config) => {
+        const resolved = resolveConfig(config);
+        const client = createClient(config, resolved);
+        const vms = await client.sandboxes.list();
+        return vms.filter((vm) => isSnapshotVm(vm) && vm.status !== "deleting" && vm.status !== "deleted").map((vm) => ({
+          id: vm.id,
+          provider: "archil",
+          createdAt: vm.createdAt,
+          metadata: { archilName: vm.name, archilStatus: vm.status }
+        }));
       },
       delete: async (config, snapshotId) => {
         const resolved = resolveConfig(config);