@google/adk 1.6.0 → 2.1.0

package/dist/cjs/code_executors/agent_engine_sandbox_code_executor.js

@@ -9,6 +9,7 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -63,6 +64,7 @@ function mapLanguage(lang) {
       throw new Error(`Unsupported language for Agent Engine Sandbox: ${lang}`);
   }
 }
+__name(mapLanguage, "mapLanguage");
 let AgentEngineSandboxCodeExecutor = class extends import_base_code_executor.BaseCodeExecutor {
   constructor(options = {}) {
     super();
@@ -296,6 +298,7 @@ let AgentEngineSandboxCodeExecutor = class extends import_base_code_executor.Bas
     return sandboxName;
   }
 };
+__name(AgentEngineSandboxCodeExecutor, "AgentEngineSandboxCodeExecutor");
 AgentEngineSandboxCodeExecutor = __decorateClass([
   import_experimental.experimental
 ], AgentEngineSandboxCodeExecutor);

package/dist/cjs/code_executors/base_code_executor.js

@@ -9,6 +9,7 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -34,14 +35,15 @@ module.exports = __toCommonJS(base_code_executor_exports);
  * SPDX-License-Identifier: Apache-2.0
  */
 var _a;
-const BASE_CODE_EXECUTOR_SIGNATURE_SYMBOL = Symbol.for(
+const BASE_CODE_EXECUTOR_SIGNATURE_SYMBOL = /* @__PURE__ */ Symbol.for(
   "google.adk.baseCodeExecutor"
 );
 function isBaseCodeExecutor(obj) {
   return typeof obj === "object" && obj !== null && BASE_CODE_EXECUTOR_SIGNATURE_SYMBOL in obj && obj[BASE_CODE_EXECUTOR_SIGNATURE_SYMBOL] === true;
 }
+__name(isBaseCodeExecutor, "isBaseCodeExecutor");
 _a = BASE_CODE_EXECUTOR_SIGNATURE_SYMBOL;
-class BaseCodeExecutor {
+const _BaseCodeExecutor = class _BaseCodeExecutor {
   constructor() {
     /** A unique symbol to identify BaseCodeExecutor class. */
     this[_a] = true;
@@ -84,7 +86,9 @@ class BaseCodeExecutor {
      */
     this.executionResultDelimiters = ["```tool_output\n", "\n```"];
   }
-}
+};
+__name(_BaseCodeExecutor, "BaseCodeExecutor");
+let BaseCodeExecutor = _BaseCodeExecutor;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BaseCodeExecutor,

package/dist/cjs/code_executors/built_in_code_executor.js

@@ -9,6 +9,7 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -36,13 +37,14 @@ var import_base_code_executor = require("./base_code_executor.js");
  * SPDX-License-Identifier: Apache-2.0
  */
 var _a, _b;
-const BUILT_IN_CODE_EXECUTOR_SIGNATURE_SYMBOL = Symbol.for(
+const BUILT_IN_CODE_EXECUTOR_SIGNATURE_SYMBOL = /* @__PURE__ */ Symbol.for(
   "google.adk.builtInCodeExecutor"
 );
 function isBuiltInCodeExecutor(obj) {
   return typeof obj === "object" && obj !== null && BUILT_IN_CODE_EXECUTOR_SIGNATURE_SYMBOL in obj && obj[BUILT_IN_CODE_EXECUTOR_SIGNATURE_SYMBOL] === true;
 }
-class BuiltInCodeExecutor extends (_b = import_base_code_executor.BaseCodeExecutor, _a = BUILT_IN_CODE_EXECUTOR_SIGNATURE_SYMBOL, _b) {
+__name(isBuiltInCodeExecutor, "isBuiltInCodeExecutor");
+const _BuiltInCodeExecutor = class _BuiltInCodeExecutor extends (_b = import_base_code_executor.BaseCodeExecutor, _a = BUILT_IN_CODE_EXECUTOR_SIGNATURE_SYMBOL, _b) {
   constructor() {
     super(...arguments);
     /** A unique symbol to identify BuiltInCodeExecutor class. */
@@ -66,7 +68,9 @@ class BuiltInCodeExecutor extends (_b = import_base_code_executor.BaseCodeExecut
       `Gemini code execution tool is not supported for model ${llmRequest.model}`
     );
   }
-}
+};
+__name(_BuiltInCodeExecutor, "BuiltInCodeExecutor");
+let BuiltInCodeExecutor = _BuiltInCodeExecutor;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BuiltInCodeExecutor,

package/dist/cjs/code_executors/code_execution_utils.js

@@ -9,6 +9,7 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -59,6 +60,7 @@ var CodeExecutionLanguage = /* @__PURE__ */ ((CodeExecutionLanguage2) => {
 function getEncodedFileContent(data) {
   return (0, import_env_aware_utils.isBase64Encoded)(data) ? data : (0, import_env_aware_utils.base64Encode)(data);
 }
+__name(getEncodedFileContent, "getEncodedFileContent");
 function extractCodeAndTruncateContent(content, codeBlockDelimiters) {
   var _a;
   if (!((_a = content.parts) == null ? void 0 : _a.length)) {
@@ -68,7 +70,7 @@ function extractCodeAndTruncateContent(content, codeBlockDelimiters) {
     const part = content.parts[i];
     if (part.executableCode && (i === content.parts.length - 1 || !content.parts[i + 1].codeExecutionResult)) {
       content.parts = content.parts.slice(0, i + 1);
-      return part.executableCode.code;
+      return part.executableCode.code || "";
     }
   }
   const textParts = content.parts.filter((part) => part.text);
@@ -95,6 +97,7 @@ function extractCodeAndTruncateContent(content, codeBlockDelimiters) {
   content.parts.push(buildExecutableCodePart(codeStr));
   return codeStr;
 }
+__name(extractCodeAndTruncateContent, "extractCodeAndTruncateContent");
 function buildExecutableCodePart(code) {
   return {
     text: code,
@@ -104,6 +107,7 @@ function buildExecutableCodePart(code) {
     }
   };
 }
+__name(buildExecutableCodePart, "buildExecutableCodePart");
 function buildCodeExecutionResultPart(codeExecutionResult) {
   if (codeExecutionResult.stderr) {
     return {
@@ -132,6 +136,7 @@ ${codeExecutionResult.stdout}
     }
   };
 }
+__name(buildCodeExecutionResultPart, "buildCodeExecutionResultPart");
 function convertCodeExecutionParts(content, codeBlockDelimiter, executionResultDelimiters) {
   var _a;
   if (!((_a = content.parts) == null ? void 0 : _a.length)) {
@@ -140,7 +145,7 @@ function convertCodeExecutionParts(content, codeBlockDelimiter, executionResultD
   const lastPart = content.parts[content.parts.length - 1];
   if (lastPart.executableCode) {
     content.parts[content.parts.length - 1] = {
-      text: codeBlockDelimiter[0] + lastPart.executableCode.code + codeBlockDelimiter[1]
+      text: codeBlockDelimiter[0] + (lastPart.executableCode.code || "") + codeBlockDelimiter[1]
     };
   } else if (content.parts.length == 1 && lastPart.codeExecutionResult) {
     content.parts[content.parts.length - 1] = {
@@ -149,6 +154,7 @@ function convertCodeExecutionParts(content, codeBlockDelimiter, executionResultD
     content.role = "user";
   }
 }
+__name(convertCodeExecutionParts, "convertCodeExecutionParts");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CodeExecutionLanguage,

package/dist/cjs/code_executors/code_executor_context.js

@@ -9,6 +9,7 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -39,7 +40,7 @@ const PROCESSED_FILE_NAMES_KEY = "processed_input_files";
 const INPUT_FILE_KEY = "_code_executor_input_files";
 const ERROR_COUNT_KEY = "_code_executor_error_counts";
 const CODE_EXECUTION_RESULTS_KEY = "_code_execution_results";
-class CodeExecutorContext {
+const _CodeExecutorContext = class _CodeExecutorContext {
   constructor(sessionState) {
     this.sessionState = sessionState;
     var _a;
@@ -191,7 +192,9 @@ class CodeExecutorContext {
   getCodeExecutionContext() {
     return this.sessionState.get(CONTEXT_KEY) || {};
   }
-}
+};
+__name(_CodeExecutorContext, "CodeExecutorContext");
+let CodeExecutorContext = _CodeExecutorContext;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CodeExecutorContext

package/dist/cjs/code_executors/container_code_executor.js

@@ -0,0 +1,186 @@
+/**
+  * @license
+  * Copyright 2026 Google LLC
+  * SPDX-License-Identifier: Apache-2.0
+  */
+
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+var container_code_executor_exports = {};
+__export(container_code_executor_exports, {
+  ContainerCodeExecutor: () => ContainerCodeExecutor
+});
+module.exports = __toCommonJS(container_code_executor_exports);
+var path = __toESM(require("node:path"), 1);
+var import_experimental = require("../utils/experimental.js");
+var import_logger = require("../utils/logger.js");
+var import_base_code_executor = require("./base_code_executor.js");
+var import_code_execution_utils = require("./code_execution_utils.js");
+var import_docker_container = require("./docker_container.js");
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const DEFAULT_IMAGE_TAG = "adk-code-executor:latest";
+const DEFAULT_TIMEOUT_SECONDS = 300;
+const TIMEOUT_COMMAND = ["timeout", "-s", "KILL"];
+const LANGUAGE_RUNTIME_COMMAND_MAP = {
+  [import_code_execution_utils.CodeExecutionLanguage.PYTHON]: ["python3", "-c"],
+  [import_code_execution_utils.CodeExecutionLanguage.JAVASCRIPT]: ["node", "-e"],
+  [import_code_execution_utils.CodeExecutionLanguage.TYPESCRIPT]: ["tsx", "--eval"],
+  [import_code_execution_utils.CodeExecutionLanguage.SHELL]: ["sh", "-c"]
+};
+let ContainerCodeExecutor = class extends import_base_code_executor.BaseCodeExecutor {
+  constructor(options = {}) {
+    var _a, _b, _c;
+    super();
+    if (!options.image && !options.dockerPath) {
+      throw new Error(
+        "Either image or dockerPath must be set for ContainerCodeExecutor."
+      );
+    }
+    this.timeoutSeconds = (_a = options.timeoutSeconds) != null ? _a : DEFAULT_TIMEOUT_SECONDS;
+    if (this.timeoutSeconds <= 0) {
+      throw new Error(
+        "timeoutSeconds must be greater than 0 for ContainerCodeExecutor."
+      );
+    }
+    this.dockerPath = options.dockerPath ? path.resolve(options.dockerPath) : void 0;
+    this.containerOptions = {
+      image: (_b = options.image) != null ? _b : DEFAULT_IMAGE_TAG,
+      networkEnabled: (_c = options.networkEnabled) != null ? _c : false,
+      baseUrl: options.baseUrl,
+      docker: options.docker
+    };
+    defineFrozenFalse(this, "stateful");
+    defineFrozenFalse(this, "optimizeDataFile");
+  }
+  async executeCode(params) {
+    const { code, language } = params.codeExecutionInput;
+    const command = LANGUAGE_RUNTIME_COMMAND_MAP[language];
+    if (!command) {
+      throw new Error(
+        `Unsupported language for ContainerCodeExecutor: ${language}. Supported: ${Object.keys(LANGUAGE_RUNTIME_COMMAND_MAP).join(", ")}.`
+      );
+    }
+    await this.ensureContainer();
+    const { stdout, stderr, exitCode } = await this.container.execute(
+      [...TIMEOUT_COMMAND, String(this.timeoutSeconds), ...command, code],
+      this.timeoutSeconds
+    );
+    import_logger.logger.debug(`Executed ${language} code:
+\`\`\`
+${code}
+\`\`\``);
+    return {
+      stdout,
+      stderr: this.describeExit(stderr, exitCode),
+      outputFiles: []
+    };
+  }
+  /**
+   * Turns a non-zero exit into stderr the model can see. An empty stderr maps
+   * to `OUTCOME_OK` downstream, so a program that exits non-zero without
+   * writing stderr would otherwise look successful (matching
+   * `UnsafeLocalCodeExecutor`).
+   */
+  describeExit(stderr, exitCode) {
+    if (exitCode === import_docker_container.TIMEOUT_EXIT_CODE) {
+      const message = `Code execution timed out after ${this.timeoutSeconds} seconds.`;
+      return stderr ? `${stderr}
+${message}` : message;
+    }
+    if (exitCode !== 0 && exitCode !== null && !stderr) {
+      return `Exit code ${exitCode}`;
+    }
+    return stderr;
+  }
+  /**
+   * Stops and removes the container. Safe to call when no container has been
+   * started; provided for deterministic teardown in tests and app shutdown.
+   */
+  async close() {
+    const container = this.container;
+    this.container = void 0;
+    this.initPromise = void 0;
+    await (container == null ? void 0 : container.stop());
+  }
+  /** Lazily builds/starts the container exactly once. */
+  ensureContainer() {
+    if (!this.initPromise) {
+      this.initPromise = this.initContainer().catch((error) => {
+        this.initPromise = void 0;
+        throw error;
+      });
+    }
+    return this.initPromise;
+  }
+  async initContainer() {
+    const container = new import_docker_container.DockerContainer(this.containerOptions);
+    if (this.dockerPath) {
+      await container.build(this.dockerPath);
+    }
+    await container.start();
+    this.container = container;
+    const { exitCode } = await container.execute(
+      ["which", "python3"],
+      this.timeoutSeconds
+    );
+    if (exitCode !== 0) {
+      throw new Error("python3 is not installed in the container.");
+    }
+  }
+};
+__name(ContainerCodeExecutor, "ContainerCodeExecutor");
+ContainerCodeExecutor = __decorateClass([
+  import_experimental.experimental
+], ContainerCodeExecutor);
+function defineFrozenFalse(target, key) {
+  Object.defineProperty(target, key, {
+    value: false,
+    writable: false,
+    enumerable: true,
+    configurable: false
+  });
+}
+__name(defineFrozenFalse, "defineFrozenFalse");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ContainerCodeExecutor
+});

package/dist/cjs/code_executors/docker_container.js

@@ -0,0 +1,282 @@
+/**
+  * @license
+  * Copyright 2026 Google LLC
+  * SPDX-License-Identifier: Apache-2.0
+  */
+
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var docker_container_exports = {};
+__export(docker_container_exports, {
+  DockerContainer: () => DockerContainer,
+  TIMEOUT_EXIT_CODE: () => TIMEOUT_EXIT_CODE
+});
+module.exports = __toCommonJS(docker_container_exports);
+var fs = __toESM(require("node:fs/promises"), 1);
+var import_node_stream = require("node:stream");
+var import_consumers = require("node:stream/consumers");
+var import_promises = require("node:timers/promises");
+var import_logger = require("../utils/logger.js");
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const TIMEOUT_EXIT_CODE = 124;
+const STREAM_WAIT_GRACE_SECONDS = 5;
+const MAX_INSPECT_ATTEMPTS = 50;
+const INSPECT_POLL_MS = 100;
+const KEEP_ALIVE_COMMAND = ["tail", "-f", "/dev/null"];
+let dockerodeCtor;
+function loadDockerodeCtor() {
+  dockerodeCtor != null ? dockerodeCtor : dockerodeCtor = Promise.resolve().then(() => __toESM(require("dockerode"), 1)).then(
+    (mod) => mod.default,
+    () => {
+      throw new Error(
+        "The `dockerode` package is required to use ContainerCodeExecutor. Install it with `npm install dockerode`."
+      );
+    }
+  );
+  return dockerodeCtor;
+}
+__name(loadDockerodeCtor, "loadDockerodeCtor");
+const activeContainers = /* @__PURE__ */ new Set();
+let exitHooksRegistered = false;
+async function stopAndRemove(container) {
+  if (!container) {
+    return true;
+  }
+  try {
+    await container.stop();
+  } catch (error) {
+    import_logger.logger.debug(`Container ${container.id} was not running: ${error}`);
+  }
+  try {
+    await container.remove({ force: true });
+    return true;
+  } catch (error) {
+    import_logger.logger.error(`Failed to remove container ${container.id}: ${error}`);
+    return false;
+  }
+}
+__name(stopAndRemove, "stopAndRemove");
+async function cleanupContainers() {
+  for (const container of activeContainers) {
+    if (await stopAndRemove(container)) {
+      activeContainers.delete(container);
+    }
+  }
+}
+__name(cleanupContainers, "cleanupContainers");
+async function handleTerminationSignal(signal) {
+  await cleanupContainers();
+  process.kill(process.pid, signal);
+}
+__name(handleTerminationSignal, "handleTerminationSignal");
+function registerExitHooks() {
+  if (exitHooksRegistered) {
+    return;
+  }
+  exitHooksRegistered = true;
+  process.once("beforeExit", cleanupContainers);
+  process.once("SIGINT", handleTerminationSignal);
+  process.once("SIGTERM", handleTerminationSignal);
+}
+__name(registerExitHooks, "registerExitHooks");
+const PROTOCOL_BY_SCHEME = {
+  "https:": "https",
+  "ssh:": "ssh"
+};
+async function inspectExitCode(exec) {
+  for (let attempt = 0; attempt < MAX_INSPECT_ATTEMPTS; attempt++) {
+    const info = await exec.inspect();
+    if (!info.Running) {
+      return info.ExitCode;
+    }
+    await (0, import_promises.setTimeout)(INSPECT_POLL_MS);
+  }
+  return (await exec.inspect()).ExitCode;
+}
+__name(inspectExitCode, "inspectExitCode");
+function parseBaseUrl(baseUrl) {
+  var _a;
+  const url = new URL(baseUrl);
+  if (url.protocol === "unix:") {
+    return { socketPath: url.pathname };
+  }
+  return {
+    host: url.hostname,
+    port: url.port || void 0,
+    protocol: (_a = PROTOCOL_BY_SCHEME[url.protocol]) != null ? _a : "http"
+  };
+}
+__name(parseBaseUrl, "parseBaseUrl");
+const _DockerContainer = class _DockerContainer {
+  constructor(options) {
+    this.options = options;
+  }
+  /**
+   * Builds the image from a directory containing a Dockerfile. `src` is the raw
+   * directory listing; unlike the Docker CLI this does not honor
+   * `.dockerignore`.
+   */
+  async build(dockerPath) {
+    try {
+      await fs.access(dockerPath);
+    } catch {
+      throw new Error(`Invalid Docker path: ${dockerPath}`);
+    }
+    const client = await this.getClient();
+    import_logger.logger.debug("Building Docker image...");
+    const stream = await client.buildImage(
+      { context: dockerPath, src: await fs.readdir(dockerPath) },
+      { t: this.options.image }
+    );
+    await new Promise((resolve, reject) => {
+      client.modem.followProgress(
+        stream,
+        (error) => error ? reject(error) : resolve()
+      );
+    });
+    import_logger.logger.debug(`Docker image ${this.options.image} built.`);
+  }
+  /**
+   * Creates and starts the container, registering it for cleanup on process
+   * exit. Throws if already started: overwriting the handle would orphan the
+   * running container. Call {@link stop} first.
+   */
+  async start() {
+    if (this.container) {
+      throw new Error("Container is already started.");
+    }
+    const client = await this.getClient();
+    import_logger.logger.debug("Starting container...");
+    this.container = await client.createContainer({
+      Image: this.options.image,
+      Tty: true,
+      Cmd: KEEP_ALIVE_COMMAND,
+      NetworkDisabled: !this.options.networkEnabled,
+      HostConfig: { CapDrop: ["ALL"], SecurityOpt: ["no-new-privileges"] }
+    });
+    await this.container.start();
+    activeContainers.add(this.container);
+    registerExitHooks();
+    import_logger.logger.debug(`Container ${this.container.id} started.`);
+  }
+  /**
+   * Runs a command inside the container and returns its decoded output. The
+   * exec is created without a TTY so the stream stays multiplexed and can be
+   * split into stdout and stderr via `modem.demuxStream`.
+   *
+   * `timeoutSeconds` bounds the wait, not the in-container run: a process that
+   * keeps the exec's stdio open (e.g. a surviving background child) means
+   * `'end'` never fires, so without this cap the promise never settles (the
+   * same hang #793 fixed in the local executor). Callers that need to bound the
+   * run itself must wrap the command (see {@link ContainerCodeExecutor}). On a
+   * cap breach the result carries {@link TIMEOUT_EXIT_CODE}.
+   */
+  async execute(cmd, timeoutSeconds) {
+    if (!this.container) {
+      throw new Error("Container is not started.");
+    }
+    const client = await this.getClient();
+    const exec = await this.container.exec({
+      Cmd: cmd,
+      AttachStdout: true,
+      AttachStderr: true
+    });
+    const stream = await exec.start({ hijack: true, stdin: false });
+    const stdout = new import_node_stream.PassThrough();
+    const stderr = new import_node_stream.PassThrough();
+    client.modem.demuxStream(stream, stdout, stderr);
+    const collected = Promise.all([(0, import_consumers.text)(stdout), (0, import_consumers.text)(stderr)]);
+    let timedOut = false;
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(
+        () => {
+          timedOut = true;
+          stream.destroy();
+          resolve();
+        },
+        (timeoutSeconds + STREAM_WAIT_GRACE_SECONDS) * 1e3
+      );
+      timer.unref();
+      stream.on("end", () => {
+        clearTimeout(timer);
+        resolve();
+      });
+      stream.on("error", (error) => {
+        clearTimeout(timer);
+        reject(error);
+      });
+    });
+    stdout.end();
+    stderr.end();
+    const [stdoutText, stderrText] = await collected;
+    if (timedOut) {
+      return {
+        stdout: stdoutText,
+        stderr: stderrText,
+        exitCode: TIMEOUT_EXIT_CODE
+      };
+    }
+    const exitCode = await inspectExitCode(exec);
+    return { stdout: stdoutText, stderr: stderrText, exitCode };
+  }
+  /** Stops and removes the container. Safe to call when never started. */
+  async stop() {
+    const container = this.container;
+    if (!container) {
+      return;
+    }
+    if (await stopAndRemove(container)) {
+      this.container = void 0;
+      activeContainers.delete(container);
+    }
+  }
+  /**
+   * Resolves the Docker client once, lazily loading dockerode when no client
+   * was injected.
+   */
+  async getClient() {
+    var _a, _b;
+    (_b = this.client) != null ? _b : this.client = (_a = this.options.docker) != null ? _a : new (await loadDockerodeCtor())(
+      this.options.baseUrl ? parseBaseUrl(this.options.baseUrl) : void 0
+    );
+    return this.client;
+  }
+};
+__name(_DockerContainer, "DockerContainer");
+let DockerContainer = _DockerContainer;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DockerContainer,
+  TIMEOUT_EXIT_CODE
+});