@google/adk 2.3.0 → 2.4.0

package/dist/cjs/code_executors/container_code_executor.js

@@ -70,6 +70,8 @@ let ContainerCodeExecutor = class extends import_base_code_executor.BaseCodeExec
   constructor(options = {}) {
     var _a, _b, _c;
     super();
+    this.containers = /* @__PURE__ */ new Map();
+    this.initPromises = /* @__PURE__ */ new Map();
     if (!options.image && !options.dockerPath) {
       throw new Error(
         "Either image or dockerPath must be set for ContainerCodeExecutor."
@@ -99,8 +101,9 @@ let ContainerCodeExecutor = class extends import_base_code_executor.BaseCodeExec
         `Unsupported language for ContainerCodeExecutor: ${language}. Supported: ${Object.keys(LANGUAGE_RUNTIME_COMMAND_MAP).join(", ")}.`
       );
     }
-    await this.ensureContainer();
-    const { stdout, stderr, exitCode } = await this.container.execute(
+    const key = sessionKey(params.invocationContext);
+    const container = await this.ensureContainer(key);
+    const { stdout, stderr, exitCode } = await container.execute(
       [...TIMEOUT_COMMAND, String(this.timeoutSeconds), ...command, code],
       this.timeoutSeconds
     );
@@ -132,32 +135,35 @@ ${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. Safe to call when none 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());
+    const containers = [...this.containers.values()];
+    this.containers.clear();
+    this.initPromises.clear();
+    await Promise.all(containers.map((container) => container.stop()));
   }
-  /** Lazily builds/starts the container exactly once. */
-  ensureContainer() {
-    if (!this.initPromise) {
-      this.initPromise = this.initContainer().catch((error) => {
-        this.initPromise = void 0;
+  /** Lazily builds/starts the given session's container exactly once. */
+  ensureContainer(key) {
+    let initPromise = this.initPromises.get(key);
+    if (!initPromise) {
+      initPromise = this.initContainer(key).catch((error) => {
+        this.initPromises.delete(key);
         throw error;
       });
+      this.initPromises.set(key, initPromise);
     }
-    return this.initPromise;
+    return initPromise.then(() => this.containers.get(key));
   }
-  async initContainer() {
+  async initContainer(key) {
     const container = new import_docker_container.DockerContainer(this.containerOptions);
     if (this.dockerPath) {
       await container.build(this.dockerPath);
     }
     await container.start();
-    this.container = container;
+    this.containers.set(key, container);
     const { exitCode } = await container.execute(
       ["which", "python3"],
       this.timeoutSeconds
@@ -171,6 +177,11 @@ __name(ContainerCodeExecutor, "ContainerCodeExecutor");
 ContainerCodeExecutor = __decorateClass([
   import_experimental.experimental
 ], ContainerCodeExecutor);
+function sessionKey(invocationContext) {
+  const session = invocationContext.session;
+  return JSON.stringify([session.appName, session.userId, session.id]);
+}
+__name(sessionKey, "sessionKey");
 function defineFrozenFalse(target, key) {
   Object.defineProperty(target, key, {
     value: false,

package/dist/cjs/code_executors/unsafe_local_code_executor.js

@@ -250,7 +250,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/cjs/common.js

@@ -73,7 +73,6 @@ __export(common_exports, {
   ContextCompactorRequestProcessor: () => import_context_compactor_request_processor.ContextCompactorRequestProcessor,
   CredentialExchangeError: () => import_base_credential_exchanger.CredentialExchangeError,
   CredentialRefresherRegistry: () => import_credential_refresher_registry.CredentialRefresherRegistry,
-  CrewaiTool: () => import_crewai_tool.CrewaiTool,
   DEFAULT_ROUTE: () => import_workflow.DEFAULT_ROUTE,
   ENTERPRISE_WEB_SEARCH: () => import_enterprise_web_search_tool.ENTERPRISE_WEB_SEARCH,
   EXIT_LOOP: () => import_exit_loop_tool.EXIT_LOOP,
@@ -115,7 +114,6 @@ __export(common_exports, {
   LOAD_ARTIFACTS: () => import_load_artifacts_tool.LOAD_ARTIFACTS,
   LOAD_MEMORY: () => import_load_memory_tool.LOAD_MEMORY,
   LangGraphAgent: () => import_langgraph_agent.LangGraphAgent,
-  LangchainTool: () => import_langchain_tool.LangchainTool,
   ListSkillsTool: () => import_list_skills_tool.ListSkillsTool,
   LiveRequestQueue: () => import_live_request_queue.LiveRequestQueue,
   LlamaIndexRetrieval: () => import_llama_index_retrieval.LlamaIndexRetrieval,
@@ -155,7 +153,6 @@ __export(common_exports, {
   ReadonlyContext: () => import_readonly_context.ReadonlyContext,
   ReflectAndRetryModelPlugin: () => import_reflect_retry_model_plugin.ReflectAndRetryModelPlugin,
   ReflectAndRetryToolPlugin: () => import_reflect_retry_tool_plugin.ReflectAndRetryToolPlugin,
-  RemoteAgent: () => import_remote_agent.RemoteAgent,
   RequestInput: () => import_workflow.RequestInput,
   RoutedAgent: () => import_routed_agent.RoutedAgent,
   RoutedLlm: () => import_routed_llm.RoutedLlm,
@@ -180,7 +177,7 @@ __export(common_exports, {
   ToolErrorType: () => import_tool_execution_error.ToolErrorType,
   ToolExecutionError: () => import_tool_execution_error.ToolExecutionError,
   ToolNode: () => import_workflow.ToolNode,
-  ToolboxTool: () => import_toolbox_tool.ToolboxTool,
+  ToolboxToolset: () => import_toolbox_toolset.ToolboxToolset,
   TrackingScope: () => import_reflect_retry_utils.TrackingScope,
   TrajectoryThoughtPruningCompactor: () => import_trajectory_thought_pruning_compactor.TrajectoryThoughtPruningCompactor,
   TruncatingContextCompactor: () => import_truncating_context_compactor.TruncatingContextCompactor,
@@ -244,7 +241,6 @@ __export(common_exports, {
   isBaseToolset: () => import_base_toolset.isBaseToolset,
   isBuiltInPlanner: () => import_built_in_planner.isBuiltInPlanner,
   isCompactedEvent: () => import_compacted_event.isCompactedEvent,
-  isCrewaiTool: () => import_crewai_tool.isCrewaiTool,
   isFinalResponse: () => import_event.isFinalResponse,
   isFunctionTool: () => import_function_tool.isFunctionTool,
   isGemini2OrAbove: () => import_model_name.isGemini2OrAbove,
@@ -253,7 +249,6 @@ __export(common_exports, {
   isGemini3xLive: () => import_model_name.isGemini3xLive,
   isIntentMismatchError: () => import_tool_confirmation.isIntentMismatchError,
   isLangGraphAgent: () => import_langgraph_agent.isLangGraphAgent,
-  isLangchainTool: () => import_langchain_tool.isLangchainTool,
   isLlmAgent: () => import_llm_agent.isLlmAgent,
   isLlmCallsLimitExceededError: () => import_invocation_context.isLlmCallsLimitExceededError,
   isLoopAgent: () => import_loop_agent.isLoopAgent,
@@ -263,7 +258,6 @@ __export(common_exports, {
   isNodeState: () => import_workflow.isNodeState,
   isNodeTimeoutError: () => import_workflow.isNodeTimeoutError,
   isParallelAgent: () => import_parallel_agent.isParallelAgent,
-  isRemoteAgent: () => import_remote_agent.isRemoteAgent,
   isRequestInput: () => import_workflow.isRequestInput,
   isRoutableLlmAgent: () => import_runner.isRoutableLlmAgent,
   isRoutedAgent: () => import_routed_agent.isRoutedAgent,
@@ -274,9 +268,11 @@ __export(common_exports, {
   isSessionArtifactService: () => import_session_artifact_service.isSessionArtifactService,
   isStateSchemaError: () => import_state.isStateSchemaError,
   isToolNotFound: () => import_functions.isToolNotFound,
-  isToolboxTool: () => import_toolbox_tool.isToolboxTool,
+  isToolboxToolset: () => import_toolbox_toolset.isToolboxToolset,
   isWebMCPSupported: () => import_webmcp_types.isWebMCPSupported,
   isWorkflow: () => import_workflow.isWorkflow,
+  isZodObject: () => import_simple_zod_to_json.isZodObject,
+  isZodSchema: () => import_simple_zod_to_json.isZodSchema,
   logger: () => import_logger.logger,
   markRestored: () => import_internal_metadata.markRestored,
   node: () => import_workflow.node,
@@ -324,7 +320,6 @@ var import_content_request_processor = require("./agents/processors/content_requ
 var import_context_compactor_request_processor = require("./agents/processors/context_compactor_request_processor.js");
 var import_interactions_request_processor = require("./agents/processors/interactions_request_processor.js");
 var import_readonly_context = require("./agents/readonly_context.js");
-var import_remote_agent = require("./agents/remote_agent.js");
 var import_routed_agent = require("./agents/routed_agent.js");
 var import_run_config = require("./agents/run_config.js");
 var import_sequential_agent = require("./agents/sequential_agent.js");
@@ -450,11 +445,9 @@ __reExport(common_exports, require("./memory/base_memory_service.js"), module.ex
 __reExport(common_exports, require("./sessions/base_session_service.js"), module.exports);
 __reExport(common_exports, require("./tools/base_tool.js"), module.exports);
 var import_evals = require("./cli/utils/evals.js");
-var import_crewai_tool = require("./tools/crewai_tool.js");
 var import_function_tool2 = require("./tools/function_tool.js");
-var import_langchain_tool = require("./tools/langchain_tool.js");
 var import_base_retrieval_tool2 = require("./tools/retrieval/base_retrieval_tool.js");
-var import_toolbox_tool = require("./tools/toolbox_tool.js");
+var import_toolbox_toolset = require("./tools/toolbox_toolset.js");
 /**
  * @license
  * Copyright 2025 Google LLC
@@ -510,7 +503,6 @@ var import_toolbox_tool = require("./tools/toolbox_tool.js");
   ContextCompactorRequestProcessor,
   CredentialExchangeError,
   CredentialRefresherRegistry,
-  CrewaiTool,
   DEFAULT_ROUTE,
   ENTERPRISE_WEB_SEARCH,
   EXIT_LOOP,
@@ -552,7 +544,6 @@ var import_toolbox_tool = require("./tools/toolbox_tool.js");
   LOAD_ARTIFACTS,
   LOAD_MEMORY,
   LangGraphAgent,
-  LangchainTool,
   ListSkillsTool,
   LiveRequestQueue,
   LlamaIndexRetrieval,
@@ -592,7 +583,6 @@ var import_toolbox_tool = require("./tools/toolbox_tool.js");
   ReadonlyContext,
   ReflectAndRetryModelPlugin,
   ReflectAndRetryToolPlugin,
-  RemoteAgent,
   RequestInput,
   RoutedAgent,
   RoutedLlm,
@@ -617,7 +607,7 @@ var import_toolbox_tool = require("./tools/toolbox_tool.js");
   ToolErrorType,
   ToolExecutionError,
   ToolNode,
-  ToolboxTool,
+  ToolboxToolset,
   TrackingScope,
   TrajectoryThoughtPruningCompactor,
   TruncatingContextCompactor,
@@ -681,7 +671,6 @@ var import_toolbox_tool = require("./tools/toolbox_tool.js");
   isBaseToolset,
   isBuiltInPlanner,
   isCompactedEvent,
-  isCrewaiTool,
   isFinalResponse,
   isFunctionTool,
   isGemini2OrAbove,
@@ -690,7 +679,6 @@ var import_toolbox_tool = require("./tools/toolbox_tool.js");
   isGemini3xLive,
   isIntentMismatchError,
   isLangGraphAgent,
-  isLangchainTool,
   isLlmAgent,
   isLlmCallsLimitExceededError,
   isLoopAgent,
@@ -700,7 +688,6 @@ var import_toolbox_tool = require("./tools/toolbox_tool.js");
   isNodeState,
   isNodeTimeoutError,
   isParallelAgent,
-  isRemoteAgent,
   isRequestInput,
   isRoutableLlmAgent,
   isRoutedAgent,
@@ -711,9 +698,11 @@ var import_toolbox_tool = require("./tools/toolbox_tool.js");
   isSessionArtifactService,
   isStateSchemaError,
   isToolNotFound,
-  isToolboxTool,
+  isToolboxToolset,
   isWebMCPSupported,
   isWorkflow,
+  isZodObject,
+  isZodSchema,
   logger,
   markRestored,
   node,

package/dist/cjs/errors/input_validation_error.js

@@ -36,9 +36,10 @@ module.exports = __toCommonJS(input_validation_error_exports);
 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/cjs/index.js

@@ -47,6 +47,7 @@ __export(index_exports, {
   GcsArtifactService: () => import_gcs_artifact_service.GcsArtifactService,
   INTERNAL_AUTH_PREFIX: () => import_auth_helpers.INTERNAL_AUTH_PREFIX,
   IntegrationClient: () => import_integration_client.IntegrationClient,
+  IntegrationConnectorTool: () => import_integration_connector_tool.IntegrationConnectorTool,
   InvocationContext: () => import_invocation_context.InvocationContext,
   LOAD_WEB_PAGE: () => import_load_web_page.LOAD_WEB_PAGE,
   LOGGING_FORMAT: () => import_logs.LOGGING_FORMAT,
@@ -66,6 +67,7 @@ __export(index_exports, {
   SecretManagerClient: () => import_secret_client.SecretManagerClient,
   ServiceAccountCredentialExchanger: () => import_service_account_exchanger.ServiceAccountCredentialExchanger,
   SkillToolset: () => import_skill_toolset.SkillToolset,
+  StaleSessionError: () => import_database_session_service.StaleSessionError,
   TOOL_TRAJECTORY_SCORE_KEY: () => import_cli_eval.TOOL_TRAJECTORY_SCORE_KEY,
   ToolAuthHandler: () => import_tool_auth_handler.ToolAuthHandler,
   ToolContextCredentialStore: () => import_tool_auth_handler.ToolContextCredentialStore,
@@ -99,6 +101,7 @@ __export(index_exports, {
   getSessionServiceFromUri: () => import_registry2.getSessionServiceFromUri,
   getTypeHint: () => import_common.getTypeHint,
   isDebugLoggingPlugin: () => import_debug_logging_plugin.isDebugLoggingPlugin,
+  isStaleSessionError: () => import_database_session_service.isStaleSessionError,
   listOperation: () => import_connections_client.listOperation,
   listOperationRequest: () => import_connections_client.listOperationRequest,
   loadAllSkillsInDir: () => import_loader.loadAllSkillsInDir,
@@ -106,7 +109,6 @@ __export(index_exports, {
   loadSkillFromDir: () => import_loader.loadSkillFromDir,
   loadSkillFromZipBuffer: () => import_loader.loadSkillFromZipBuffer,
   loadWebPage: () => import_load_web_page.loadWebPage,
-  logToStderr: () => import_logs.logToStderr,
   logToTmpFolder: () => import_logs.logToTmpFolder,
   openidDictToSchemeCredential: () => import_auth_helpers.openidDictToSchemeCredential,
   openidUrlToSchemeCredential: () => import_auth_helpers.openidUrlToSchemeCredential,
@@ -114,6 +116,7 @@ __export(index_exports, {
   runEvals: () => import_cli_eval.runEvals,
   serviceAccountDictToSchemeCredential: () => import_auth_helpers.serviceAccountDictToSchemeCredential,
   serviceAccountSchemeCredential: () => import_auth_helpers.serviceAccountSchemeCredential,
+  setupAdkLogger: () => import_logs.setupAdkLogger,
   tokenToSchemeCredential: () => import_auth_helpers.tokenToSchemeCredential,
   tryGetResetFunc: () => import_cli_eval.tryGetResetFunc,
   updateOperation: () => import_connections_client.updateOperation,
@@ -148,6 +151,7 @@ var import_secret_client = require("./tools/apihub_tool/clients/secret_client.js
 var import_application_integration_toolset = require("./tools/application_integration_tool/application_integration_toolset.js");
 var import_connections_client = require("./tools/application_integration_tool/clients/connections_client.js");
 var import_integration_client = require("./tools/application_integration_tool/clients/integration_client.js");
+var import_integration_connector_tool = require("./tools/application_integration_tool/integration_connector_tool.js");
 var import_load_web_page = require("./tools/load_web_page.js");
 var import_auth_helpers = require("./tools/openapi_tool/auth/auth_helpers.js");
 var import_auto_auth_credential_exchanger = require("./tools/openapi_tool/auth/credential_exchangers/auto_auth_credential_exchanger.js");
@@ -203,6 +207,7 @@ __reExport(index_exports, require("./tools/mcp/index.js"), module.exports);
   GcsArtifactService,
   INTERNAL_AUTH_PREFIX,
   IntegrationClient,
+  IntegrationConnectorTool,
   InvocationContext,
   LOAD_WEB_PAGE,
   LOGGING_FORMAT,
@@ -222,6 +227,7 @@ __reExport(index_exports, require("./tools/mcp/index.js"), module.exports);
   SecretManagerClient,
   ServiceAccountCredentialExchanger,
   SkillToolset,
+  StaleSessionError,
   TOOL_TRAJECTORY_SCORE_KEY,
   ToolAuthHandler,
   ToolContextCredentialStore,
@@ -255,6 +261,7 @@ __reExport(index_exports, require("./tools/mcp/index.js"), module.exports);
   getSessionServiceFromUri,
   getTypeHint,
   isDebugLoggingPlugin,
+  isStaleSessionError,
   listOperation,
   listOperationRequest,
   loadAllSkillsInDir,
@@ -262,7 +269,6 @@ __reExport(index_exports, require("./tools/mcp/index.js"), module.exports);
   loadSkillFromDir,
   loadSkillFromZipBuffer,
   loadWebPage,
-  logToStderr,
   logToTmpFolder,
   openidDictToSchemeCredential,
   openidUrlToSchemeCredential,
@@ -270,6 +276,7 @@ __reExport(index_exports, require("./tools/mcp/index.js"), module.exports);
   runEvals,
   serviceAccountDictToSchemeCredential,
   serviceAccountSchemeCredential,
+  setupAdkLogger,
   tokenToSchemeCredential,
   tryGetResetFunc,
   updateOperation,

package/dist/cjs/plugins/base_plugin.js

@@ -272,29 +272,19 @@ const _BasePlugin = class _BasePlugin {
     return;
   }
   /**
-     * Callback executed when a tool call encounters an error.
-      tool: BaseTool;
-      toolArgs: Record<string, unknown>;
-      toolContext: Context;
-      result: Record<string, unknown>;
-    }): Promise<Record<string, unknown> | undefined> {
-      return;
-    }
-  
-    /**
-     * Callback executed when a tool call encounters an error.
-     *
-     * This callback provides an opportunity to handle tool errors gracefully,
-     * potentially providing alternative responses or recovery mechanisms.
-     *
-     * @param _params.tool The tool instance that encountered an error.
-     * @param _params.toolArgs The arguments that were passed to the tool.
-     * @param _params.toolContext The context specific to the tool execution.
-     * @param _params.error The exception that was raised during tool execution.
-     * @returns An optional dictionary. If a dictionary is returned, it will be
-     *     used as the tool response instead of propagating the error. Returning
-     *     `undefined` allows the original error to be raised.
-     */
+   * Callback executed when a tool call encounters an error.
+   *
+   * This callback provides an opportunity to handle tool errors gracefully,
+   * potentially providing alternative responses or recovery mechanisms.
+   *
+   * @param _params.tool The tool instance that encountered an error.
+   * @param _params.toolArgs The arguments that were passed to the tool.
+   * @param _params.toolContext The context specific to the tool execution.
+   * @param _params.error The exception that was raised during tool execution.
+   * @returns An optional dictionary. If a dictionary is returned, it will be
+   *     used as the tool response instead of propagating the error. Returning
+   *     `undefined` allows the original error to be raised.
+   */
   async onToolErrorCallback(_params) {
     return;
   }

package/dist/cjs/sessions/base_session_service.js

@@ -28,7 +28,8 @@ __export(base_session_service_exports, {
   BaseSessionService: () => BaseSessionService,
   mergeStates: () => mergeStates,
   trimTempDeltaState: () => trimTempDeltaState,
-  trimTempState: () => trimTempState
+  trimTempState: () => trimTempState,
+  upsertSessionEvent: () => upsertSessionEvent
 });
 module.exports = __toCommonJS(base_session_service_exports);
 var import_lodash_es = require("lodash-es");
@@ -72,12 +73,7 @@ const _BaseSessionService = class _BaseSessionService {
     }
     event = trimTempDeltaState(event);
     this.updateSessionState({ session, event });
-    const index = session.events.findIndex((e) => e.id === event.id);
-    if (index >= 0) {
-      session.events[index] = event;
-    } else {
-      session.events.push(event);
-    }
+    upsertSessionEvent(session, event);
     return event;
   }
   /**
@@ -107,6 +103,15 @@ const _BaseSessionService = class _BaseSessionService {
 };
 __name(_BaseSessionService, "BaseSessionService");
 let BaseSessionService = _BaseSessionService;
+function upsertSessionEvent(session, event) {
+  const index = session.events.findIndex((e) => e.id === event.id);
+  if (index >= 0) {
+    session.events[index] = event;
+  } else {
+    session.events.push(event);
+  }
+}
+__name(upsertSessionEvent, "upsertSessionEvent");
 function trimTempDeltaState(event) {
   if (!event.actions || !event.actions.stateDelta) {
     return event;
@@ -149,5 +154,6 @@ __name(mergeStates, "mergeStates");
   BaseSessionService,
   mergeStates,
   trimTempDeltaState,
-  trimTempState
+  trimTempState,
+  upsertSessionEvent
 });

package/dist/cjs/sessions/database_session_service.js

@@ -36,13 +36,18 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var database_session_service_exports = {};
 __export(database_session_service_exports, {
   DatabaseSessionService: () => DatabaseSessionService,
-  isDatabaseConnectionString: () => isDatabaseConnectionString
+  StaleSessionError: () => import_stale_session_error2.StaleSessionError,
+  isDatabaseConnectionString: () => isDatabaseConnectionString,
+  isStaleSessionError: () => import_stale_session_error2.isStaleSessionError
 });
 module.exports = __toCommonJS(database_session_service_exports);
 var import_env_aware_utils = require("../utils/env_aware_utils.js");
+var import_logger = require("../utils/logger.js");
 var import_base_session_service = require("./base_session_service.js");
 var import_session = require("./session.js");
+var import_stale_session_error = require("./stale_session_error.js");
 var import_state = require("./state.js");
+var import_stale_session_error2 = require("./stale_session_error.js");
 /**
  * @license
  * Copyright 2026 Google LLC
@@ -79,6 +84,11 @@ async function importMikroOrm() {
   } = operations);
 }
 __name(importMikroOrm, "importMikroOrm");
+function formatDateTime(dateOrEpochMs) {
+  const date = typeof dateOrEpochMs === "number" ? new Date(dateOrEpochMs) : dateOrEpochMs;
+  return date.toISOString().replace("T", " ").slice(0, 19);
+}
+__name(formatDateTime, "formatDateTime");
 function isDatabaseConnectionString(uri) {
   if (!uri) {
     return false;
@@ -87,16 +97,20 @@ function isDatabaseConnectionString(uri) {
 }
 __name(isDatabaseConnectionString, "isDatabaseConnectionString");
 const _DatabaseSessionService = class _DatabaseSessionService extends import_base_session_service.BaseSessionService {
-  constructor(connectionStringOrOptions) {
+  constructor(connectionStringOrOptions, options) {
+    var _a;
     super();
     this.initialized = false;
     if (typeof connectionStringOrOptions === "string") {
       this.connectionString = connectionStringOrOptions;
+      this.staleSession = (_a = options == null ? void 0 : options.staleSession) != null ? _a : "reject";
     } else {
       if (!connectionStringOrOptions.driver) {
         throw new Error("Driver is required when passing options object.");
       }
-      this.options = connectionStringOrOptions;
+      const { staleSession, ...mikroOptions } = connectionStringOrOptions;
+      this.options = mikroOptions;
+      this.staleSession = staleSession != null ? staleSession : "reject";
     }
   }
   async init() {
@@ -342,6 +356,7 @@ const _DatabaseSessionService = class _DatabaseSessionService extends import_bas
       return event;
     }
     const trimmedEvent = (0, import_base_session_service.trimTempDeltaState)(event);
+    let sessionWasStale = false;
     await em.transactional(async (txEm) => {
       const storageSession = await txEm.findOne(
         StorageSession,
@@ -355,6 +370,14 @@ const _DatabaseSessionService = class _DatabaseSessionService extends import_bas
       if (!storageSession) {
         throw new Error(`Session ${session.id} not found for appendEvent`);
       }
+      if (storageSession.updateTime.getTime() > session.lastUpdateTime) {
+        if (this.staleSession === "reject") {
+          throw new import_stale_session_error.StaleSessionError(
+            `The last_update_time provided in the session object ${formatDateTime(session.lastUpdateTime)} is earlier than the update_time in the storage_session ${formatDateTime(storageSession.updateTime)}. Please check if it is a stale session.`
+          );
+        }
+        sessionWasStale = true;
+      }
       let appStateModel = await txEm.findOne(StorageAppState, {
         appName: session.appName
       });
@@ -378,24 +401,6 @@ const _DatabaseSessionService = class _DatabaseSessionService extends import_bas
         });
         txEm.persist(userStateModel);
       }
-      if (storageSession.updateTime.getTime() > session.lastUpdateTime) {
-        const events = await txEm.find(
-          StorageEvent,
-          {
-            appName: session.appName,
-            userId: session.userId,
-            sessionId: session.id
-          },
-          { orderBy: { timestamp: "ASC" } }
-        );
-        const mergedState = (0, import_base_session_service.mergeStates)(
-          appStateModel.state,
-          userStateModel.state,
-          storageSession.state
-        );
-        session.state = mergedState;
-        session.events = events.map((e) => e.eventData);
-      }
       if (event.actions && event.actions.stateDelta) {
         const appDelta = {};
         const userDelta = {};
@@ -449,14 +454,29 @@ const _DatabaseSessionService = class _DatabaseSessionService extends import_bas
         storageSession.state
       );
       session.state = newMergedState;
-      const index = session.events.findIndex((e) => e.id === event.id);
-      if (index >= 0) {
-        session.events[index] = event;
-      } else {
-        session.events.push(event);
-      }
+      (0, import_base_session_service.upsertSessionEvent)(session, event);
       session.lastUpdateTime = storageSession.updateTime.getTime();
     });
+    if (sessionWasStale) {
+      try {
+        const storageEvents = await em.find(
+          StorageEvent,
+          {
+            appName: session.appName,
+            userId: session.userId,
+            sessionId: session.id
+          },
+          { orderBy: { timestamp: "ASC" } }
+        );
+        session.events = storageEvents.map((se) => se.eventData);
+        (0, import_base_session_service.upsertSessionEvent)(session, event);
+      } catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        import_logger.logger.warn(
+          `Failed to reload events for stale session ${session.id} after appendEvent; the event was persisted but session.events may be missing concurrent appends: ${message}`
+        );
+      }
+    }
     return event;
   }
 };
@@ -465,5 +485,7 @@ let DatabaseSessionService = _DatabaseSessionService;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DatabaseSessionService,
-  isDatabaseConnectionString
+  StaleSessionError,
+  isDatabaseConnectionString,
+  isStaleSessionError
 });

package/dist/cjs/sessions/stale_session_error.js

@@ -0,0 +1,59 @@
+/**
+  * @license
+  * Copyright 2026 Google LLC
+  * SPDX-License-Identifier: Apache-2.0
+  */
+
+"use strict";
+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 });
+};
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var stale_session_error_exports = {};
+__export(stale_session_error_exports, {
+  StaleSessionError: () => StaleSessionError,
+  isStaleSessionError: () => isStaleSessionError
+});
+module.exports = __toCommonJS(stale_session_error_exports);
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+var _a, _b;
+const STALE_SESSION_ERROR_SIGNATURE_SYMBOL = /* @__PURE__ */ Symbol.for(
+  "google.adk.staleSessionError"
+);
+const _StaleSessionError = class _StaleSessionError extends (_b = Error, _a = STALE_SESSION_ERROR_SIGNATURE_SYMBOL, _b) {
+  constructor(message) {
+    super(message);
+    this[_a] = true;
+    this.name = "StaleSessionError";
+    Object.setPrototypeOf(this, _StaleSessionError.prototype);
+  }
+};
+__name(_StaleSessionError, "StaleSessionError");
+let StaleSessionError = _StaleSessionError;
+function isStaleSessionError(obj) {
+  return typeof obj === "object" && obj !== null && (STALE_SESSION_ERROR_SIGNATURE_SYMBOL in obj || obj instanceof Error && obj.name === "StaleSessionError");
+}
+__name(isStaleSessionError, "isStaleSessionError");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  StaleSessionError,
+  isStaleSessionError
+});