@google/adk 2.3.0 → 2.5.0

package/dist/esm/code_executors/container_code_executor.js

@@ -40,6 +40,16 @@ let ContainerCodeExecutor = class extends BaseCodeExecutor {
   constructor(options = {}) {
     var _a, _b, _c;
     super();
+    /** Started session containers, ordered from least to most recently used. */
+    this.containers = /* @__PURE__ */ new Map();
+    /** Container starts that are still in flight, keyed by session. */
+    this.initPromises = /* @__PURE__ */ new Map();
+    /**
+     * Number of `executeCode` calls in progress per session. A session with a
+     * call in progress is never evicted, so a run is not stopped midway.
+     */
+    this.activeExecutions = /* @__PURE__ */ new Map();
+    this.closing = false;
     if (!options.image && !options.dockerPath) {
       throw new Error(
         "Either image or dockerPath must be set for ContainerCodeExecutor."
@@ -51,6 +61,12 @@ let ContainerCodeExecutor = class extends BaseCodeExecutor {
         "timeoutSeconds must be greater than 0 for ContainerCodeExecutor."
       );
     }
+    this.maxContainers = options.maxContainers;
+    if (this.maxContainers !== void 0 && (!Number.isInteger(this.maxContainers) || this.maxContainers < 1)) {
+      throw new Error(
+        "maxContainers must be a positive integer for ContainerCodeExecutor."
+      );
+    }
     this.dockerPath = options.dockerPath ? path.resolve(options.dockerPath) : void 0;
     this.containerOptions = {
       image: (_b = options.image) != null ? _b : DEFAULT_IMAGE_TAG,
@@ -62,6 +78,7 @@ let ContainerCodeExecutor = class extends BaseCodeExecutor {
     defineFrozenFalse(this, "optimizeDataFile");
   }
   async executeCode(params) {
+    var _a, _b;
     const { code, language } = params.codeExecutionInput;
     const command = LANGUAGE_RUNTIME_COMMAND_MAP[language];
     if (!command) {
@@ -69,20 +86,32 @@ let ContainerCodeExecutor = class extends BaseCodeExecutor {
         `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:
+    const key = sessionKey(params.invocationContext);
+    this.activeExecutions.set(key, ((_a = this.activeExecutions.get(key)) != null ? _a : 0) + 1);
+    try {
+      const container = await this.ensureContainer(key);
+      const { stdout, stderr, exitCode } = await 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: []
-    };
+      return {
+        stdout,
+        stderr: this.describeExit(stderr, exitCode),
+        outputFiles: []
+      };
+    } finally {
+      const remaining = ((_b = this.activeExecutions.get(key)) != null ? _b : 1) - 1;
+      if (remaining > 0) {
+        this.activeExecutions.set(key, remaining);
+      } else {
+        this.activeExecutions.delete(key);
+      }
+      this.evictLeastRecentlyUsed();
+    }
   }
   /**
    * Turns a non-zero exit into stderr the model can see. An empty stderr maps
@@ -102,38 +131,134 @@ ${message}` : message;
     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.
+   * Stops and removes every session's container. Waits for container starts
+   * that are still in flight, so no container is left running after it
+   * resolves. Safe to call when none has been started, and concurrent calls
+   * share one teardown. 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());
+  close() {
+    var _a;
+    (_a = this.closePromise) != null ? _a : this.closePromise = this.stopAll().finally(() => {
+      this.closePromise = void 0;
+    });
+    return this.closePromise;
   }
-  /** Lazily builds/starts the container exactly once. */
-  ensureContainer() {
-    if (!this.initPromise) {
-      this.initPromise = this.initContainer().catch((error) => {
-        this.initPromise = void 0;
-        throw error;
-      });
+  async stopAll() {
+    this.closing = true;
+    try {
+      while (this.initPromises.size > 0) {
+        await Promise.allSettled([...this.initPromises.values()]);
+      }
+      const containers = [...this.containers.values()];
+      this.containers.clear();
+      this.initPromises.clear();
+      await Promise.allSettled(containers.map((container) => container.stop()));
+    } finally {
+      this.closing = false;
     }
-    return this.initPromise;
   }
-  async initContainer() {
+  /**
+   * Returns the given session's container, starting it if needed. Concurrent
+   * calls for one session share a single in-flight start, and reuse marks the
+   * container as the most recently used.
+   */
+  ensureContainer(key) {
+    const existing = this.containers.get(key);
+    if (existing) {
+      this.containers.delete(key);
+      this.containers.set(key, existing);
+      return Promise.resolve(existing);
+    }
+    const inFlight = this.initPromises.get(key);
+    if (inFlight) {
+      return inFlight;
+    }
+    const initPromise = this.initContainer(
+      key
+    ).finally(() => {
+      if (this.initPromises.get(key) === initPromise) {
+        this.initPromises.delete(key);
+      }
+    });
+    this.initPromises.set(key, initPromise);
+    return initPromise;
+  }
+  /**
+   * Builds the image from `dockerPath` once and shares the build across every
+   * session. A failed build is cleared so the next call retries it.
+   */
+  ensureImageBuilt() {
+    var _a;
+    const dockerPath = this.dockerPath;
+    if (!dockerPath) {
+      return Promise.resolve();
+    }
+    (_a = this.buildPromise) != null ? _a : this.buildPromise = new DockerContainer(this.containerOptions).build(dockerPath).catch((error) => {
+      this.buildPromise = void 0;
+      throw error;
+    });
+    return this.buildPromise;
+  }
+  async initContainer(key) {
+    await this.ensureImageBuilt();
+    if (this.closing) {
+      throw new Error(
+        "ContainerCodeExecutor closed during container initialization."
+      );
+    }
     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.");
+    try {
+      await container.start();
+      const { exitCode } = await container.execute(
+        ["which", "python3"],
+        this.timeoutSeconds
+      );
+      if (exitCode !== 0) {
+        throw new Error("python3 is not installed in the container.");
+      }
+    } catch (error) {
+      await container.stop().catch((stopError) => {
+        logger.debug(
+          `Failed to stop container after failed start: ${stopError}`
+        );
+      });
+      throw error;
+    }
+    if (this.closing) {
+      await container.stop().catch((stopError) => {
+        logger.debug(`Failed to stop container during close: ${stopError}`);
+      });
+      throw new Error(
+        "ContainerCodeExecutor closed during container initialization."
+      );
+    }
+    this.containers.set(key, container);
+    this.evictLeastRecentlyUsed();
+    return container;
+  }
+  /**
+   * Stops the least recently used idle session containers until the count is
+   * within `maxContainers`. A session with a call in progress is skipped, which
+   * includes the caller that just registered its container; if every session
+   * is busy, the overshoot stays until a call ends. The stop is not awaited so
+   * the caller is not delayed by another session's teardown.
+   */
+  evictLeastRecentlyUsed() {
+    if (this.maxContainers === void 0) {
+      return;
+    }
+    for (const [key, container] of this.containers) {
+      if (this.containers.size <= this.maxContainers) {
+        return;
+      }
+      if (this.activeExecutions.has(key)) {
+        continue;
+      }
+      this.containers.delete(key);
+      void container.stop().catch((error) => {
+        logger.debug(`Failed to stop evicted container: ${error}`);
+      });
     }
   }
 };
@@ -141,6 +266,14 @@ __name(ContainerCodeExecutor, "ContainerCodeExecutor");
 ContainerCodeExecutor = __decorateClass([
   experimental
 ], ContainerCodeExecutor);
+function sessionKey(invocationContext) {
+  const session = invocationContext == null ? void 0 : invocationContext.session;
+  if (!session) {
+    return "default";
+  }
+  return JSON.stringify([session.appName, session.userId, session.id]);
+}
+__name(sessionKey, "sessionKey");
 function defineFrozenFalse(target, key) {
   Object.defineProperty(target, key, {
     value: false,

package/dist/esm/code_executors/unsafe_local_code_executor.js

@@ -216,7 +216,12 @@ Code execution timed out after ${this.timeoutSeconds} seconds.`;
       };
     } finally {
       if (tempDir) {
-        await fs.rm(tempDir, { recursive: true, force: true });
+        await fs.rm(tempDir, {
+          recursive: true,
+          force: true,
+          maxRetries: 10,
+          retryDelay: 500
+        });
       }
     }
   }

package/dist/esm/common.js

@@ -18,6 +18,7 @@ import {
   handleFunctionCallsLive,
   isToolNotFound
 } from "./agents/functions.js";
+import { injectSessionState } from "./agents/instructions.js";
 import {
   InvocationContext,
   LlmCallsLimitExceededError,
@@ -49,7 +50,6 @@ import {
   InteractionsRequestProcessor
 } from "./agents/processors/interactions_request_processor.js";
 import { ReadonlyContext } from "./agents/readonly_context.js";
-import { RemoteAgent, isRemoteAgent } from "./agents/remote_agent.js";
 import { RoutedAgent, isRoutedAgent } from "./agents/routed_agent.js";
 import { StreamingMode, createRunConfig } from "./agents/run_config.js";
 import { SequentialAgent, isSequentialAgent } from "./agents/sequential_agent.js";
@@ -182,11 +182,29 @@ import {
 import { BaseSessionService } from "./sessions/base_session_service.js";
 import { InMemorySessionService } from "./sessions/in_memory_session_service.js";
 import { createSession } from "./sessions/session.js";
+import {
+  StaleSessionError,
+  isStaleSessionError
+} from "./sessions/stale_session_error.js";
 import { State, StateSchemaError, isStateSchemaError } from "./sessions/state.js";
 import { AgentTool, isAgentTool } from "./tools/agent_tool.js";
 import { BaseTool, isBaseTool } from "./tools/base_tool.js";
 import { BaseToolset, isBaseToolset } from "./tools/base_toolset.js";
 import { BuiltInTool } from "./tools/built_in_tool.js";
+import {
+  BaseComputer,
+  ComputerEnvironment,
+  isBaseComputer
+} from "./tools/computer_use/base_computer.js";
+import {
+  ComputerUseTool,
+  isComputerUseTool
+} from "./tools/computer_use/computer_use_tool.js";
+import {
+  ComputerUseToolset,
+  adaptComputerUseTool,
+  isComputerUseToolset
+} from "./tools/computer_use/computer_use_toolset.js";
 import { ConsolidateContextTool } from "./tools/consolidate_context_tool.js";
 import {
   ENTERPRISE_WEB_SEARCH,
@@ -240,6 +258,7 @@ import { renameReservedKeywords, toSnakeCaseName } from "./utils/case_utils.js";
 import { getClientLabels, runWithClientLabel } from "./utils/client_labels.js";
 import { toGeminiSchema } from "./utils/gemini_schema_util.js";
 import { genaiSchemaToJsonSchema } from "./utils/genai_schema_to_json.js";
+import { newId, resetIdProvider, setIdProvider } from "./utils/id_provider.js";
 import {
   LogLevel,
   getLogger,
@@ -255,7 +274,11 @@ import {
   isGemini3xLive
 } from "./utils/model_name.js";
 import { toJsonSchema } from "./utils/schema.js";
-import { zodObjectToSchema } from "./utils/simple_zod_to_json.js";
+import {
+  isZodObject,
+  isZodSchema,
+  zodObjectToSchema
+} from "./utils/simple_zod_to_json.js";
 import { Task } from "./utils/task.js";
 import { GoogleLLMVariant } from "./utils/variant_utils.js";
 import { version } from "./version.js";
@@ -265,7 +288,11 @@ import { SearchSkillsTool } from "./tools/skill/search_skills_tool.js";
 export * from "./artifacts/base_artifact_service.js";
 export * from "./features/feature_registry.js";
 export * from "./memory/base_memory_service.js";
-export * from "./sessions/base_session_service.js";
+import {
+  mergeStates,
+  trimTempDeltaState,
+  trimTempState
+} from "./sessions/base_session_service.js";
 export * from "./tools/base_tool.js";
 import {
   BaseNode,
@@ -297,6 +324,7 @@ import {
   isNodeSchemaValidationError,
   isNodeState,
   isNodeTimeoutError,
+  isParallelWorker,
   isRequestInput,
   isRunnableRoot,
   isWorkflow,
@@ -305,24 +333,19 @@ import {
   prepareRetryConfig
 } from "./workflow/index.js";
 import { App, isApp, validateAppName } from "./apps/app.js";
-export * from "./artifacts/base_artifact_service.js";
-export * from "./features/feature_registry.js";
-export * from "./memory/base_memory_service.js";
-export * from "./sessions/base_session_service.js";
-export * from "./tools/base_tool.js";
+import { RUNNER_CLEANUP_TIMEOUT_MS, closeRunners } from "./cli/utils/cleanup.js";
 import {
   convertSessionToEvalFormat,
+  convertSessionToEvalInvocations,
   createEmptyState
 } from "./cli/utils/evals.js";
-import { CrewaiTool, isCrewaiTool } from "./tools/crewai_tool.js";
 import {
   buildFunctionDeclarationForLangchain,
   buildFunctionDeclarationForParamsForCrewai,
   buildFunctionDeclarationUtil
 } from "./tools/function_tool.js";
-import { LangchainTool, isLangchainTool } from "./tools/langchain_tool.js";
 import { isBaseRetrievalTool } from "./tools/retrieval/base_retrieval_tool.js";
-import { ToolboxTool, isToolboxTool } from "./tools/toolbox_tool.js";
+import { ToolboxToolset, isToolboxToolset } from "./tools/toolbox_toolset.js";
 export {
   ADK_HANDLE_MODEL_ERROR_TOOL_NAME,
   AUTH_PREPROCESSOR,
@@ -343,6 +366,7 @@ export {
   AuthSchemeType,
   BaseAgent,
   BaseCodeExecutor,
+  BaseComputer,
   BaseEnvironment,
   BaseExampleProvider,
   BaseLlm,
@@ -365,6 +389,9 @@ export {
   ChromeModelUnavailableError,
   CodeExecutionLanguage,
   CodeExecutionResponseProcessor,
+  ComputerEnvironment,
+  ComputerUseTool,
+  ComputerUseToolset,
   ConsolidateContextTool,
   ContentRequestProcessor,
   Context,
@@ -372,7 +399,6 @@ export {
   ContextCompactorRequestProcessor,
   CredentialExchangeError,
   CredentialRefresherRegistry,
-  CrewaiTool,
   DEFAULT_ROUTE,
   ENTERPRISE_WEB_SEARCH,
   EXIT_LOOP,
@@ -414,7 +440,6 @@ export {
   LOAD_ARTIFACTS,
   LOAD_MEMORY,
   LangGraphAgent,
-  LangchainTool,
   ListSkillsTool,
   LiveRequestQueue,
   LlamaIndexRetrieval,
@@ -451,10 +476,10 @@ export {
   REQUEST_INPUT_FUNCTION_CALL_NAME,
   RESERVED_TOOL_CALL_ERROR_TYPE,
   RESTORED_EVENT_KEY,
+  RUNNER_CLEANUP_TIMEOUT_MS,
   ReadonlyContext,
   ReflectAndRetryModelPlugin,
   ReflectAndRetryToolPlugin,
-  RemoteAgent,
   RequestInput,
   RoutedAgent,
   RoutedLlm,
@@ -467,6 +492,7 @@ export {
   SequentialAgent,
   SessionNotFoundError,
   SessionStateCredentialService,
+  StaleSessionError,
   State,
   StateSchemaError,
   StreamingMode,
@@ -479,7 +505,7 @@ export {
   ToolErrorType,
   ToolExecutionError,
   ToolNode,
-  ToolboxTool,
+  ToolboxToolset,
   TrackingScope,
   TrajectoryThoughtPruningCompactor,
   TruncatingContextCompactor,
@@ -492,13 +518,16 @@ export {
   WebMCPToolset,
   Workflow,
   WorkflowNode,
+  adaptComputerUseTool,
   appendInstructions,
   asRunnableRoot,
   buildFunctionDeclarationForLangchain,
   buildFunctionDeclarationForParamsForCrewai,
   buildFunctionDeclarationUtil,
+  closeRunners,
   commonPrefixOf,
   convertSessionToEvalFormat,
+  convertSessionToEvalInvocations,
   createEmptyState,
   createEvent,
   createEventActions,
@@ -531,10 +560,12 @@ export {
   handleFunctionCallsLive,
   hasThoughts,
   hasTrailingCodeExecutionResult,
+  injectSessionState,
   isAgentTool,
   isApp,
   isAuthCredential,
   isBaseAgent,
+  isBaseComputer,
   isBaseExampleProvider,
   isBaseLlm,
   isBasePlanner,
@@ -543,7 +574,8 @@ export {
   isBaseToolset,
   isBuiltInPlanner,
   isCompactedEvent,
-  isCrewaiTool,
+  isComputerUseTool,
+  isComputerUseToolset,
   isFinalResponse,
   isFunctionTool,
   isGemini2OrAbove,
@@ -552,7 +584,6 @@ export {
   isGemini3xLive,
   isIntentMismatchError,
   isLangGraphAgent,
-  isLangchainTool,
   isLlmAgent,
   isLlmCallsLimitExceededError,
   isLoopAgent,
@@ -562,7 +593,7 @@ export {
   isNodeState,
   isNodeTimeoutError,
   isParallelAgent,
-  isRemoteAgent,
+  isParallelWorker,
   isRequestInput,
   isRoutableLlmAgent,
   isRoutedAgent,
@@ -571,13 +602,18 @@ export {
   isScratchpadEvent,
   isSequentialAgent,
   isSessionArtifactService,
+  isStaleSessionError,
   isStateSchemaError,
   isToolNotFound,
-  isToolboxTool,
+  isToolboxToolset,
   isWebMCPSupported,
   isWorkflow,
+  isZodObject,
+  isZodSchema,
   logger,
   markRestored,
+  mergeStates,
+  newId,
   node,
   normalizeRetryExceptions,
   populateClientFunctionCallId,
@@ -590,9 +626,11 @@ export {
   requestInputTool,
   requireAgent,
   requiresUserInput,
+  resetIdProvider,
   resetLogger,
   resolveScopeKey,
   runWithClientLabel,
+  setIdProvider,
   setLogLevel,
   setLogger,
   stringifyContent,
@@ -601,6 +639,8 @@ export {
   toJsonSchema,
   toSnakeCaseName,
   toStructuredEvents,
+  trimTempDeltaState,
+  trimTempState,
   validateAppName,
   version,
   zodObjectToSchema

package/dist/esm/context/compaction_utils.js

@@ -40,6 +40,25 @@ function calculateRetainStartIndex(rawEvents, eventRetentionSize) {
       break;
     }
   }
+  const latestCalls = /* @__PURE__ */ new Map();
+  const callDependencies = rawEvents.map((event, index) => {
+    let earliestCall = index;
+    for (const response of getFunctionResponses(event)) {
+      if (response.id === void 0) continue;
+      const callIndex = latestCalls.get(response.id);
+      if (callIndex !== void 0) {
+        earliestCall = Math.min(earliestCall, callIndex);
+      }
+    }
+    for (const call of getFunctionCalls(event)) {
+      if (call.id === void 0) continue;
+      latestCalls.set(call.id, index);
+    }
+    return earliestCall;
+  });
+  for (let index = rawEvents.length - 1; index >= retainStartIndex; index--) {
+    retainStartIndex = Math.min(retainStartIndex, callDependencies[index]);
+  }
   return retainStartIndex;
 }
 __name(calculateRetainStartIndex, "calculateRetainStartIndex");

package/dist/esm/errors/input_validation_error.js

@@ -10,9 +10,10 @@ var __name = (target, value) => __defProp(target, "name", { value, configurable:
 const _InputValidationError = class _InputValidationError extends Error {
   /**
    * @param message A message describing why the input is invalid.
+   * @param options Standard error options, e.g. `{cause}`.
    */
-  constructor(message = "Invalid input.") {
-    super(message);
+  constructor(message = "Invalid input.", options) {
+    super(message, options);
     this.name = "InputValidationError";
   }
 };

package/dist/esm/events/event.js

@@ -7,7 +7,7 @@ var __name = (target, value) => __defProp(target, "name", { value, configurable:
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { randomUUID } from "../utils/env_aware_utils.js";
+import { newId, newIdOr } from "../utils/id_provider.js";
 import { toCamelCase, toSnakeCase } from "../utils/object_notation_utils.js";
 import { createEventActions } from "./event_actions.js";
 const EVENT_SIGNATURE_SYMBOL = /* @__PURE__ */ Symbol.for("google.adk.event");
@@ -46,7 +46,7 @@ function getFunctionCalls(event) {
 __name(getFunctionCalls, "getFunctionCalls");
 const AF_FUNCTION_CALL_ID_PREFIX = "adk-";
 function generateClientFunctionCallId() {
-  return `${AF_FUNCTION_CALL_ID_PREFIX}${randomUUID()}`;
+  return `${AF_FUNCTION_CALL_ID_PREFIX}${newId()}`;
 }
 __name(generateClientFunctionCallId, "generateClientFunctionCallId");
 function populateClientFunctionCallId(modelResponseEvent) {
@@ -128,13 +128,17 @@ function isEvent(obj) {
 }
 __name(isEvent, "isEvent");
 function createNewEventId() {
+  return newIdOr(createRandomEventId);
+}
+__name(createNewEventId, "createNewEventId");
+function createRandomEventId() {
   let id = "";
   for (let i = 0; i < 8; i++) {
     id += ASCII_LETTERS_AND_NUMBERS[Math.floor(Math.random() * ASCII_LETTERS_AND_NUMBERS.length)];
   }
   return id;
 }
-__name(createNewEventId, "createNewEventId");
+__name(createRandomEventId, "createRandomEventId");
 const PRESERVE_KEYS_CAMEL_CASE = [
   "actions.stateDelta",
   "actions.artifactDelta",

package/dist/esm/features/feature_registry.js

@@ -10,6 +10,7 @@ var __name = (target, value) => __defProp(target, "name", { value, configurable:
 import { getBooleanEnvVar } from "../utils/env_aware_utils.js";
 import { logger } from "../utils/logger.js";
 var FeatureName = /* @__PURE__ */ ((FeatureName2) => {
+  FeatureName2["COMPUTER_USE"] = "COMPUTER_USE";
   FeatureName2["PROGRESSIVE_SSE_STREAMING"] = "PROGRESSIVE_SSE_STREAMING";
   return FeatureName2;
 })(FeatureName || {});
@@ -20,6 +21,10 @@ var FeatureStage = /* @__PURE__ */ ((FeatureStage2) => {
   return FeatureStage2;
 })(FeatureStage || {});
 const FEATURE_REGISTRY = {
+  ["COMPUTER_USE" /* COMPUTER_USE */]: {
+    stage: "experimental" /* EXPERIMENTAL */,
+    defaultOn: true
+  },
   ["PROGRESSIVE_SSE_STREAMING" /* PROGRESSIVE_SSE_STREAMING */]: {
     stage: "experimental" /* EXPERIMENTAL */,
     defaultOn: false