@google/adk 2.2.1 → 2.4.0

package/dist/esm/runner/runner.js

@@ -31,6 +31,7 @@ import {
   BuiltInCodeExecutor,
   isBuiltInCodeExecutor
 } from "../code_executors/built_in_code_executor.js";
+import { buildAbortEvents, isAbortEvent } from "../events/abort_events.js";
 import { createEvent } from "../events/event.js";
 import { createEventActions } from "../events/event_actions.js";
 import {
@@ -64,8 +65,8 @@ const _Runner = class _Runner {
    */
   constructor(input) {
     this[_a] = true;
-    var _a2, _b, _c, _d, _e, _f, _g, _h, _i;
-    const appName = (_b = (_a2 = input.app) == null ? void 0 : _a2.name) != null ? _b : input.appName;
+    var _a2, _b, _c, _d, _e, _f, _g, _h, _i, _j;
+    const appName = (_b = input.appName) != null ? _b : (_a2 = input.app) == null ? void 0 : _a2.name;
     const agent = (_d = (_c = input.app) == null ? void 0 : _c.rootAgent) != null ? _d : input.agent;
     if (!agent) {
       throw new Error(
@@ -82,6 +83,20 @@ const _Runner = class _Runner {
     this.memoryService = input.memoryService;
     this.credentialService = input.credentialService;
     this.resumabilityConfig = (_i = (_h = input.app) == null ? void 0 : _h.resumabilityConfig) != null ? _i : input.resumabilityConfig;
+    this.autoCreateSession = (_j = input.autoCreateSession) != null ? _j : false;
+  }
+  /**
+   * Looks the session up, creating it first when `autoCreateSession` is set.
+   *
+   * A runner with no `appName` cannot address a session, so it falls through to
+   * the plain lookup rather than creating one under an undefined app name.
+   */
+  async resolveSession(userId, sessionId) {
+    const key = { appName: this.appName, userId, sessionId };
+    if (this.autoCreateSession && this.appName) {
+      return this.sessionService.getOrCreateSession(key);
+    }
+    return this.sessionService.getSession(key);
   }
   /**
    * Runs the agent with a new, ephemeral session.
@@ -142,12 +157,8 @@ const _Runner = class _Runner {
         ctx,
         this,
         async function* () {
-          var _a2, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k;
-          const session = await this.sessionService.getSession({
-            appName: this.appName,
-            userId,
-            sessionId
-          });
+          var _a2, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l;
+          const session = await this.resolveSession(userId, sessionId);
           if ((_a2 = params.abortSignal) == null ? void 0 : _a2.aborted) {
             return;
           }
@@ -258,35 +269,45 @@ const _Runner = class _Runner {
               }
               yield earlyExitEvent;
             } else {
-              for await (const event of this.runRoot(invocationContext)) {
-                if ((_h = params.abortSignal) == null ? void 0 : _h.aborted) {
-                  return;
-                }
-                const modifiedEvent = await this.pluginManager.runOnEventCallback({
-                  invocationContext,
-                  event
-                });
-                const outputEvent = modifiedEvent ? {
-                  ...withInternalMetadataOf(event, modifiedEvent),
-                  id: event.id,
-                  invocationId: event.invocationId,
-                  timestamp: event.timestamp,
-                  author: modifiedEvent.author || event.author,
-                  branch: (_i = modifiedEvent.branch) != null ? _i : event.branch
-                } : event;
-                if (!event.partial) {
-                  await this.sessionService.appendEvent({
-                    session,
-                    event: outputEvent
-                  });
+              let abortSealed = false;
+              const sealAbortedInvocation = /* @__PURE__ */ __name(() => {
+                abortSealed = true;
+                return this.synthesizeAbortEvents(invocationContext);
+              }, "sealAbortedInvocation");
+              try {
+                for await (const event of this.runRoot(invocationContext)) {
+                  if ((_h = params.abortSignal) == null ? void 0 : _h.aborted) {
+                    break;
+                  }
+                  const outputEvent = await this.processAndAppendEvent(
+                    invocationContext,
+                    event
+                  );
+                  if ((_i = params.abortSignal) == null ? void 0 : _i.aborted) {
+                    break;
+                  }
+                  yield outputEvent;
                 }
                 if ((_j = params.abortSignal) == null ? void 0 : _j.aborted) {
+                  for (const abortEvent of await sealAbortedInvocation()) {
+                    yield abortEvent;
+                  }
                   return;
                 }
-                yield outputEvent;
+              } finally {
+                if (((_k = params.abortSignal) == null ? void 0 : _k.aborted) && !abortSealed) {
+                  try {
+                    await sealAbortedInvocation();
+                  } catch (e) {
+                    logger.error(
+                      `Failed to seal aborted invocation ${invocationContext.invocationId}.`,
+                      e
+                    );
+                  }
+                }
               }
               await this.pluginManager.runAfterRunCallback({ invocationContext });
-              if ((_k = params.abortSignal) == null ? void 0 : _k.aborted) {
+              if ((_l = params.abortSignal) == null ? void 0 : _l.aborted) {
                 return;
               }
             }
@@ -318,6 +339,56 @@ const _Runner = class _Runner {
     }
     yield* runNodeAsInvocation(this.agent, invocationContext);
   }
+  /**
+   * Runs the on_event plugin callbacks on an event and appends the result to
+   * the session unless it is partial.
+   *
+   * @returns The event as streamed to the caller.
+   */
+  async processAndAppendEvent(invocationContext, event) {
+    var _a2;
+    const modifiedEvent = await this.pluginManager.runOnEventCallback({
+      invocationContext,
+      event
+    });
+    const outputEvent = modifiedEvent ? {
+      ...withInternalMetadataOf(event, modifiedEvent),
+      id: event.id,
+      invocationId: event.invocationId,
+      timestamp: event.timestamp,
+      author: modifiedEvent.author || event.author,
+      branch: (_a2 = modifiedEvent.branch) != null ? _a2 : event.branch
+    } : event;
+    if (!event.partial) {
+      await this.sessionService.appendEvent({
+        session: invocationContext.session,
+        event: outputEvent
+      });
+    }
+    return outputEvent;
+  }
+  /**
+   * Seals an aborted invocation in session history: answers its dangling
+   * function calls with error responses, or records a plain abort event when
+   * there is nothing to answer.
+   *
+   * @returns The synthetic events after plugin processing and persistence.
+   */
+  async synthesizeAbortEvents(invocationContext) {
+    const abortEvents = buildAbortEvents({
+      events: invocationContext.session.events,
+      invocationId: invocationContext.invocationId,
+      rootAgentName: this.agent.name,
+      branch: invocationContext.branch
+    });
+    const outputEvents = [];
+    for (const event of abortEvents) {
+      outputEvents.push(
+        await this.processAndAppendEvent(invocationContext, event)
+      );
+    }
+    return outputEvents;
+  }
   /**
    * Saves artifacts from the message parts and replaces the inline data with
    * a file name placeholder and optional file reference.
@@ -564,7 +635,8 @@ function isLiveModelMediaEventWithInlineData(event) {
 }
 __name(isLiveModelMediaEventWithInlineData, "isLiveModelMediaEventWithInlineData");
 function determineAgentForResumption(session, rootAgent, resumabilityConfig) {
-  const event = findEventByLastFunctionResponseId(session.events);
+  const lastEvent = session.events[session.events.length - 1];
+  const event = lastEvent && !isAbortEvent(lastEvent) ? findEventByLastFunctionResponseId(session.events) : null;
   const isResumable = Boolean(resumabilityConfig == null ? void 0 : resumabilityConfig.isResumable);
   if (event && event.author && isResumable) {
     const conflictingAuthors = getConflictingFunctionResponseAuthors(
@@ -588,7 +660,7 @@ function determineAgentForResumption(session, rootAgent, resumabilityConfig) {
   for (let i = session.events.length - 1; i >= 0; i--) {
     logger.debug("event:", stringifyWithRedactedInlineData(session.events[i]));
     const event2 = session.events[i];
-    if (event2.author === "user" || !event2.author) {
+    if (event2.author === "user" || !event2.author || isAbortEvent(event2)) {
       continue;
     }
     if (event2.author === rootAgent.name) {

package/dist/esm/sessions/base_session_service.js

@@ -43,12 +43,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;
   }
   /**
@@ -78,6 +73,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;
@@ -119,5 +123,6 @@ export {
   BaseSessionService,
   mergeStates,
   trimTempDeltaState,
-  trimTempState
+  trimTempState,
+  upsertSessionEvent
 };

package/dist/esm/sessions/database_session_service.js

@@ -29,12 +29,15 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
  * SPDX-License-Identifier: Apache-2.0
  */
 import { randomUUID } from "../utils/env_aware_utils.js";
+import { logger } from "../utils/logger.js";
 import {
   BaseSessionService,
   mergeStates,
-  trimTempDeltaState
+  trimTempDeltaState,
+  upsertSessionEvent
 } from "./base_session_service.js";
 import { createSession } from "./session.js";
+import { StaleSessionError } from "./stale_session_error.js";
 import { State } from "./state.js";
 let MikroORM;
 let LockMode;
@@ -67,6 +70,12 @@ async function importMikroOrm() {
   } = operations);
 }
 __name(importMikroOrm, "importMikroOrm");
+import { isStaleSessionError, StaleSessionError as StaleSessionError2 } from "./stale_session_error.js";
+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;
@@ -75,16 +84,20 @@ function isDatabaseConnectionString(uri) {
 }
 __name(isDatabaseConnectionString, "isDatabaseConnectionString");
 const _DatabaseSessionService = class _DatabaseSessionService extends 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() {
@@ -330,6 +343,7 @@ const _DatabaseSessionService = class _DatabaseSessionService extends BaseSessio
       return event;
     }
     const trimmedEvent = trimTempDeltaState(event);
+    let sessionWasStale = false;
     await em.transactional(async (txEm) => {
       const storageSession = await txEm.findOne(
         StorageSession,
@@ -343,6 +357,14 @@ const _DatabaseSessionService = class _DatabaseSessionService extends BaseSessio
       if (!storageSession) {
         throw new Error(`Session ${session.id} not found for appendEvent`);
       }
+      if (storageSession.updateTime.getTime() > session.lastUpdateTime) {
+        if (this.staleSession === "reject") {
+          throw new 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
       });
@@ -366,24 +388,6 @@ const _DatabaseSessionService = class _DatabaseSessionService extends BaseSessio
         });
         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 = 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 = {};
@@ -437,14 +441,29 @@ const _DatabaseSessionService = class _DatabaseSessionService extends BaseSessio
         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);
-      }
+      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);
+        upsertSessionEvent(session, event);
+      } catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        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;
   }
 };
@@ -452,5 +471,7 @@ __name(_DatabaseSessionService, "DatabaseSessionService");
 let DatabaseSessionService = _DatabaseSessionService;
 export {
   DatabaseSessionService,
-  isDatabaseConnectionString
+  StaleSessionError2 as StaleSessionError,
+  isDatabaseConnectionString,
+  isStaleSessionError
 };

package/dist/esm/sessions/db/operations.js

@@ -281,7 +281,7 @@ async function getConnectionOptionsFromUri(uri) {
     );
     return {
       entities: ENTITIES,
-      dbName: uri === "sqlite://:memory:" ? ":memory:" : uri.substring("sqlite://".length),
+      dbName: uri === "sqlite://:memory:" || uri === "sqlite:///:memory:" ? ":memory:" : uri.substring("sqlite://".length),
       driver: SqliteDriver
     };
   }

package/dist/esm/sessions/in_memory_session_service.js

@@ -47,7 +47,9 @@ const _InMemorySessionService = class _InMemorySessionService extends BaseSessio
     var _a;
     const filteredState = state ? trimTempState(state) : void 0;
     const session = createSession({
-      id: sessionId || randomUUID(),
+      // Surrounding whitespace is dropped so that a later lookup by the bare
+      // id finds the session, and a blank id gets a generated one.
+      id: (sessionId == null ? void 0 : sessionId.trim()) || randomUUID(),
       appName,
       userId,
       state: filteredState,

package/dist/esm/sessions/stale_session_error.js

@@ -0,0 +1,31 @@
+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
+ */
+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");
+export {
+  StaleSessionError,
+  isStaleSessionError
+};

package/dist/esm/sessions/state.js

@@ -74,16 +74,19 @@ const _State = class _State {
   /**
    * Returns the value of the state dict for the given key.
    *
+   * Only keys the state holds itself are found. Names inherited from
+   * `Object.prototype`, such as `toString`, are treated as missing.
+   *
    * @param key The key to get the value for.
    * @param defaultValue The default value to return if the key is not found.
    * @return The value of the state for the given key, or the default value if
    *     not found.
    */
   get(key, defaultValue) {
-    if (key in this.delta) {
+    if (Object.hasOwn(this.delta, key)) {
       return this.delta[key];
     }
-    if (key in this.value) {
+    if (Object.hasOwn(this.value, key)) {
       return this.value[key];
     }
     return defaultValue;
@@ -101,10 +104,11 @@ const _State = class _State {
     recordStateWrite(this.value, this.delta, key);
   }
   /**
-   * Whether the state has pending delta.
+   * Whether the state holds the given key, either as a stored value or as a
+   * pending delta. Names inherited from `Object.prototype` are not keys.
    */
   has(key) {
-    return key in this.value || key in this.delta;
+    return Object.hasOwn(this.value, key) || Object.hasOwn(this.delta, key);
   }
   /**
    * Whether the state has pending delta.

package/dist/esm/sessions/vertex_ai_session_service.js

@@ -44,17 +44,22 @@ function quoteFilterLiteral(value) {
   return `"${escaped}"`;
 }
 __name(quoteFilterLiteral, "quoteFilterLiteral");
+function toStateMap(state) {
+  return Object.assign(/* @__PURE__ */ Object.create(null), state);
+}
+__name(toStateMap, "toStateMap");
 let VertexAiSessionService = class extends BaseSessionService {
   constructor(options) {
     super();
     this.agentEngineId = options.agentEngineId;
-    this.projectId = options.projectId;
-    this.location = options.location;
     this.expressModeApiKey = getExpressModeApiKey(
-      this.projectId,
-      this.location,
+      options.projectId,
+      options.location,
       options.expressModeApiKey
     );
+    const useEnvironment = !options.expressModeApiKey;
+    this.projectId = options.projectId || (useEnvironment ? process.env["GOOGLE_CLOUD_PROJECT"] : void 0);
+    this.location = options.location || (useEnvironment ? process.env["GOOGLE_CLOUD_LOCATION"] : void 0);
     if (options.sessions) {
       this.sessions = options.sessions;
     } else {
@@ -140,7 +145,7 @@ let VertexAiSessionService = class extends BaseSessionService {
       id,
       appName,
       userId,
-      state: getSessionResponse.sessionState,
+      state: toStateMap(getSessionResponse.sessionState),
       events: [],
       lastUpdateTime: getSessionResponse.updateTime ? Date.parse(getSessionResponse.updateTime) : Date.now()
     });
@@ -155,13 +160,14 @@ let VertexAiSessionService = class extends BaseSessionService {
     const sessionResourceName = `reasoningEngines/${reasoningEngineId}/sessions/${sessionId}`;
     try {
       let getSessionResponse;
-      let eventsIterator = [];
+      const eventsIterator = [];
+      const listConfig = {};
+      let pageToken;
       if (config && config.numRecentEvents === 0) {
         getSessionResponse = await this.sessions.get({
           name: sessionResourceName
         });
       } else {
-        const listConfig = {};
         if (config && config.afterTimestamp) {
           listConfig.filter = `timestamp>="${new Date(
             config.afterTimestamp
@@ -175,7 +181,9 @@ let VertexAiSessionService = class extends BaseSessionService {
           })
         ]);
         getSessionResponse = sessionRes;
-        eventsIterator = eventsRes.sessionEvents || [];
+        const firstPage = eventsRes;
+        eventsIterator.push(...firstPage.sessionEvents || []);
+        pageToken = firstPage.nextPageToken;
       }
       const sessionObj = getSessionResponse;
       if (sessionObj.userId !== userId) {
@@ -183,20 +191,29 @@ let VertexAiSessionService = class extends BaseSessionService {
           `Session ${sessionId} does not belong to user ${userId}.`
         );
       }
+      while (pageToken) {
+        const eventsRes = await this.sessions.events.listInternal({
+          name: sessionResourceName,
+          config: {
+            ...listConfig,
+            pageToken
+          }
+        });
+        eventsIterator.push(...eventsRes.sessionEvents || []);
+        pageToken = eventsRes.nextPageToken;
+      }
       const session = createSession({
         id: sessionId,
         appName,
         userId,
-        state: sessionObj.sessionState,
+        state: toStateMap(sessionObj.sessionState),
         events: [],
         lastUpdateTime: sessionObj.updateTime ? Date.parse(sessionObj.updateTime) : Date.now()
       });
-      for (const event of eventsIterator) {
+      const recentEvents = config && config.numRecentEvents ? eventsIterator.slice(-config.numRecentEvents) : eventsIterator;
+      for (const event of recentEvents) {
         session.events.push(_fromApiEvent(event));
       }
-      if (config && config.numRecentEvents) {
-        session.events = session.events.slice(-config.numRecentEvents);
-      }
       return session;
     } catch (error) {
       const err = error;
@@ -235,7 +252,7 @@ let VertexAiSessionService = class extends BaseSessionService {
             id,
             appName,
             userId: sessionObj.userId,
-            state: sessionObj.sessionState,
+            state: toStateMap(sessionObj.sessionState),
             events: [],
             lastUpdateTime: sessionObj.updateTime ? new Date(sessionObj.updateTime).getTime() : Date.now()
           })
@@ -481,7 +498,9 @@ function _fromApiEvent(apiEventObj) {
     }
   }
   const eventActions = {
-    stateDelta: actions["stateDelta"] || {},
+    stateDelta: toStateMap(
+      actions["stateDelta"]
+    ),
     artifactDelta: actions["artifactDelta"] || {},
     requestedAuthConfigs: actions.requestedAuthConfigs || {},
     requestedToolConfirmations: actions["requestedToolConfirmations"] || {},