@google/adk 2.0.0 → 2.2.0

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
+};

package/dist/esm/code_executors/unsafe_local_code_executor.js

@@ -139,13 +139,17 @@ const _UnsafeLocalCodeExecutor = class _UnsafeLocalCodeExecutor extends BaseCode
         }
       }
       const executionResult = await new Promise((resolve) => {
-        const child = spawn(command, args, {
-          timeout: this.timeoutSeconds * 1e3,
-          killSignal: "SIGKILL",
-          cwd: tempDir
-        });
+        const child = spawn(command, args, { cwd: tempDir });
         let stdout = "";
         let stderr = "";
+        let timedOut = false;
+        const timer = setTimeout(() => {
+          var _a2, _b;
+          timedOut = true;
+          child.kill("SIGKILL");
+          (_a2 = child.stdout) == null ? void 0 : _a2.destroy();
+          (_b = child.stderr) == null ? void 0 : _b.destroy();
+        }, this.timeoutSeconds * 1e3);
         if (child.stdout) {
           child.stdout.on("data", (data) => {
             stdout += data.toString();
@@ -161,7 +165,8 @@ const _UnsafeLocalCodeExecutor = class _UnsafeLocalCodeExecutor extends BaseCode
 `;
         });
         child.on("close", (exitCode, signal) => {
-          if (signal === "SIGKILL" || signal === "SIGTERM") {
+          clearTimeout(timer);
+          if (timedOut || signal === "SIGKILL" || signal === "SIGTERM") {
             stderr += `
 Code execution timed out after ${this.timeoutSeconds} seconds.`;
           } else if (exitCode !== 0 && exitCode !== null) {