@isol8/core 0.16.0 → 0.18.0

package/dist/index.js

@@ -1,4 +1,3 @@
-import { createRequire } from "node:module";
 var __defProp = Object.defineProperty;
 var __returnValue = (v) => v;
 function __exportSetter(name, newValue) {
@@ -14,7 +13,6 @@ var __export = (target, all) => {
     });
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
-var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/runtime/adapter.ts
 var adapters, extensionMap, RuntimeRegistry;
@@ -200,11 +198,13 @@ var exports_utils = {};
 __export(exports_utils, {
   validatePackageName: () => validatePackageName,
   truncateOutput: () => truncateOutput,
+  resolveWorkdir: () => resolveWorkdir,
   parseMemoryLimit: () => parseMemoryLimit,
   maskSecrets: () => maskSecrets,
   extractFromTar: () => extractFromTar,
   createTarBuffer: () => createTarBuffer
 });
+import path from "node:path";
 function parseMemoryLimit(limit) {
   const match = limit.match(/^(\d+(?:\.\d+)?)\s*([kmgt]?)b?$/i);
   if (!match) {
@@ -299,17 +299,24 @@ function validatePackageName(name) {
   }
   return name;
 }
+function resolveWorkdir(workdir, sandboxRoot = "/sandbox") {
+  const resolved = path.posix.resolve(sandboxRoot, workdir);
+  if (resolved !== sandboxRoot && !resolved.startsWith(`${sandboxRoot}/`)) {
+    throw new Error("Working directory must be inside /sandbox");
+  }
+  return resolved;
+}
+var init_utils = () => {};
 
 // src/engine/image-builder.ts
 var exports_image_builder = {};
 __export(exports_image_builder, {
   normalizePackages: () => normalizePackages,
   imageExists: () => imageExists,
-  getCustomImageTag: () => getCustomImageTag,
   ensureImages: () => ensureImages,
-  buildCustomImages: () => buildCustomImages,
   buildCustomImage: () => buildCustomImage,
-  buildBaseImages: () => buildBaseImages
+  buildBaseImages: () => buildBaseImages,
+  LABELS: () => LABELS
 });
 import { createHash as createHash2 } from "node:crypto";
 import { existsSync as existsSync3, readFileSync as readFileSync2, statSync as statSync2 } from "node:fs";
@@ -350,23 +357,21 @@ function computeDockerDirHash() {
   }
   return hash.digest("hex");
 }
-function computeDepsHash(runtime, packages) {
+function computeDepsHash(runtime, packages, setupScript) {
   const hash = createHash2("sha256");
   hash.update(runtime);
   for (const pkg of [...packages].sort()) {
     hash.update(pkg);
   }
+  if (setupScript) {
+    hash.update("setup:");
+    hash.update(setupScript);
+  }
   return hash.digest("hex");
 }
 function normalizePackages(packages) {
   return [...new Set(packages.map((pkg) => pkg.trim()).filter(Boolean))].sort();
 }
-function getCustomImageTag(runtime, packages) {
-  const normalizedPackages = normalizePackages(packages);
-  const depsHash = computeDepsHash(runtime, normalizedPackages);
-  const shortHash = depsHash.slice(0, 12);
-  return `isol8:${runtime}-custom-${shortHash}`;
-}
 async function getImageLabels(docker, imageName) {
   try {
     const image = docker.getImage(imageName);
@@ -439,33 +444,9 @@ async function buildBaseImages(docker, onProgress, force = false, onlyRuntimes)
     }
   }
 }
-async function buildCustomImages(docker, config, onProgress, force = false) {
-  const deps = config.dependencies;
-  const python = deps.python ? normalizePackages(deps.python) : [];
-  const node = deps.node ? normalizePackages(deps.node) : [];
-  const bun = deps.bun ? normalizePackages(deps.bun) : [];
-  const deno = deps.deno ? normalizePackages(deps.deno) : [];
-  const bash = deps.bash ? normalizePackages(deps.bash) : [];
-  if (python.length) {
-    await buildCustomImage(docker, "python", python, onProgress, force);
-  }
-  if (node.length) {
-    await buildCustomImage(docker, "node", node, onProgress, force);
-  }
-  if (bun.length) {
-    await buildCustomImage(docker, "bun", bun, onProgress, force);
-  }
-  if (deno.length) {
-    await buildCustomImage(docker, "deno", deno, onProgress, force);
-  }
-  if (bash.length) {
-    await buildCustomImage(docker, "bash", bash, onProgress, force);
-  }
-}
-async function buildCustomImage(docker, runtime, packages, onProgress, force = false) {
+async function buildCustomImage(docker, runtime, packages, tag, onProgress, force = false, setupScript) {
   const normalizedPackages = normalizePackages(packages);
-  const tag = getCustomImageTag(runtime, normalizedPackages);
-  const depsHash = computeDepsHash(runtime, normalizedPackages);
+  const depsHash = computeDepsHash(runtime, normalizedPackages, setupScript);
   logger.debug(`[ImageBuilder] ${runtime} custom deps hash: ${depsHash.slice(0, 16)}...`);
   if (!force) {
     const labels = await getImageLabels(docker, tag);
@@ -491,7 +472,7 @@ async function buildCustomImage(docker, runtime, packages, onProgress, force = f
   let installCmd;
   switch (runtime) {
     case "python":
-      installCmd = `RUN pip install --no-cache-dir ${normalizedPackages.join(" ")}`;
+      installCmd = `RUN pip install --break-system-packages --no-cache-dir ${normalizedPackages.join(" ")}`;
       break;
     case "node":
       installCmd = `RUN npm install -g ${normalizedPackages.join(" ")}`;
@@ -509,27 +490,50 @@ async function buildCustomImage(docker, runtime, packages, onProgress, force = f
     default:
       throw new Error(`Unknown runtime: ${runtime}`);
   }
+  let setupLines = "";
+  if (setupScript) {
+    const escaped = setupScript.replace(/\\/g, "\\\\").replace(/'/g, "'\\''");
+    setupLines = [
+      `RUN printf '%s\\n' '${escaped}' > /sandbox/.isol8-setup.sh`,
+      "RUN chmod +x /sandbox/.isol8-setup.sh"
+    ].join(`
+`);
+  }
   const dockerfileContent = `FROM isol8:${runtime}
 ${installCmd}
+${setupLines}
 `;
-  const { createTarBuffer: createTarBuffer2, validatePackageName: validatePackageName2 } = await Promise.resolve().then(() => exports_utils);
-  const { Readable } = await import("node:stream");
+  const { createTarBuffer: createTarBuffer2, validatePackageName: validatePackageName2 } = await Promise.resolve().then(() => (init_utils(), exports_utils));
   normalizedPackages.forEach(validatePackageName2);
   const tarBuffer = createTarBuffer2("Dockerfile", dockerfileContent);
-  const stream = await docker.buildImage(Readable.from(tarBuffer), {
+  const imageLabels = {
+    [LABELS.depsHash]: depsHash,
+    [LABELS.runtime]: runtime.toString(),
+    [LABELS.dependencies]: normalizedPackages.join(",")
+  };
+  if (setupScript) {
+    imageLabels[LABELS.setupScript] = setupScript;
+  }
+  const stream = await docker.buildImage(tarBuffer, {
     t: tag,
     dockerfile: "Dockerfile",
-    labels: {
-      [LABELS.depsHash]: depsHash
-    }
+    labels: imageLabels
   });
   await new Promise((resolve2, reject) => {
-    docker.modem.followProgress(stream, (err) => {
+    docker.modem.followProgress(stream, (err, res) => {
       if (err) {
         reject(err);
+      } else if (res && res.length > 0 && res.at(-1).error) {
+        reject(new Error(res.at(-1).error));
       } else {
         resolve2();
       }
+    }, (event) => {
+      if (event.stream) {
+        process.stdout.write(event.stream);
+      } else if (event.error) {
+        console.error(event.error);
+      }
     });
   });
   if (oldImageId) {
@@ -564,7 +568,10 @@ var init_image_builder = __esm(() => {
   DOCKERFILE_DIR = resolveDockerDir();
   LABELS = {
     dockerHash: "org.isol8.build.hash",
-    depsHash: "org.isol8.deps.hash"
+    depsHash: "org.isol8.deps.hash",
+    runtime: "org.isol8.runtime",
+    dependencies: "org.isol8.dependencies",
+    setupScript: "org.isol8.setup"
   };
   DOCKER_BUILD_FILES = ["Dockerfile", "proxy.sh", "proxy-handler.sh"];
 });
@@ -776,6 +783,22 @@ class RemoteIsol8 {
     const body = await res.json();
     return Buffer.from(body.content, "base64");
   }
+  async listSessions() {
+    const res = await this.fetch("/sessions");
+    if (!res.ok) {
+      const body2 = await res.json().catch(() => ({}));
+      throw new Error(`Failed to list sessions: ${body2.error ?? res.statusText}`);
+    }
+    const body = await res.json();
+    return body.sessions;
+  }
+  async deleteSession(sessionId) {
+    const res = await this.fetch(`/session/${sessionId}`, { method: "DELETE" });
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      throw new Error(`Failed to delete session: ${body.error ?? res.statusText}`);
+    }
+  }
   async fetch(path, init) {
     return globalThis.fetch(`${this.host}${path}`, {
       ...init,
@@ -812,7 +835,6 @@ var DEFAULT_CONFIG = {
   },
   poolStrategy: "fast",
   poolSize: { clean: 1, dirty: 1 },
-  dependencies: {},
   security: {
     seccomp: "strict"
   },
@@ -853,6 +875,7 @@ var DEFAULT_CONFIG = {
     defaultTtlMs: 86400000,
     cleanupIntervalMs: 3600000
   },
+  prebuiltImages: [],
   debug: false
 };
 function loadConfig(cwd) {
@@ -887,10 +910,6 @@ function mergeConfig(defaults, overrides) {
     },
     poolStrategy: overrides.poolStrategy ?? defaults.poolStrategy,
     poolSize: overrides.poolSize ?? defaults.poolSize,
-    dependencies: {
-      ...defaults.dependencies,
-      ...overrides.dependencies
-    },
     security: {
       seccomp: overrides.security?.seccomp ?? defaults.security.seccomp,
       customProfilePath: overrides.security?.customProfilePath ?? defaults.security.customProfilePath
@@ -910,6 +929,7 @@ function mergeConfig(defaults, overrides) {
       ...defaults.auth,
       ...overrides.auth
     },
+    prebuiltImages: overrides.prebuiltImages ?? defaults.prebuiltImages,
     debug: overrides.debug ?? defaults.debug
   };
 }
@@ -1329,11 +1349,9 @@ var EMBEDDED_DEFAULT_SECCOMP_PROFILE = JSON.stringify({
   ]
 });
 
-// src/engine/docker.ts
-init_image_builder();
-
 // src/engine/managers/execution-manager.ts
 init_logger();
+init_utils();
 import { PassThrough } from "node:stream";
 
 class ExecutionManager {
@@ -1437,6 +1455,63 @@ class ExecutionManager {
       stream.on("error", reject);
     });
   }
+  async runSetupScript(container, script, timeoutMs, volumeManager) {
+    const scriptPath = "/sandbox/.isol8-setup.sh";
+    await volumeManager.writeFileViaExec(container, scriptPath, script);
+    const chmodExec = await container.exec({
+      Cmd: ["chmod", "+x", scriptPath],
+      User: "sandbox"
+    });
+    await chmodExec.start({ Detach: true });
+    let chmodInfo = await chmodExec.inspect();
+    while (chmodInfo.Running) {
+      await new Promise((r) => setTimeout(r, 5));
+      chmodInfo = await chmodExec.inspect();
+    }
+    const timeoutSec = Math.max(1, Math.ceil(timeoutMs / 1000));
+    const cmd = this.wrapWithTimeout(["bash", scriptPath], timeoutSec);
+    logger.debug(`Running setup script: ${JSON.stringify(cmd)}`);
+    const env = [
+      "PATH=/sandbox/.local/bin:/sandbox/.npm-global/bin:/sandbox/.bun-global/bin:/usr/local/bin:/usr/bin:/bin:/usr/local/sbin:/usr/sbin:/sbin"
+    ];
+    const exec = await container.exec({
+      Cmd: cmd,
+      AttachStdout: true,
+      AttachStderr: true,
+      Env: env,
+      WorkingDir: "/sandbox",
+      User: "sandbox"
+    });
+    const stream = await exec.start({ Detach: false, Tty: false });
+    return new Promise((resolve2, reject) => {
+      let stderr = "";
+      const stdoutStream = new PassThrough;
+      const stderrStream = new PassThrough;
+      container.modem.demuxStream(stream, stdoutStream, stderrStream);
+      stderrStream.on("data", (chunk) => {
+        const text = chunk.toString();
+        stderr += text;
+        logger.debug(`[setup:stderr] ${text.trimEnd()}`);
+      });
+      stdoutStream.on("data", (chunk) => {
+        const text = chunk.toString();
+        logger.debug(`[setup:stdout] ${text.trimEnd()}`);
+      });
+      stream.on("end", async () => {
+        try {
+          const info = await exec.inspect();
+          if (info.ExitCode !== 0) {
+            reject(new Error(`Setup script failed (exit code ${info.ExitCode}): ${stderr}`));
+          } else {
+            resolve2();
+          }
+        } catch (err) {
+          reject(err);
+        }
+      });
+      stream.on("error", reject);
+    });
+  }
   async* streamExecOutput(stream, exec, container, timeoutMs) {
     const queue = [];
     let resolve2 = null;
@@ -1691,6 +1766,7 @@ class NetworkManager {
   }
 }
 // src/engine/managers/volume-manager.ts
+init_utils();
 import { PassThrough as PassThrough2 } from "node:stream";
 
 class VolumeManager {
@@ -1771,13 +1847,13 @@ class VolumeManager {
     const b64Output = Buffer.concat(chunks).toString("utf-8").trim();
     return Buffer.from(b64Output, "base64");
   }
-  async getFileFromContainer(container, path) {
-    const stream = await container.getArchive({ path });
+  async getFileFromContainer(container, path2) {
+    const stream = await container.getArchive({ path: path2 });
     const chunks = [];
     for await (const chunk of stream) {
       chunks.push(chunk);
     }
-    return extractFromTar(Buffer.concat(chunks), path);
+    return extractFromTar(Buffer.concat(chunks), path2);
   }
   async retrieveFiles(container, paths) {
     const files = {};
@@ -1789,19 +1865,19 @@ class VolumeManager {
     }
     return files;
   }
-  async putFile(container, path, content) {
+  async putFile(container, path2, content) {
     if (this.readonlyRootFs) {
-      await this.writeFileViaExec(container, path, content);
+      await this.writeFileViaExec(container, path2, content);
     } else {
-      const tar = createTarBuffer(path, content);
+      const tar = createTarBuffer(path2, content);
       await container.putArchive(tar, { path: "/" });
     }
   }
-  async getFile(container, path) {
+  async getFile(container, path2) {
     if (this.readonlyRootFs) {
-      return this.readFileViaExec(container, path);
+      return this.readFileViaExec(container, path2);
     }
-    return this.getFileFromContainer(container, path);
+    return this.getFileFromContainer(container, path2);
   }
 }
 // src/engine/pool.ts
@@ -2083,6 +2159,7 @@ function calculateResourceDelta(before, after) {
 }
 
 // src/engine/docker.ts
+init_utils();
 var SANDBOX_WORKDIR = "/sandbox";
 var MAX_OUTPUT_BYTES = 1024 * 1024;
 
@@ -2107,7 +2184,6 @@ class DockerIsol8 {
   logNetwork;
   poolStrategy;
   poolSize;
-  dependencies;
   auditLogger;
   remoteCodePolicy;
   networkManager;
@@ -2157,7 +2233,6 @@ class DockerIsol8 {
     this.logNetwork = options.logNetwork ?? false;
     this.poolStrategy = options.poolStrategy ?? "fast";
     this.poolSize = options.poolSize ?? { clean: 1, dirty: 1 };
-    this.dependencies = options.dependencies ?? {};
     this.remoteCodePolicy = options.remoteCode ?? {
       enabled: false,
       allowedSchemes: ["https"],
@@ -2201,7 +2276,8 @@ class DockerIsol8 {
     const adapters2 = typeof prewarm === "object" && prewarm.runtimes?.length ? prewarm.runtimes.map((runtime) => RuntimeRegistry.get(runtime)) : RuntimeRegistry.list();
     for (const adapter of adapters2) {
       try {
-        images.add(await this.resolveImage(adapter));
+        const resolved = await this.resolveImage(adapter);
+        images.add(resolved.image);
       } catch (err) {
         logger.debug(`[Pool] Pre-warm image resolution failed for ${adapter.name}: ${err}`);
       }
@@ -2358,17 +2434,17 @@ class DockerIsol8 {
     } catch {}
     return logs;
   }
-  async putFile(path, content) {
+  async putFile(path2, content) {
     if (!this.container) {
       throw new Error("No active container. Call execute() first in persistent mode.");
     }
-    await this.volumeManager.putFile(this.container, path, content);
+    await this.volumeManager.putFile(this.container, path2, content);
   }
-  async getFile(path) {
+  async getFile(path2) {
     if (!this.container) {
       throw new Error("No active container. Call execute() first in persistent mode.");
     }
-    return this.volumeManager.getFile(this.container, path);
+    return this.volumeManager.getFile(this.container, path2);
   }
   get containerId() {
     return this.container?.id ?? null;
@@ -2379,7 +2455,9 @@ class DockerIsol8 {
       const request = await this.resolveExecutionRequest(req);
       const adapter = this.getAdapter(request.runtime);
       const timeoutMs = request.timeoutMs ?? this.defaultTimeoutMs;
-      const image = await this.resolveImage(adapter);
+      const resolved = await this.resolveImage(adapter, request.installPackages);
+      const image = resolved.image;
+      const execWorkdir = request.workdir ? resolveWorkdir(request.workdir) : SANDBOX_WORKDIR;
       const container = await this.docker.createContainer({
         Image: image,
         Cmd: ["sleep", "infinity"],
@@ -2396,8 +2474,14 @@ class DockerIsol8 {
         const ext = request.fileExtension ?? adapter.getFileExtension();
         const filePath = `${SANDBOX_WORKDIR}/main${ext}`;
         await this.volumeManager.writeFileViaExec(container, filePath, request.code);
-        if (request.installPackages?.length) {
-          await this.executionManager.installPackages(container, request.runtime, request.installPackages, timeoutMs);
+        if (resolved.remainingPackages.length > 0) {
+          await this.executionManager.installPackages(container, request.runtime, resolved.remainingPackages, timeoutMs);
+        }
+        if (resolved.imageSetupScript) {
+          await this.executionManager.runSetupScript(container, resolved.imageSetupScript, timeoutMs, this.volumeManager);
+        }
+        if (request.setupScript) {
+          await this.executionManager.runSetupScript(container, request.setupScript, timeoutMs, this.volumeManager);
         }
         if (request.files) {
           for (const [fPath, fContent] of Object.entries(request.files)) {
@@ -2420,7 +2504,7 @@ class DockerIsol8 {
           Env: this.executionManager.buildEnv(request.env, this.networkManager.proxyPort, this.network, this.networkFilter),
           AttachStdout: true,
           AttachStderr: true,
-          WorkingDir: SANDBOX_WORKDIR,
+          WorkingDir: execWorkdir,
           User: "sandbox"
         });
         const execStream = await exec.start({ Tty: false });
@@ -2438,55 +2522,90 @@ class DockerIsol8 {
       this.semaphore.release();
     }
   }
-  async resolveImage(adapter) {
+  async resolveImage(adapter, requestedPackages) {
     if (this.overrideImage) {
-      return this.overrideImage;
+      let imageSetupScript2;
+      try {
+        const { LABELS: LABELS2 } = await Promise.resolve().then(() => (init_image_builder(), exports_image_builder));
+        const inspect = await this.docker.getImage(this.overrideImage).inspect();
+        const labels = inspect.Config?.Labels ?? {};
+        imageSetupScript2 = labels[LABELS2.setupScript] || undefined;
+      } catch {}
+      return {
+        image: this.overrideImage,
+        remainingPackages: requestedPackages ?? [],
+        imageSetupScript: imageSetupScript2
+      };
     }
-    const cacheKey = adapter.image;
+    const cacheKey = `${adapter.name}:${(requestedPackages ?? []).join(",")}`;
     const cached = this.imageCache.get(cacheKey);
     if (cached) {
-      return cached;
-    }
-    let resolvedImage = adapter.image;
-    const configuredDeps = this.dependencies[adapter.name];
-    const normalizedDeps = configuredDeps ? normalizePackages(configuredDeps) : [];
-    if (normalizedDeps.length > 0) {
-      const hashedCustomTag = getCustomImageTag(adapter.name, normalizedDeps);
+      let imageSetupScript2;
       try {
-        await this.docker.getImage(hashedCustomTag).inspect();
-        resolvedImage = hashedCustomTag;
-      } catch {
-        logger.debug(`[ImageBuilder] Hashed custom image not found for ${adapter.name}: ${hashedCustomTag}`);
+        const { LABELS: LABELS2 } = await Promise.resolve().then(() => (init_image_builder(), exports_image_builder));
+        const inspect = await this.docker.getImage(cached).inspect();
+        const labels = inspect.Config?.Labels ?? {};
+        imageSetupScript2 = labels[LABELS2.setupScript] || undefined;
+      } catch {}
+      return { image: cached, remainingPackages: [], imageSetupScript: imageSetupScript2 };
+    }
+    const baseImage = adapter.image;
+    let bestImage = baseImage;
+    let remainingPackages = requestedPackages ?? [];
+    let imageSetupScript;
+    if (requestedPackages && requestedPackages.length > 0) {
+      const { LABELS: LABELS2, normalizePackages: normalizePackages2 } = await Promise.resolve().then(() => (init_image_builder(), exports_image_builder));
+      const normalizedReq = normalizePackages2(requestedPackages);
+      const images = await this.docker.listImages({
+        filters: {
+          label: [`${LABELS2.runtime}=${adapter.name}`]
+        }
+      });
+      for (const img of images) {
+        if (!img.RepoTags || img.RepoTags.length === 0) {
+          continue;
+        }
+        const depsLabel = img.Labels?.[LABELS2.dependencies];
+        if (!depsLabel) {
+          continue;
+        }
+        const imgDeps = depsLabel.split(",");
+        if (img.RepoTags[0] && normalizedReq.length === imgDeps.length && normalizedReq.every((p) => imgDeps.includes(p))) {
+          bestImage = img.RepoTags[0];
+          remainingPackages = [];
+          imageSetupScript = img.Labels?.[LABELS2.setupScript] || undefined;
+          logger.debug(`[Docker] Found exact custom image match: ${bestImage}`);
+          break;
+        }
+        if (img.RepoTags[0] && normalizedReq.every((p) => imgDeps.includes(p))) {
+          bestImage = img.RepoTags[0];
+          remainingPackages = [];
+          imageSetupScript = img.Labels?.[LABELS2.setupScript] || undefined;
+          logger.debug(`[Docker] Found superset custom image match: ${bestImage}`);
+        }
       }
     }
-    if (resolvedImage === adapter.image) {
-      const legacyCustomTag = `${adapter.image}-custom`;
+    if (bestImage !== baseImage && imageSetupScript === undefined) {
       try {
-        await this.docker.getImage(legacyCustomTag).inspect();
-        resolvedImage = legacyCustomTag;
+        const { LABELS: LABELS2 } = await Promise.resolve().then(() => (init_image_builder(), exports_image_builder));
+        const inspect = await this.docker.getImage(bestImage).inspect();
+        const labels = inspect.Config?.Labels ?? {};
+        imageSetupScript = labels[LABELS2.setupScript] || undefined;
       } catch {}
     }
-    try {
-      await this.docker.getImage(resolvedImage).inspect();
-    } catch {
-      logger.debug(`[ImageBuilder] Image ${resolvedImage} not found. Building...`);
-      const { buildBaseImages: buildBaseImages2, buildCustomImage: buildCustomImage2 } = await Promise.resolve().then(() => (init_image_builder(), exports_image_builder));
-      if (resolvedImage !== adapter.image && normalizedDeps.length > 0) {
-        try {
-          await this.docker.getImage(adapter.image).inspect();
-        } catch {
-          logger.debug(`[ImageBuilder] Base image ${adapter.image} missing. Building...`);
-          await buildBaseImages2(this.docker, undefined, false, [adapter.name]);
-        }
-        logger.debug(`[ImageBuilder] Building custom image for ${adapter.name}...`);
-        await buildCustomImage2(this.docker, adapter.name, normalizedDeps);
-      } else {
-        logger.debug(`[ImageBuilder] Building base image for ${adapter.name}...`);
+    if (bestImage === baseImage) {
+      try {
+        await this.docker.getImage(baseImage).inspect();
+      } catch {
+        logger.debug(`[Docker] Base image ${baseImage} not found. Building...`);
+        const { buildBaseImages: buildBaseImages2 } = await Promise.resolve().then(() => (init_image_builder(), exports_image_builder));
         await buildBaseImages2(this.docker, undefined, false, [adapter.name]);
       }
     }
-    this.imageCache.set(cacheKey, resolvedImage);
-    return resolvedImage;
+    if (remainingPackages.length === 0) {
+      this.imageCache.set(cacheKey, bestImage);
+    }
+    return { image: bestImage, remainingPackages, imageSetupScript };
   }
   ensurePool() {
     if (!this.pool) {
@@ -2511,7 +2630,9 @@ class DockerIsol8 {
   async executeEphemeral(req, startTime) {
     const adapter = this.getAdapter(req.runtime);
     const timeoutMs = req.timeoutMs ?? this.defaultTimeoutMs;
-    const image = await this.resolveImage(adapter);
+    const resolved = await this.resolveImage(adapter, req.installPackages);
+    const image = resolved.image;
+    const execWorkdir = req.workdir ? resolveWorkdir(req.workdir) : SANDBOX_WORKDIR;
     const pool = this.ensurePool();
     const container = await pool.acquire(image);
     let startStats;
@@ -2542,8 +2663,14 @@ class DockerIsol8 {
         await this.volumeManager.writeFileViaExec(container, filePath, req.code);
         rawCmd = adapter.getCommand(req.code, filePath);
       }
-      if (req.installPackages?.length) {
-        await this.executionManager.installPackages(container, req.runtime, req.installPackages, timeoutMs);
+      if (resolved.remainingPackages.length > 0) {
+        await this.executionManager.installPackages(container, req.runtime, resolved.remainingPackages, timeoutMs);
+      }
+      if (resolved.imageSetupScript) {
+        await this.executionManager.runSetupScript(container, resolved.imageSetupScript, timeoutMs, this.volumeManager);
+      }
+      if (req.setupScript) {
+        await this.executionManager.runSetupScript(container, req.setupScript, timeoutMs, this.volumeManager);
       }
       const timeoutSec = Math.ceil(timeoutMs / 1000);
       let cmd;
@@ -2565,7 +2692,7 @@ class DockerIsol8 {
         Env: this.executionManager.buildEnv(req.env, this.networkManager.proxyPort, this.network, this.networkFilter),
         AttachStdout: true,
         AttachStderr: true,
-        WorkingDir: SANDBOX_WORKDIR,
+        WorkingDir: execWorkdir,
         User: "sandbox"
       });
       const start = performance.now();
@@ -2625,8 +2752,13 @@ class DockerIsol8 {
   async executePersistent(req, startTime) {
     const adapter = this.getAdapter(req.runtime);
     const timeoutMs = req.timeoutMs ?? this.defaultTimeoutMs;
+    const execWorkdir = req.workdir ? resolveWorkdir(req.workdir) : SANDBOX_WORKDIR;
+    let remainingPackages = req.installPackages ?? [];
+    let imageSetupScript;
     if (!this.container) {
-      await this.startPersistentContainer(adapter);
+      const started = await this.startPersistentContainer(adapter, req.installPackages);
+      remainingPackages = started.remainingPackages;
+      imageSetupScript = started.imageSetupScript;
     } else if (this.persistentRuntime?.name !== adapter.name) {
       throw new Error(`Cannot switch runtime from "${this.persistentRuntime?.name}" to "${adapter.name}". Each persistent container supports a single runtime. Create a new Isol8 instance for a different runtime.`);
     }
@@ -2640,8 +2772,14 @@ class DockerIsol8 {
     }
     const rawCmd = adapter.getCommand(req.code, filePath);
     const timeoutSec = Math.ceil(timeoutMs / 1000);
-    if (req.installPackages?.length) {
-      await this.executionManager.installPackages(this.container, req.runtime, req.installPackages, timeoutMs);
+    if (remainingPackages.length > 0) {
+      await this.executionManager.installPackages(this.container, req.runtime, remainingPackages, timeoutMs);
+    }
+    if (imageSetupScript) {
+      await this.executionManager.runSetupScript(this.container, imageSetupScript, timeoutMs, this.volumeManager);
+    }
+    if (req.setupScript) {
+      await this.executionManager.runSetupScript(this.container, req.setupScript, timeoutMs, this.volumeManager);
     }
     let cmd;
     if (req.stdin) {
@@ -2658,7 +2796,7 @@ class DockerIsol8 {
       Env: execEnv,
       AttachStdout: true,
       AttachStderr: true,
-      WorkingDir: SANDBOX_WORKDIR,
+      WorkingDir: execWorkdir,
       User: "sandbox"
     });
     const start = performance.now();
@@ -2713,10 +2851,10 @@ class DockerIsol8 {
   async retrieveFiles(container, paths) {
     return this.volumeManager.retrieveFiles(container, paths);
   }
-  async startPersistentContainer(adapter) {
-    const image = await this.resolveImage(adapter);
+  async startPersistentContainer(adapter, requestedPackages) {
+    const resolved = await this.resolveImage(adapter, requestedPackages);
     this.container = await this.docker.createContainer({
-      Image: image,
+      Image: resolved.image,
       Cmd: ["sleep", "infinity"],
       WorkingDir: SANDBOX_WORKDIR,
       Env: this.executionManager.buildEnv(undefined, this.networkManager.proxyPort, this.network, this.networkFilter),
@@ -2732,6 +2870,10 @@ class DockerIsol8 {
     await this.networkManager.startProxy(this.container);
     await this.networkManager.setupIptables(this.container);
     this.persistentRuntime = adapter;
+    return {
+      remainingPackages: resolved.remainingPackages,
+      imageSetupScript: resolved.imageSetupScript
+    };
   }
   getAdapter(runtime) {
     return RuntimeRegistry.get(runtime);
@@ -2844,7 +2986,7 @@ init_logger();
 // package.json
 var package_default = {
   name: "@isol8/core",
-  version: "0.16.0",
+  version: "0.18.0",
   description: "Sandboxed code execution engine for AI agents and apps (Docker, runtime and network controls)",
   author: "Illusion47586",
   license: "MIT",
@@ -2912,8 +3054,7 @@ var VERSION = package_default.version;
 export {
   logger,
   loadConfig,
-  getCustomImageTag,
-  buildCustomImages,
+  imageExists,
   buildCustomImage,
   buildBaseImages,
   bashAdapter,
@@ -2923,9 +3064,10 @@ export {
   RemoteIsol8,
   PythonAdapter,
   NodeAdapter,
+  LABELS,
   DockerIsol8,
   DenoAdapter,
   BunAdapter
 };
 
-//# debugId=A775CBFF7103831D64756E2164756E21
+//# debugId=014F8E5DF8C3A76364756E2164756E21