@isol8/core 0.17.0 → 0.19.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;
@@ -50,6 +48,37 @@ var init_adapter = __esm(() => {
   };
 });
 
+// src/runtime/adapters/agent.ts
+function shellQuote(s) {
+  return `'${s.replace(/'/g, "'\\''")}'`;
+}
+var SANDBOX_SYSTEM_PROMPT, AgentAdapter;
+var init_agent = __esm(() => {
+  SANDBOX_SYSTEM_PROMPT = "You are running inside an isol8 sandbox — a Docker container with strict " + "resource limits and controlled network access. isol8 exists to execute " + "untrusted code safely: outbound network is filtered to a whitelist, the " + "filesystem is ephemeral, and some system calls are restricted. Work within " + "these constraints: do not assume open internet access, do not rely on " + "persistent state across runs, and do not attempt to escape the sandbox.";
+  AgentAdapter = {
+    name: "agent",
+    image: "isol8:agent",
+    getCommand(code) {
+      return [
+        "bash",
+        "-c",
+        `pi --no-session --append-system-prompt ${shellQuote(SANDBOX_SYSTEM_PROMPT)} -p ${shellQuote(code)}`
+      ];
+    },
+    getCommandWithOptions(code, options) {
+      const flags = options.agentFlags ? `${options.agentFlags} ` : "";
+      return [
+        "bash",
+        "-c",
+        `pi --no-session --append-system-prompt ${shellQuote(SANDBOX_SYSTEM_PROMPT)} ${flags}-p ${shellQuote(code)}`
+      ];
+    },
+    getFileExtension() {
+      return ".txt";
+    }
+  };
+});
+
 // src/runtime/adapters/bash.ts
 var bashAdapter;
 var init_bash = __esm(() => {
@@ -151,12 +180,14 @@ var init_python = __esm(() => {
 // src/runtime/index.ts
 var init_runtime = __esm(() => {
   init_adapter();
+  init_agent();
   init_bash();
   init_bun();
   init_deno();
   init_node();
   init_python();
   init_adapter();
+  init_agent();
   init_bash();
   init_bun();
   init_deno();
@@ -167,6 +198,7 @@ var init_runtime = __esm(() => {
   RuntimeRegistry.register(BunAdapter);
   RuntimeRegistry.register(bashAdapter);
   RuntimeRegistry.register(DenoAdapter);
+  RuntimeRegistry.register(AgentAdapter);
 });
 
 // src/utils/logger.ts
@@ -200,11 +232,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 +333,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 +391,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 +478,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 +506,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 +524,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) {
+        onProgress?.({ runtime: String(runtime), status: "building", message: event.stream });
+      } else if (event.error) {
+        onProgress?.({ runtime: String(runtime), status: "error", message: event.error });
+      }
     });
   });
   if (oldImageId) {
@@ -564,7 +602,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"];
 });
@@ -828,7 +869,6 @@ var DEFAULT_CONFIG = {
   },
   poolStrategy: "fast",
   poolSize: { clean: 1, dirty: 1 },
-  dependencies: {},
   security: {
     seccomp: "strict"
   },
@@ -869,6 +909,7 @@ var DEFAULT_CONFIG = {
     defaultTtlMs: 86400000,
     cleanupIntervalMs: 3600000
   },
+  prebuiltImages: [],
   debug: false
 };
 function loadConfig(cwd) {
@@ -903,10 +944,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
@@ -926,6 +963,7 @@ function mergeConfig(defaults, overrides) {
       ...defaults.auth,
       ...overrides.auth
     },
+    prebuiltImages: overrides.prebuiltImages ?? defaults.prebuiltImages,
     debug: overrides.debug ?? defaults.debug
   };
 }
@@ -1345,11 +1383,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 {
@@ -1382,6 +1418,8 @@ class ExecutionManager {
         return ["npm", "install", "--prefix", "/sandbox", ...packages];
       case "bun":
         return ["bun", "install", "-g", "--global-dir=/sandbox/.bun-global", ...packages];
+      case "agent":
+        return ["bun", "install", "-g", "--global-dir=/sandbox/.bun-global", ...packages];
       case "deno":
         return ["sh", "-c", packages.map((p) => `deno cache ${p}`).join(" && ")];
       case "bash":
@@ -1409,7 +1447,7 @@ class ExecutionManager {
       env.push("npm_config_fetch_retry_mintimeout=1000");
       env.push("NPM_CONFIG_FETCH_RETRY_MAXTIMEOUT=2000");
       env.push("npm_config_fetch_retry_maxtimeout=2000");
-    } else if (runtime === "bun") {
+    } else if (runtime === "bun" || runtime === "agent") {
       env.push("BUN_INSTALL_GLOBAL_DIR=/sandbox/.bun-global");
       env.push("BUN_INSTALL_CACHE_DIR=/sandbox/.bun-cache");
       env.push("BUN_INSTALL_BIN=/sandbox/.bun-global/bin");
@@ -1453,6 +1491,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;
@@ -1707,6 +1802,7 @@ class NetworkManager {
   }
 }
 // src/engine/managers/volume-manager.ts
+init_utils();
 import { PassThrough as PassThrough2 } from "node:stream";
 
 class VolumeManager {
@@ -1787,13 +1883,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 = {};
@@ -1805,19 +1901,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
@@ -2099,6 +2195,7 @@ function calculateResourceDelta(before, after) {
 }
 
 // src/engine/docker.ts
+init_utils();
 var SANDBOX_WORKDIR = "/sandbox";
 var MAX_OUTPUT_BYTES = 1024 * 1024;
 
@@ -2123,7 +2220,6 @@ class DockerIsol8 {
   logNetwork;
   poolStrategy;
   poolSize;
-  dependencies;
   auditLogger;
   remoteCodePolicy;
   networkManager;
@@ -2173,7 +2269,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"],
@@ -2217,7 +2312,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}`);
       }
@@ -2251,6 +2347,7 @@ class DockerIsol8 {
     await this.semaphore.acquire();
     const startTime = Date.now();
     try {
+      this.validateAgentRuntime(req);
       const request = await this.resolveExecutionRequest(req);
       const result = this.mode === "persistent" ? await this.executePersistent(request, startTime) : await this.executeEphemeral(request, startTime);
       return result;
@@ -2374,17 +2471,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;
@@ -2392,10 +2489,13 @@ class DockerIsol8 {
   async* executeStream(req) {
     await this.semaphore.acquire();
     try {
+      this.validateAgentRuntime(req);
       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"],
@@ -2412,15 +2512,21 @@ 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)) {
             await this.volumeManager.writeFileViaExec(container, fPath, fContent);
           }
         }
-        const rawCmd = adapter.getCommand(request.code, filePath);
+        const rawCmd = this.buildAdapterCommand(adapter, request, filePath);
         const timeoutSec = Math.ceil(timeoutMs / 1000);
         let cmd;
         if (request.stdin) {
@@ -2436,7 +2542,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 });
@@ -2454,55 +2560,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) {
@@ -2527,7 +2668,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;
@@ -2545,21 +2688,27 @@ class DockerIsol8 {
       let rawCmd;
       if (canUseInline) {
         try {
-          rawCmd = adapter.getCommand(req.code);
+          rawCmd = this.buildAdapterCommand(adapter, req);
         } catch {
           const ext = req.fileExtension ?? adapter.getFileExtension();
           const filePath = `${SANDBOX_WORKDIR}/main${ext}`;
           await this.volumeManager.writeFileViaExec(container, filePath, req.code);
-          rawCmd = adapter.getCommand(req.code, filePath);
+          rawCmd = this.buildAdapterCommand(adapter, req, filePath);
         }
       } else {
         const ext = req.fileExtension ?? adapter.getFileExtension();
         const filePath = `${SANDBOX_WORKDIR}/main${ext}`;
         await this.volumeManager.writeFileViaExec(container, filePath, req.code);
-        rawCmd = adapter.getCommand(req.code, filePath);
+        rawCmd = this.buildAdapterCommand(adapter, req, filePath);
+      }
+      if (resolved.remainingPackages.length > 0) {
+        await this.executionManager.installPackages(container, req.runtime, resolved.remainingPackages, timeoutMs);
       }
-      if (req.installPackages?.length) {
-        await this.executionManager.installPackages(container, req.runtime, req.installPackages, 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;
@@ -2581,7 +2730,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();
@@ -2641,8 +2790,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.`);
     }
@@ -2654,10 +2808,16 @@ class DockerIsol8 {
         await this.volumeManager.putFile(this.container, fPath, fContent);
       }
     }
-    const rawCmd = adapter.getCommand(req.code, filePath);
+    const rawCmd = this.buildAdapterCommand(adapter, req, 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) {
@@ -2674,7 +2834,7 @@ class DockerIsol8 {
       Env: execEnv,
       AttachStdout: true,
       AttachStderr: true,
-      WorkingDir: SANDBOX_WORKDIR,
+      WorkingDir: execWorkdir,
       User: "sandbox"
     });
     const start = performance.now();
@@ -2729,10 +2889,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),
@@ -2748,10 +2908,35 @@ 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);
   }
+  validateAgentRuntime(req) {
+    if (req.runtime !== "agent") {
+      return;
+    }
+    if (this.network !== "filtered") {
+      throw new Error(`Agent runtime requires network mode "filtered". The AI coding agent needs network access to reach its LLM provider API. Use --net filtered --allow "api.anthropic.com" (or your provider's domain).`);
+    }
+    const whitelist = this.networkFilter?.whitelist ?? [];
+    if (whitelist.length === 0) {
+      throw new Error(`Agent runtime requires at least one network whitelist entry. The AI coding agent needs to reach its LLM provider API. Use --allow "api.anthropic.com" (or your provider's domain).`);
+    }
+  }
+  buildAdapterCommand(adapter, req, filePath) {
+    if (adapter.getCommandWithOptions) {
+      return adapter.getCommandWithOptions(req.code, {
+        filePath,
+        agentFlags: req.agentFlags
+      });
+    }
+    return adapter.getCommand(req.code, filePath);
+  }
   buildHostConfig() {
     const config = {
       Memory: parseMemoryLimit(this.memoryLimit),
@@ -2860,7 +3045,7 @@ init_logger();
 // package.json
 var package_default = {
   name: "@isol8/core",
-  version: "0.17.0",
+  version: "0.19.0",
   description: "Sandboxed code execution engine for AI agents and apps (Docker, runtime and network controls)",
   author: "Illusion47586",
   license: "MIT",
@@ -2928,8 +3113,7 @@ var VERSION = package_default.version;
 export {
   logger,
   loadConfig,
-  getCustomImageTag,
-  buildCustomImages,
+  imageExists,
   buildCustomImage,
   buildBaseImages,
   bashAdapter,
@@ -2939,9 +3123,11 @@ export {
   RemoteIsol8,
   PythonAdapter,
   NodeAdapter,
+  LABELS,
   DockerIsol8,
   DenoAdapter,
-  BunAdapter
+  BunAdapter,
+  AgentAdapter
 };
 
-//# debugId=52A84C2338D09E5564756E2164756E21
+//# debugId=944C4599E61DE68D64756E2164756E21