@softactivate/adk 1.1.0 → 1.2.0

package/dist/esm/sessions/database_session_service.js

@@ -193,7 +193,11 @@ class DatabaseSessionService extends BaseSessionService {
   }
   async listSessions({
     appName,
-    userId
+    userId,
+    limit,
+    offset,
+    page,
+    order
   }) {
     await this.init();
     const em = this.orm.em.fork();
@@ -201,7 +205,49 @@ class DatabaseSessionService extends BaseSessionService {
     if (userId) {
       where.userId = userId;
     }
-    const storageSessions = await em.find(StorageSession, where);
+    const orderBy = order === "asc" ? { updateTime: "ASC", id: "ASC" } : order === "desc" ? { updateTime: "DESC", id: "ASC" } : void 0;
+    let storageSessions;
+    let paginationMeta;
+    if (limit !== void 0) {
+      const totalItems = await em.count(StorageSession, where);
+      const totalPages = limit === 0 ? 0 : Math.ceil(totalItems / limit);
+      let effectiveOffset;
+      let effectivePage;
+      if (page !== void 0) {
+        effectiveOffset = (page - 1) * limit;
+        effectivePage = page;
+      } else {
+        effectiveOffset = offset != null ? offset : 0;
+        effectivePage = limit === 0 ? 1 : Math.floor(effectiveOffset / limit) + 1;
+      }
+      storageSessions = await em.find(StorageSession, where, {
+        orderBy,
+        limit,
+        offset: effectiveOffset
+      });
+      paginationMeta = { page: effectivePage, limit, totalItems, totalPages };
+    } else if (offset) {
+      const totalItems = await em.count(StorageSession, where);
+      storageSessions = await em.find(StorageSession, where, {
+        orderBy,
+        offset
+      });
+      paginationMeta = {
+        page: 1,
+        limit: totalItems,
+        totalItems,
+        totalPages: totalItems === 0 ? 0 : 1
+      };
+    } else {
+      storageSessions = await em.find(StorageSession, where, { orderBy });
+      const totalItems = storageSessions.length;
+      paginationMeta = {
+        page: 1,
+        limit: totalItems,
+        totalItems,
+        totalPages: totalItems === 0 ? 0 : 1
+      };
+    }
     const appStateModel = await em.findOne(StorageAppState, { appName });
     const appState = (appStateModel == null ? void 0 : appStateModel.state) || {};
     const userStateMap = {};
@@ -226,7 +272,7 @@ class DatabaseSessionService extends BaseSessionService {
         lastUpdateTime: ss.updateTime.getTime()
       });
     });
-    return { sessions };
+    return { sessions, ...paginationMeta };
   }
   async deleteSession({
     appName,

package/dist/esm/sessions/in_memory_session_service.js

@@ -104,25 +104,81 @@ class InMemorySessionService extends BaseSessionService {
   }
   listSessions({
     appName,
-    userId
+    userId,
+    limit,
+    offset,
+    page,
+    order
   }) {
     if (!this.sessions[appName] || !this.sessions[appName][userId]) {
-      return Promise.resolve({ sessions: [] });
+      if (limit !== void 0) {
+        const effectiveOffset2 = page !== void 0 ? (page - 1) * limit : offset != null ? offset : 0;
+        const effectivePage2 = page !== void 0 ? page : limit === 0 ? 1 : Math.floor(effectiveOffset2 / limit) + 1;
+        return Promise.resolve({
+          sessions: [],
+          page: effectivePage2,
+          limit,
+          totalItems: 0,
+          totalPages: 0
+        });
+      }
+      return Promise.resolve({
+        sessions: [],
+        page: 1,
+        limit: 0,
+        totalItems: 0,
+        totalPages: 0
+      });
     }
-    const sessionsWithoutEvents = [];
-    for (const session of Object.values(this.sessions[appName][userId])) {
-      sessionsWithoutEvents.push(
-        createSession({
-          id: session.id,
-          appName: session.appName,
-          userId: session.userId,
-          state: {},
-          events: [],
-          lastUpdateTime: session.lastUpdateTime
-        })
+    const all = Object.values(this.sessions[appName][userId]).map(
+      (session) => createSession({
+        id: session.id,
+        appName: session.appName,
+        userId: session.userId,
+        state: {},
+        events: [],
+        lastUpdateTime: session.lastUpdateTime
+      })
+    );
+    if (order === "asc") {
+      all.sort(
+        (a, b) => a.lastUpdateTime - b.lastUpdateTime || a.id.localeCompare(b.id)
+      );
+    } else if (order === "desc") {
+      all.sort(
+        (a, b) => b.lastUpdateTime - a.lastUpdateTime || a.id.localeCompare(b.id)
       );
     }
-    return Promise.resolve({ sessions: sessionsWithoutEvents });
+    if (limit === void 0) {
+      const totalItems2 = all.length;
+      const sliced = offset ? all.slice(offset) : all;
+      return Promise.resolve({
+        sessions: sliced,
+        page: 1,
+        limit: totalItems2,
+        totalItems: totalItems2,
+        totalPages: totalItems2 === 0 ? 0 : 1
+      });
+    }
+    const totalItems = all.length;
+    const totalPages = limit === 0 ? 0 : Math.ceil(totalItems / limit);
+    let effectiveOffset;
+    let effectivePage;
+    if (page !== void 0) {
+      effectiveOffset = (page - 1) * limit;
+      effectivePage = page;
+    } else {
+      effectiveOffset = offset != null ? offset : 0;
+      effectivePage = limit === 0 ? 1 : Math.floor(effectiveOffset / limit) + 1;
+    }
+    const paginated = all.slice(effectiveOffset, effectiveOffset + limit);
+    return Promise.resolve({
+      sessions: paginated,
+      page: effectivePage,
+      limit,
+      totalItems,
+      totalPages
+    });
   }
   async deleteSession({
     appName,

package/dist/esm/sessions/registry.js

@@ -13,6 +13,10 @@ import {
   InMemorySessionService,
   isInMemoryConnectionString
 } from "./in_memory_session_service.js";
+import {
+  VertexAiSessionService,
+  isVertexAiConnectionString
+} from "./vertex_ai_session_service.js";
 function getSessionServiceFromUri(uri) {
   if (isInMemoryConnectionString(uri)) {
     return new InMemorySessionService();
@@ -20,6 +24,9 @@ function getSessionServiceFromUri(uri) {
   if (isDatabaseConnectionString(uri)) {
     return new DatabaseSessionService(uri);
   }
+  if (isVertexAiConnectionString(uri)) {
+    return new VertexAiSessionService({});
+  }
   throw new Error(`Unsupported session service URI: ${uri}`);
 }
 export {

package/dist/esm/sessions/vertex_ai_session_service.js

@@ -0,0 +1,403 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+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 { Client } from "@google-cloud/vertexai/build/src/genai/client.js";
+import { isCompactedEvent } from "../events/compacted_event.js";
+import { experimental } from "../utils/experimental.js";
+import { logger } from "../utils/logger.js";
+import { getExpressModeApiKey } from "../utils/vertex_ai_utils.js";
+import { partialCopy } from "../utils/partial_copy.js";
+import {
+  BaseSessionService
+} from "./base_session_service.js";
+import { createSession } from "./session.js";
+const DEFAULT_MAX_ATTEMPTS = 30;
+const GRPC_NOT_FOUND = 5;
+const HTTP_NOT_FOUND = 404;
+function isVertexAiConnectionString(uri) {
+  return (uri == null ? void 0 : uri.startsWith("vertexai://")) || false;
+}
+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.expressModeApiKey
+    );
+    if (!options.sessions) {
+      if (!this.expressModeApiKey && (!this.projectId || !this.location)) {
+        throw new Error(
+          "Either (Project ID and Location) or an expressModeApiKey is required."
+        );
+      }
+    }
+    if (options.sessions) {
+      this.sessions = options.sessions;
+    } else {
+      const client = new Client({
+        project: this.projectId,
+        location: this.location
+      });
+      this.sessions = client.agentEnginesInternal.sessions;
+    }
+  }
+  getReasoningEngineId(appName) {
+    if (this.agentEngineId) {
+      return this.agentEngineId;
+    }
+    if (/^\d+$/.test(appName)) {
+      return appName;
+    }
+    const pattern = /^projects\/([a-zA-Z0-9-_]+)\/locations\/([a-zA-Z0-9-_]+)\/reasoningEngines\/(\d+)$/;
+    const match = appName.match(pattern);
+    if (!match) {
+      throw new Error(
+        `App name ${appName} is not valid. It should either be the full ReasoningEngine resource name, or the reasoning engine id.`
+      );
+    }
+    return match[3];
+  }
+  async createSession({
+    appName,
+    userId,
+    state,
+    sessionId
+  }) {
+    var _a;
+    const reasoningEngineId = this.getReasoningEngineId(appName);
+    let apiResponse = await this.sessions.createInternal({
+      name: `reasoningEngines/${reasoningEngineId}`,
+      userId,
+      config: {
+        ...state ? { sessionState: state } : {},
+        ...sessionId ? { sessionId } : {}
+      }
+    });
+    const operationName = apiResponse.name;
+    let attempts = 0;
+    while (!apiResponse.done && attempts < DEFAULT_MAX_ATTEMPTS) {
+      const [nextResponse] = await Promise.all([
+        this.sessions.getSessionOperationInternal({
+          operationName
+        }),
+        new Promise((resolve) => setTimeout(resolve, 1e3))
+      ]);
+      apiResponse = nextResponse;
+      attempts++;
+    }
+    if (!apiResponse.done) {
+      throw new Error(
+        `Session creation operation ${operationName} did not complete in time.`
+      );
+    }
+    const getSessionResponse = apiResponse.response;
+    const id = ((_a = getSessionResponse.name) == null ? void 0 : _a.split("/").pop()) || "";
+    return createSession({
+      id,
+      appName,
+      userId,
+      state: getSessionResponse.sessionState,
+      events: [],
+      lastUpdateTime: getSessionResponse.updateTime ? Date.parse(getSessionResponse.updateTime) : Date.now()
+    });
+  }
+  async getSession({
+    appName,
+    userId,
+    sessionId,
+    config
+  }) {
+    const reasoningEngineId = this.getReasoningEngineId(appName);
+    const sessionResourceName = `reasoningEngines/${reasoningEngineId}/sessions/${sessionId}`;
+    try {
+      let getSessionResponse;
+      let eventsIterator = [];
+      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
+          ).toISOString()}"`;
+        }
+        const [sessionRes, eventsRes] = await Promise.all([
+          this.sessions.get({ name: sessionResourceName }),
+          this.sessions.events.listInternal({
+            name: sessionResourceName,
+            config: listConfig
+          })
+        ]);
+        getSessionResponse = sessionRes;
+        eventsIterator = eventsRes.sessionEvents || [];
+      }
+      const sessionObj = getSessionResponse;
+      if (sessionObj.userId !== userId) {
+        throw new Error(
+          `Session ${sessionId} does not belong to user ${userId}.`
+        );
+      }
+      const session = createSession({
+        id: sessionId,
+        appName,
+        userId,
+        state: sessionObj.sessionState,
+        events: [],
+        lastUpdateTime: sessionObj.updateTime ? Date.parse(sessionObj.updateTime) : Date.now()
+      });
+      for (const event of eventsIterator) {
+        session.events.push(_fromApiEvent(event));
+      }
+      if (config && config.numRecentEvents) {
+        session.events = session.events.slice(-config.numRecentEvents);
+      }
+      return session;
+    } catch (error) {
+      const err = error;
+      if (err.code === GRPC_NOT_FOUND || err.code === HTTP_NOT_FOUND) {
+        return void 0;
+      }
+      logger.error(`Error getting session from Vertex AI: ${err.message}`);
+      throw error;
+    }
+  }
+  async listSessions({
+    appName,
+    userId,
+    limit,
+    offset,
+    page,
+    order
+  }) {
+    var _a;
+    const reasoningEngineId = this.getReasoningEngineId(appName);
+    const adkSessions = [];
+    let pageToken = void 0;
+    do {
+      const response = await this.sessions.listInternal({
+        name: `reasoningEngines/${reasoningEngineId}`,
+        config: {
+          ...userId ? { filter: `user_id="${userId}"` } : {},
+          ...pageToken ? { pageToken } : {}
+        }
+      });
+      const sessions = response.sessions || [];
+      for (const sessionObj of sessions) {
+        const id = ((_a = sessionObj.name) == null ? void 0 : _a.split("/").pop()) || "";
+        adkSessions.push(
+          createSession({
+            id,
+            appName,
+            userId: sessionObj.userId,
+            state: sessionObj.sessionState,
+            events: [],
+            lastUpdateTime: sessionObj.updateTime ? new Date(sessionObj.updateTime).getTime() : Date.now()
+          })
+        );
+      }
+      pageToken = response.nextPageToken;
+    } while (pageToken);
+    if (order === "asc") {
+      adkSessions.sort(
+        (a, b) => a.lastUpdateTime - b.lastUpdateTime || a.id.localeCompare(b.id)
+      );
+    } else if (order === "desc") {
+      adkSessions.sort(
+        (a, b) => b.lastUpdateTime - a.lastUpdateTime || a.id.localeCompare(b.id)
+      );
+    }
+    if (limit === void 0) {
+      const totalItems2 = adkSessions.length;
+      const sliced = offset ? adkSessions.slice(offset) : adkSessions;
+      return {
+        sessions: sliced,
+        page: 1,
+        limit: totalItems2,
+        totalItems: totalItems2,
+        totalPages: totalItems2 === 0 ? 0 : 1
+      };
+    }
+    const totalItems = adkSessions.length;
+    const totalPages = limit === 0 ? 0 : Math.ceil(totalItems / limit);
+    let effectiveOffset;
+    let effectivePage;
+    if (page !== void 0) {
+      effectiveOffset = (page - 1) * limit;
+      effectivePage = page;
+    } else {
+      effectiveOffset = offset != null ? offset : 0;
+      effectivePage = limit === 0 ? 1 : Math.floor(effectiveOffset / limit) + 1;
+    }
+    return {
+      sessions: adkSessions.slice(effectiveOffset, effectiveOffset + limit),
+      page: effectivePage,
+      limit,
+      totalItems,
+      totalPages
+    };
+  }
+  async deleteSession({
+    appName,
+    userId: _userId,
+    sessionId
+  }) {
+    const reasoningEngineId = this.getReasoningEngineId(appName);
+    await this.sessions.delete({
+      name: `reasoningEngines/${reasoningEngineId}/sessions/${sessionId}`
+    });
+  }
+  async appendEvent({
+    session,
+    event
+  }) {
+    await super.appendEvent({ session, event });
+    session.lastUpdateTime = event.timestamp;
+    const reasoningEngineId = this.getReasoningEngineId(session.appName);
+    const customMetadata = { ...event.customMetadata };
+    if (isCompactedEvent(event)) {
+      customMetadata._compaction = {
+        startTime: event.startTime,
+        endTime: event.endTime,
+        compactedContent: event.compactedContent
+      };
+    }
+    if (event.usageMetadata) {
+      customMetadata._usage_metadata = event.usageMetadata;
+    }
+    const config = partialCopy(event, [
+      "content",
+      "actions",
+      "errorCode",
+      "errorMessage"
+    ]);
+    config.eventMetadata = {
+      ...partialCopy(event, [
+        "partial",
+        "turnComplete",
+        "interrupted",
+        "branch",
+        "longRunningToolIds",
+        "groundingMetadata"
+      ]),
+      customMetadata: Object.keys(customMetadata).length > 0 ? customMetadata : void 0
+    };
+    config.rawEvent = JSON.parse(JSON.stringify(event));
+    const params = {
+      name: `reasoningEngines/${reasoningEngineId}/sessions/${session.id}`,
+      author: event.author || "user",
+      invocationId: event.invocationId || `inv-${Date.now()}`,
+      timestamp: new Date(event.timestamp).toISOString(),
+      config
+    };
+    try {
+      await this.sessions.events.append(params);
+    } catch (error) {
+      logger.warn(
+        "Failed to append event with rawEvent, falling back...",
+        error
+      );
+      delete config.rawEvent;
+      await this.sessions.events.append({
+        name: `reasoningEngines/${reasoningEngineId}/sessions/${session.id}`,
+        author: event.author || "user",
+        invocationId: event.invocationId || `inv-${Date.now()}`,
+        timestamp: new Date(event.timestamp).toISOString(),
+        config
+      });
+    }
+    return event;
+  }
+};
+VertexAiSessionService = __decorateClass([
+  experimental
+], VertexAiSessionService);
+function _fromApiEvent(apiEventObj) {
+  var _a, _b, _c;
+  const rawEvent = apiEventObj.rawEvent;
+  if (rawEvent) {
+    const event2 = JSON.parse(JSON.stringify(rawEvent));
+    event2.id = ((_a = apiEventObj.name) == null ? void 0 : _a.split("/").pop()) || "";
+    event2.invocationId = apiEventObj.invocationId || "";
+    event2.author = apiEventObj.author;
+    if (apiEventObj.timestamp) {
+      event2.timestamp = new Date(apiEventObj.timestamp).getTime();
+    }
+    return event2;
+  }
+  const actions = apiEventObj.actions || {};
+  const eventMetadata = apiEventObj.eventMetadata || {};
+  let customMetadata = eventMetadata.customMetadata;
+  let compactionData = null;
+  let usageMetadataData = null;
+  if (customMetadata) {
+    if (customMetadata._compaction) {
+      compactionData = customMetadata._compaction;
+      delete customMetadata._compaction;
+    }
+    if (customMetadata._usage_metadata) {
+      usageMetadataData = customMetadata._usage_metadata;
+      delete customMetadata._usage_metadata;
+    }
+    if (Object.keys(customMetadata).length === 0) {
+      customMetadata = void 0;
+    }
+  }
+  const eventActions = {
+    stateDelta: actions["stateDelta"] || {},
+    artifactDelta: actions["artifactDelta"] || {},
+    requestedAuthConfigs: actions.requestedAuthConfigs || {},
+    requestedToolConfirmations: actions["requestedToolConfirmations"] || {},
+    skipSummarization: actions["skipSummarization"],
+    transferToAgent: actions["transferAgent"],
+    escalate: actions["escalate"],
+    compaction: compactionData || void 0
+  };
+  const event = {
+    id: ((_b = apiEventObj.name) == null ? void 0 : _b.split("/").pop()) || "",
+    invocationId: apiEventObj.invocationId || "",
+    author: apiEventObj.author,
+    actions: eventActions,
+    content: apiEventObj.content,
+    timestamp: apiEventObj.timestamp ? new Date(apiEventObj.timestamp).getTime() : Date.now(),
+    errorCode: (_c = apiEventObj.errorCode) == null ? void 0 : _c.toString(),
+    errorMessage: apiEventObj.errorMessage,
+    partial: eventMetadata["partial"],
+    turnComplete: eventMetadata["turnComplete"],
+    interrupted: eventMetadata["interrupted"],
+    branch: eventMetadata["branch"],
+    customMetadata,
+    longRunningToolIds: eventMetadata["longRunningToolIds"],
+    usageMetadata: usageMetadataData
+  };
+  if (compactionData) {
+    event.isCompacted = true;
+    event.startTime = compactionData.startTime;
+    event.endTime = compactionData.endTime;
+    event.compactedContent = compactionData.compactedContent;
+  }
+  return event;
+}
+export {
+  VertexAiSessionService,
+  isVertexAiConnectionString
+};

package/dist/esm/tools/agent_tool.js

@@ -12,6 +12,7 @@ import { InMemoryMemoryService } from "../memory/in_memory_memory_service.js";
 import { Runner } from "../runner/runner.js";
 import { InMemorySessionService } from "../sessions/in_memory_session_service.js";
 import { GoogleLLMVariant } from "../utils/variant_utils.js";
+import { State } from "../sessions/state.js";
 import { BaseTool } from "./base_tool.js";
 import { ForwardingArtifactService } from "./forwarding_artifact_service.js";
 const AGENT_TOOL_SIGNATURE_SYMBOL = Symbol.for("google.adk.agentTool");
@@ -122,9 +123,6 @@ class AgentTool extends (_b = BaseTool, _a = AGENT_TOOL_SIGNATURE_SYMBOL, _b) {
     toolContext
   }) {
     var _a2, _b2;
-    if (this.skipSummarization) {
-      toolContext.actions.skipSummarization = true;
-    }
     const { runner, content, sessionUserId, sessionId } = await this.setupRunnerAndSession({ args, toolContext });
     if ((_a2 = toolContext.abortSignal) == null ? void 0 : _a2.aborted) {
       return "";
@@ -141,7 +139,14 @@ class AgentTool extends (_b = BaseTool, _a = AGENT_TOOL_SIGNATURE_SYMBOL, _b) {
         return;
       }
       if (event.actions.stateDelta) {
-        toolContext.state.update(event.actions.stateDelta);
+        const filteredDelta = Object.fromEntries(
+          Object.entries(event.actions.stateDelta).filter(
+            ([key]) => !key.startsWith(State.TEMP_PREFIX)
+          )
+        );
+        if (Object.keys(filteredDelta).length > 0) {
+          toolContext.state.update(filteredDelta);
+        }
       }
       lastEvent = event;
     }
@@ -160,9 +165,6 @@ class AgentTool extends (_b = BaseTool, _a = AGENT_TOOL_SIGNATURE_SYMBOL, _b) {
     toolContext
   }) {
     var _a2, _b2;
-    if (this.skipSummarization) {
-      toolContext.actions.skipSummarization = true;
-    }
     const { runner, content, sessionUserId, sessionId } = await this.setupRunnerAndSession({ args, toolContext });
     if ((_a2 = toolContext.abortSignal) == null ? void 0 : _a2.aborted) {
       return;
@@ -178,7 +180,14 @@ class AgentTool extends (_b = BaseTool, _a = AGENT_TOOL_SIGNATURE_SYMBOL, _b) {
         return;
       }
       if (event.actions.stateDelta) {
-        toolContext.state.update(event.actions.stateDelta);
+        const filteredDelta = Object.fromEntries(
+          Object.entries(event.actions.stateDelta).filter(
+            ([key]) => !key.startsWith(State.TEMP_PREFIX)
+          )
+        );
+        if (Object.keys(filteredDelta).length > 0) {
+          toolContext.state.update(filteredDelta);
+        }
       }
       yield event;
     }

package/dist/esm/tools/exit_loop_tool.js

@@ -7,18 +7,27 @@ const require = topLevelCreateRequire(import.meta.url);
  */
 import { BaseTool } from "./base_tool.js";
 class ExitLoopTool extends BaseTool {
+  /** Creates an ExitLoopTool with its fixed name and description. */
   constructor() {
     super({
       name: "exit_loop",
       description: "Exits the loop.\n\nCall this function only when you are instructed to do so."
     });
   }
+  /** Returns the function declaration for this tool. */
   _getDeclaration() {
     return {
       name: this.name,
       description: this.description
     };
   }
+  /**
+   * Sets `escalate` and `skipSummarization` on the event actions, signalling
+   * the {@link LoopAgent} to stop iterating.
+   *
+   * @param request The tool request containing the current tool context.
+   * @returns An empty string response.
+   */
   async runAsync({
     toolContext
   }) {