@google/adk 2.0.0 → 2.1.0

package/dist/esm/agents/sequential_agent.js

@@ -23,7 +23,7 @@ import { BaseAgent } from "./base_agent.js";
 import { isLlmAgent } from "./llm_agent.js";
 import { ReadonlyContext } from "./readonly_context.js";
 const TASK_COMPLETED_TOOL_NAME = "task_completed";
-const SEQUENTIAL_AGENT_SIGNATURE_SYMBOL = Symbol.for(
+const SEQUENTIAL_AGENT_SIGNATURE_SYMBOL = /* @__PURE__ */ Symbol.for(
   "google.adk.sequentialAgent"
 );
 function isSequentialAgent(obj) {

package/dist/esm/apps/app.js

@@ -23,7 +23,7 @@ function validateAppName(name) {
   }
 }
 __name(validateAppName, "validateAppName");
-const APP_SIGNATURE_SYMBOL = Symbol.for("google.adk.app");
+const APP_SIGNATURE_SYMBOL = /* @__PURE__ */ Symbol.for("google.adk.app");
 function isApp(obj) {
   return typeof obj === "object" && obj !== null && APP_SIGNATURE_SYMBOL in obj && obj[APP_SIGNATURE_SYMBOL] === true;
 }

package/dist/esm/artifacts/file_artifact_service.js

@@ -474,10 +474,9 @@ async function* iterateArtifactDirs(dir) {
     );
     if (hasVersions) {
       yield dir;
-      return;
     }
     for (const entry of entries) {
-      if (entry.isDirectory()) {
+      if (entry.isDirectory() && entry.name !== "versions") {
         const subdir = path.join(dir, entry.name);
         for await (const foundDir of iterateArtifactDirs(subdir)) {
           yield foundDir;

package/dist/esm/artifacts/scoped_artifact_service.js

@@ -7,12 +7,21 @@ var __name = (target, value) => __defProp(target, "name", { value, configurable:
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+var _a;
+const SESSION_ARTIFACT_SERVICE_SIGNATURE_SYMBOL = /* @__PURE__ */ Symbol.for(
+  "google.adk.sessionArtifactService"
+);
+_a = SESSION_ARTIFACT_SERVICE_SIGNATURE_SYMBOL;
 const _ScopedArtifactService = class _ScopedArtifactService {
   constructor(delegate, appName, userId, sessionId) {
     this.delegate = delegate;
     this.appName = appName;
     this.userId = userId;
     this.sessionId = sessionId;
+    /**
+     * Brands this class as a session-scoped artifact service.
+     */
+    this[_a] = true;
   }
   async saveArtifact(request) {
     return this.delegate.saveArtifact({

package/dist/esm/artifacts/session_artifact_service.js

@@ -1,7 +1,19 @@
 import {createRequire as topLevelCreateRequire} from 'module';
 const require = topLevelCreateRequire(import.meta.url);
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 /**
  * @license
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+const SESSION_ARTIFACT_SERVICE_SIGNATURE_SYMBOL = /* @__PURE__ */ Symbol.for(
+  "google.adk.sessionArtifactService"
+);
+function isSessionArtifactService(service) {
+  return typeof service === "object" && service !== null && SESSION_ARTIFACT_SERVICE_SIGNATURE_SYMBOL in service && service[SESSION_ARTIFACT_SERVICE_SIGNATURE_SYMBOL] === true;
+}
+__name(isSessionArtifactService, "isSessionArtifactService");
+export {
+  isSessionArtifactService
+};

package/dist/esm/auth/auth_handler.js

@@ -9,6 +9,11 @@ var __name = (target, value) => __defProp(target, "name", { value, configurable:
  */
 import { randomUUID } from "../utils/env_aware_utils.js";
 import { OAuth2CredentialExchanger } from "./oauth2/oauth2_credential_exchanger.js";
+import {
+  createS256CodeChallenge,
+  generateCodeVerifier
+} from "./oauth2/oauth2_utils.js";
+const S256_CODE_CHALLENGE_METHOD = "S256";
 const _AuthHandler = class _AuthHandler {
   constructor(authConfig) {
     this.authConfig = authConfig;
@@ -17,7 +22,16 @@ const _AuthHandler = class _AuthHandler {
     const credentialKey = "temp:" + this.authConfig.credentialKey;
     return state.get(credentialKey);
   }
+  /**
+   * Stores the exchanged credential in the session state.
+   *
+   * @param state The session state to store the credential in.
+   * @throws Error: If the auth config has no credentialKey.
+   */
   async parseAndStoreAuthResponse(state) {
+    if (!this.authConfig.credentialKey) {
+      throw new Error("credentialKey is empty.");
+    }
     const credentialKey = "temp:" + this.authConfig.credentialKey;
     const authSchemeType = this.authConfig.authScheme.type;
     if (!["oauth2", "openIdConnect"].includes(authSchemeType)) {
@@ -73,9 +87,14 @@ const _AuthHandler = class _AuthHandler {
   /**
    * Generates an response containing the auth uri for user to sign in.
    *
+   * When the credential requests PKCE, the URI also carries the S256 code
+   * challenge derived from the credential's code verifier, and the returned
+   * credential carries the verifier the later token exchange must send.
+   *
    * @return An AuthCredential object containing the auth URI and state.
    * @throws Error: If the authorization endpoint is not configured in the
-   *     auth scheme.
+   *     auth scheme, or the credential requests a code challenge method other
+   *     than 'S256'.
    */
   generateAuthUri() {
     const authScheme = this.authConfig.authScheme;
@@ -83,6 +102,13 @@ const _AuthHandler = class _AuthHandler {
     if (!authCredential || !authCredential.oauth2) {
       return authCredential;
     }
+    const oauth2 = authCredential.oauth2;
+    const codeChallengeMethod = oauth2.codeChallengeMethod;
+    if (codeChallengeMethod && codeChallengeMethod !== S256_CODE_CHALLENGE_METHOD) {
+      throw new Error(
+        `Unsupported codeChallengeMethod: ${codeChallengeMethod}. Only '${S256_CODE_CHALLENGE_METHOD}' is supported.`
+      );
+    }
     let authorizationEndpoint = "";
     let scopes = [];
     if ("authorizationEndpoint" in authScheme) {
@@ -107,22 +133,35 @@ const _AuthHandler = class _AuthHandler {
     }
     const state = randomUUID();
     const url = new URL(authorizationEndpoint);
-    url.searchParams.set("client_id", authCredential.oauth2.clientId || "");
-    url.searchParams.set(
-      "redirect_uri",
-      authCredential.oauth2.redirectUri || ""
-    );
+    url.searchParams.set("client_id", oauth2.clientId || "");
+    url.searchParams.set("redirect_uri", oauth2.redirectUri || "");
     url.searchParams.set("response_type", "code");
     url.searchParams.set("scope", scopes.join(" "));
     url.searchParams.set("state", state);
     url.searchParams.set("access_type", "offline");
     url.searchParams.set("prompt", "consent");
+    if (oauth2.audience) {
+      url.searchParams.set("audience", oauth2.audience);
+    }
+    if (oauth2.nonce) {
+      url.searchParams.set("nonce", oauth2.nonce);
+    }
+    let codeVerifier = oauth2.codeVerifier;
+    if (codeChallengeMethod) {
+      codeVerifier != null ? codeVerifier : codeVerifier = generateCodeVerifier();
+      url.searchParams.set(
+        "code_challenge",
+        createS256CodeChallenge(codeVerifier)
+      );
+      url.searchParams.set("code_challenge_method", codeChallengeMethod);
+    }
     const exchangedAuthCredential = {
       ...authCredential,
       oauth2: {
-        ...authCredential.oauth2,
+        ...oauth2,
         authUri: url.toString(),
-        state
+        state,
+        codeVerifier
       }
     };
     return exchangedAuthCredential;

package/dist/esm/auth/oauth2/oauth2_credential_refresher.js

@@ -19,7 +19,7 @@ const _OAuth2CredentialRefresher = class _OAuth2CredentialRefresher {
    *
    * @param authCredential The OAuth2 credential to check.
    * @param authScheme The OAuth2 authentication scheme (optional).
-   * @returns True if the credential needs to be refreshed, False otherwise.
+   * @returns True if the credential needs to be refreshed, false otherwise.
    */
   async isRefreshNeeded(authCredential) {
     if (!authCredential.oauth2) {

package/dist/esm/auth/oauth2/oauth2_utils.js

@@ -7,8 +7,19 @@ var __name = (target, value) => __defProp(target, "name", { value, configurable:
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import { createHash, randomBytes } from "node:crypto";
 import { logger } from "../../utils/logger.js";
+import { redactUriPassword } from "../../utils/redact_uri.js";
 import { validateDiscoveryUrl } from "./oauth2_discovery.js";
+const CODE_VERIFIER_BYTES = 36;
+function generateCodeVerifier() {
+  return randomBytes(CODE_VERIFIER_BYTES).toString("base64url");
+}
+__name(generateCodeVerifier, "generateCodeVerifier");
+function createS256CodeChallenge(codeVerifier) {
+  return createHash("sha256").update(codeVerifier).digest("base64url");
+}
+__name(createS256CodeChallenge, "createS256CodeChallenge");
 function getTokenEndpoint(authScheme) {
   if (authScheme.type === "openIdConnect" && authScheme.tokenEndpoint) {
     return authScheme.tokenEndpoint;
@@ -63,8 +74,8 @@ function parseAuthorizationCode(uri) {
   try {
     const url = new URL(uri);
     return url.searchParams.get("code") || void 0;
-  } catch (e) {
-    logger.warn(`Failed to parse authorization URI ${uri}: ${e}`);
+  } catch {
+    logger.warn(`Failed to parse authorization URI ${redactUriPassword(uri)}`);
     return void 0;
   }
 }
@@ -98,7 +109,9 @@ function isTokenExpired(token, leeway = 60) {
 __name(isTokenExpired, "isTokenExpired");
 export {
   createOAuth2TokenRequestBody,
+  createS256CodeChallenge,
   fetchOAuth2Tokens,
+  generateCodeVerifier,
   getTokenEndpoint,
   isTokenExpired,
   parseAuthorizationCode

package/dist/esm/code_executors/base_code_executor.js

@@ -8,7 +8,7 @@ var __name = (target, value) => __defProp(target, "name", { value, configurable:
  * 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) {

package/dist/esm/code_executors/built_in_code_executor.js

@@ -10,7 +10,7 @@ var __name = (target, value) => __defProp(target, "name", { value, configurable:
 var _a, _b;
 import { isGemini2OrAbove } from "../utils/model_name.js";
 import { BaseCodeExecutor } from "./base_code_executor.js";
-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) {

package/dist/esm/code_executors/code_execution_utils.js

@@ -38,7 +38,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);
@@ -113,7 +113,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] = {

package/dist/esm/code_executors/container_code_executor.js

@@ -0,0 +1,155 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+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;
+};
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as path from "node:path";
+import { experimental } from "../utils/experimental.js";
+import { logger } from "../utils/logger.js";
+import { BaseCodeExecutor } from "./base_code_executor.js";
+import {
+  CodeExecutionLanguage
+} from "./code_execution_utils.js";
+import {
+  DockerContainer,
+  TIMEOUT_EXIT_CODE
+} from "./docker_container.js";
+const DEFAULT_IMAGE_TAG = "adk-code-executor:latest";
+const DEFAULT_TIMEOUT_SECONDS = 300;
+const TIMEOUT_COMMAND = ["timeout", "-s", "KILL"];
+const LANGUAGE_RUNTIME_COMMAND_MAP = {
+  [CodeExecutionLanguage.PYTHON]: ["python3", "-c"],
+  [CodeExecutionLanguage.JAVASCRIPT]: ["node", "-e"],
+  [CodeExecutionLanguage.TYPESCRIPT]: ["tsx", "--eval"],
+  [CodeExecutionLanguage.SHELL]: ["sh", "-c"]
+};
+let ContainerCodeExecutor = class extends 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
+    );
+    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 === 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 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([
+  experimental
+], ContainerCodeExecutor);
+function defineFrozenFalse(target, key) {
+  Object.defineProperty(target, key, {
+    value: false,
+    writable: false,
+    enumerable: true,
+    configurable: false
+  });
+}
+__name(defineFrozenFalse, "defineFrozenFalse");
+export {
+  ContainerCodeExecutor
+};

package/dist/esm/code_executors/docker_container.js

@@ -0,0 +1,265 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+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 __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
+));
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as fs from "node:fs/promises";
+import { PassThrough } from "node:stream";
+import { text } from "node:stream/consumers";
+import { setTimeout as delay } from "node:timers/promises";
+import { logger } from "../utils/logger.js";
+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) {
+    logger.debug(`Container ${container.id} was not running: ${error}`);
+  }
+  try {
+    await container.remove({ force: true });
+    return true;
+  } catch (error) {
+    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 delay(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();
+    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()
+      );
+    });
+    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();
+    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();
+    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 PassThrough();
+    const stderr = new PassThrough();
+    client.modem.demuxStream(stream, stdout, stderr);
+    const collected = Promise.all([text(stdout), 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;
+export {
+  DockerContainer,
+  TIMEOUT_EXIT_CODE
+};