@google/adk 1.4.0 → 1.5.0

package/dist/cjs/utils/streaming_utils.js

@@ -30,7 +30,7 @@ __export(streaming_utils_exports, {
 module.exports = __toCommonJS(streaming_utils_exports);
 var import_genai = require("@google/genai");
 var import_jsonpath_plus = require("jsonpath-plus");
-var import_functions = require("../agents/functions.js");
+var import_event = require("../events/event.js");
 var import_feature_registry = require("../features/feature_registry.js");
 var import_llm_response = require("../models/llm_response.js");
 /**
@@ -127,7 +127,7 @@ class ProgressiveStrategy {
         functionCall: {
           name: this.currentFcName,
           args: JSON.parse(JSON.stringify(this.currentFcArgs)),
-          id: (_a = this.currentFcId) != null ? _a : (0, import_functions.generateClientFunctionCallId)()
+          id: (_a = this.currentFcId) != null ? _a : (0, import_event.generateClientFunctionCallId)()
         }
       };
       if (this.currentThoughtSignature) {
@@ -172,7 +172,7 @@ class ProgressiveStrategy {
     }
     if (fc.partialArgs || fc.willContinue) {
       if (!fc.id && !this.currentFcId) {
-        fc.id = (0, import_functions.generateClientFunctionCallId)();
+        fc.id = (0, import_event.generateClientFunctionCallId)();
       }
       if (part.thoughtSignature && !this.currentThoughtSignature) {
         this.currentThoughtSignature = part.thoughtSignature;
@@ -181,7 +181,7 @@ class ProgressiveStrategy {
     } else {
       if (fc.name) {
         if (!fc.id) {
-          fc.id = (0, import_functions.generateClientFunctionCallId)();
+          fc.id = (0, import_event.generateClientFunctionCallId)();
         }
         this.flushTextBufferToSequence();
         this.partsSequence.push(part);
@@ -243,7 +243,7 @@ class NonProgressiveStrategy {
           continue;
         }
         if (part.functionCall && !part.functionCall.id) {
-          part.functionCall.id = (0, import_functions.generateClientFunctionCallId)();
+          part.functionCall.id = (0, import_event.generateClientFunctionCallId)();
         }
         nonTextParts.push(part);
       }

package/dist/cjs/version.js

@@ -32,7 +32,7 @@ module.exports = __toCommonJS(version_exports);
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-const version = "1.4.0";
+const version = "1.5.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   version

package/dist/esm/a2a/agent_to_a2a.js

@@ -16,10 +16,26 @@ import {
 import express from "express";
 import { StreamingMode } from "../agents/run_config.js";
 import { InMemorySessionService } from "../sessions/in_memory_session_service.js";
+import { logger } from "../utils/logger.js";
 import { getA2AAgentCard, resolveAgentCard } from "./agent_card.js";
 import { A2AAgentExecutor } from "./agent_executor.js";
+function resolveA2aUserBuilder(options) {
+  if (options.authentication) {
+    return options.authentication;
+  }
+  if (options.allowUnauthenticated === true) {
+    logger.warn(
+      "SECURITY WARNING: Mounting the A2A server WITHOUT authentication because `allowUnauthenticated: true` was set. The agent and all of its tools are exposed to any network-reachable caller, which can invoke them with arbitrary input and read the output. Do NOT use this outside of local, trusted development."
+    );
+    return UserBuilder.noAuthentication;
+  }
+  throw new Error(
+    "toA2a: refusing to mount the A2A server without authentication. The A2A surface lets any network-reachable caller invoke this agent and its tools with arbitrary input and read the output, so it must be authenticated. Provide `authentication` (a UserBuilder that validates the request, e.g. a bearer token or OIDC credential) or, only for local/trusted development, explicitly set `allowUnauthenticated: true`."
+  );
+}
 async function toA2a(agent, options = {}) {
   var _a, _b, _c, _d;
+  const userBuilder = resolveA2aUserBuilder(options);
   const host = (_a = options.host) != null ? _a : "localhost";
   const port = (_b = options.port) != null ? _b : 8e3;
   const protocol = (_c = options.protocol) != null ? _c : "http";
@@ -65,14 +81,14 @@ async function toA2a(agent, options = {}) {
     `${basePath}/rest`,
     restHandler({
       requestHandler,
-      userBuilder: UserBuilder.noAuthentication
+      userBuilder
     })
   );
   app.use(
     `${basePath}/jsonrpc`,
     jsonRpcHandler({
       requestHandler,
-      userBuilder: UserBuilder.noAuthentication
+      userBuilder
     })
   );
   return app;

package/dist/esm/a2a/event_converter_utils.js

@@ -58,13 +58,14 @@ function toAdkEvent(event, invocationId, agentName) {
   }
   return void 0;
 }
-function messageToAdkEvent(msg, invocationId, agentName, parentEvent) {
+function messageToAdkEvent(msg, invocationId, agentName) {
   const parts = toGenAIParts(msg.parts);
+  const content = parts.length === 0 ? void 0 : msg.role === MessageRole.USER ? createUserContent(parts) : createModelContent(parts);
   return {
-    ...createAdkEventFromMetadata(parentEvent || msg),
+    ...createAdkEventFromMetadata(msg),
     invocationId,
     author: msg.role === MessageRole.USER ? MessageRole.USER : agentName,
-    content: msg.role === MessageRole.USER ? createUserContent(parts) : createModelContent(parts),
+    content,
     turnComplete: true,
     partial: false
   };
@@ -110,6 +111,9 @@ function taskStatusUpdateToAdkEvent(a2aEvent, invocationId, agentName) {
     return void 0;
   }
   const parts = toGenAIParts(msg.parts);
+  if (parts.length === 0) {
+    return void 0;
+  }
   return {
     ...createAdkEventFromMetadata(a2aEvent),
     invocationId,
@@ -140,7 +144,7 @@ function taskToAdkEvent(a2aTask, invocationId, agentName) {
   }
   const isTerminal = isTerminalTaskStatusUpdateEvent(a2aTask) || isInputRequiredTaskStatusUpdateEvent(a2aTask);
   const isFailed = isFailedTaskStatusUpdateEvent(a2aTask);
-  if (parts.length === 0 && !isTerminal) {
+  if (parts.length === 0 && !isFailed) {
     return void 0;
   }
   return {

package/dist/esm/a2a/metadata_converter_utils.js

@@ -56,7 +56,7 @@ function getA2AEventMetadata(adkEvent, {
     [A2AMetadataKeys.INVOCATION_ID]: adkEvent.invocationId,
     [A2AMetadataKeys.AUTHOR]: adkEvent.author,
     [A2AMetadataKeys.BRANCH]: adkEvent.branch,
-    [A2AMetadataKeys.ERROR_CODE]: adkEvent.errorMessage,
+    [A2AMetadataKeys.ERROR_CODE]: adkEvent.errorCode,
     [A2AMetadataKeys.ERROR_MESSAGE]: adkEvent.errorMessage,
     [A2AMetadataKeys.CITATION_METADATA]: adkEvent.citationMetadata,
     [A2AMetadataKeys.GROUNDING_METADATA]: adkEvent.groundingMetadata,

package/dist/esm/agents/base_agent.js

@@ -26,6 +26,7 @@ class BaseAgent {
      * A unique symbol to identify ADK agent classes.
      */
     this[_a] = true;
+    this.config = { ...config };
     this.name = validateAgentName(config.name);
     this.description = config.description;
     this.parentAgent = config.parentAgent;
@@ -43,6 +44,44 @@ class BaseAgent {
   get rootAgent() {
     return getRootAgent(this);
   }
+  /**
+   * Creates a copy of this agent with the given config fields overridden.
+   *
+   * Mirrors adk-python's `BaseAgent.clone(update=...)`. The clone is a detached
+   * root: its `parentAgent` is always `undefined`. Sub-agents are recursively
+   * cloned (and re-parented to the clone) unless `subAgents` is overridden.
+   * Rebuilding via the concrete constructor re-derives all state, so a cloned
+   * `LlmAgent` gets a fresh `requestProcessors` array rather than sharing the
+   * original's. See google/adk-js#534.
+   *
+   * @param overrides Config fields to override on the clone. Overriding
+   *     `parentAgent` is rejected, matching adk-python.
+   * @returns A new detached agent instance of the same concrete class.
+   */
+  clone(overrides) {
+    if (overrides && "parentAgent" in overrides) {
+      throw new Error(
+        "Cannot update `parentAgent` field in clone. Parent agent is set only when the parent agent is instantiated with the sub-agents."
+      );
+    }
+    const merged = { ...this.config, ...overrides };
+    merged.parentAgent = void 0;
+    const mergedRecord = merged;
+    for (const key of Object.keys(mergedRecord)) {
+      if (key === "subAgents" || overrides && key in overrides) {
+        continue;
+      }
+      const value = mergedRecord[key];
+      if (Array.isArray(value)) {
+        mergedRecord[key] = value.slice();
+      }
+    }
+    if (!overrides || !("subAgents" in overrides)) {
+      merged.subAgents = this.subAgents.map((subAgent) => subAgent.clone());
+    }
+    const ctor = this.constructor;
+    return new ctor(merged);
+  }
   /**
    * Entry method to run an agent via text-based conversation.
    *

package/dist/esm/agents/functions.js

@@ -9,11 +9,11 @@ import { createUserContent } from "@google/genai";
 import { isEmpty } from "lodash-es";
 import {
   createEvent,
+  generateClientFunctionCallId,
   getFunctionCalls,
   getFunctionResponses
 } from "../events/event.js";
 import { mergeEventActions } from "../events/event_actions.js";
-import { randomUUID } from "../utils/env_aware_utils.js";
 import { logger } from "../utils/logger.js";
 import { Context } from "./context.js";
 import {
@@ -21,7 +21,11 @@ import {
   tracer,
   traceToolCall
 } from "../telemetry/tracing.js";
-const AF_FUNCTION_CALL_ID_PREFIX = "adk-";
+import {
+  AF_FUNCTION_CALL_ID_PREFIX,
+  generateClientFunctionCallId as generateClientFunctionCallId2,
+  populateClientFunctionCallId
+} from "../events/event.js";
 const REQUEST_EUC_FUNCTION_CALL_NAME = "adk_request_credential";
 const REQUEST_CONFIRMATION_FUNCTION_CALL_NAME = "adk_request_confirmation";
 const functionsExportedForTestingOnly = {
@@ -29,20 +33,6 @@ const functionsExportedForTestingOnly = {
   generateAuthEvent,
   generateRequestConfirmationEvent
 };
-function generateClientFunctionCallId() {
-  return `${AF_FUNCTION_CALL_ID_PREFIX}${randomUUID()}`;
-}
-function populateClientFunctionCallId(modelResponseEvent) {
-  const functionCalls = getFunctionCalls(modelResponseEvent);
-  if (!functionCalls) {
-    return;
-  }
-  for (const functionCall of functionCalls) {
-    if (!functionCall.id) {
-      functionCall.id = generateClientFunctionCallId();
-    }
-  }
-}
 function getLongRunningFunctionCalls(functionCalls, toolsDict) {
   const longRunningToolIds = /* @__PURE__ */ new Set();
   for (const functionCall of functionCalls) {
@@ -420,7 +410,7 @@ export {
   findMatchingFunctionCall,
   functionsExportedForTestingOnly,
   generateAuthEvent,
-  generateClientFunctionCallId,
+  generateClientFunctionCallId2 as generateClientFunctionCallId,
   generateRequestConfirmationEvent,
   getLongRunningFunctionCalls,
   handleFunctionCallList,

package/dist/esm/agents/llm_agent.js

@@ -13,7 +13,8 @@ import {
   createNewEventId,
   getFunctionCalls,
   getFunctionResponses,
-  isFinalResponse
+  isFinalResponse,
+  populateClientFunctionCallId
 } from "../events/event.js";
 import { isBaseLlm } from "../models/base_llm.js";
 import { LLMRegistry } from "../models/registry.js";
@@ -31,8 +32,7 @@ import {
   generateAuthEvent,
   generateRequestConfirmationEvent,
   getLongRunningFunctionCalls,
-  handleFunctionCallsAsync,
-  populateClientFunctionCallId
+  handleFunctionCallsAsync
 } from "./functions.js";
 import { AUTH_PREPROCESSOR } from "../auth/auth_preprocessor.js";
 import { AGENT_TRANSFER_LLM_REQUEST_PROCESSOR } from "./processors/agent_transfer_llm_request_processor.js";
@@ -183,6 +183,7 @@ class LlmAgent extends (_b = BaseAgent, _a = LLM_AGENT_SIGNATURE_SYMBOL, _b) {
    * This method is only for use by Agent Development Kit.
    * @param context The context to retrieve the session state.
    * @returns The resolved globalInstruction field.
+   * @deprecated Use GlobalInstructionPlugin instead.
    */
   async canonicalGlobalInstruction(context2) {
     if (typeof this.globalInstruction === "string") {

package/dist/esm/agents/loop_agent.js

@@ -44,9 +44,21 @@ class LoopAgent extends (_b = BaseAgent, _a = LOOP_AGENT_SIGNATURE_SYMBOL, _b) {
     }
     return;
   }
-  // eslint-disable-next-line require-yield
-  async *runLiveImpl(_context) {
-    throw new Error("This is not supported yet for LoopAgent.");
+  async *runLiveImpl(context) {
+    var _a2, _b2;
+    for (let iteration = 0; iteration < this.maxIterations; iteration++) {
+      for (const subAgent of this.subAgents) {
+        for await (const event of subAgent.runLive(context)) {
+          if ((_a2 = context.abortSignal) == null ? void 0 : _a2.aborted) {
+            return;
+          }
+          yield event;
+          if ((_b2 = event.actions) == null ? void 0 : _b2.escalate) {
+            return;
+          }
+        }
+      }
+    }
   }
 }
 export {

package/dist/esm/agents/processors/content_processor_utils.js

@@ -15,6 +15,7 @@ import {
   getFunctionCalls,
   getFunctionResponses
 } from "../../events/event.js";
+import { isSegmentPrefix } from "../../utils/branch_trie.js";
 import {
   AF_FUNCTION_CALL_ID_PREFIX,
   REQUEST_CONFIRMATION_FUNCTION_CALL_NAME,
@@ -42,7 +43,7 @@ function getContents(events, agentName, currentBranch) {
     if (!((_a = event.content) == null ? void 0 : _a.role) || ((_c = (_b = event.content.parts) == null ? void 0 : _b[0]) == null ? void 0 : _c.text) === "") {
       continue;
     }
-    if (currentBranch && event.branch && !currentBranch.startsWith(event.branch)) {
+    if (currentBranch && event.branch && !isSegmentPrefix(currentBranch, event.branch)) {
       continue;
     }
     if (isAuthEvent(event)) {

package/dist/esm/agents/routed_agent.js

@@ -38,6 +38,29 @@ let RoutedAgent = class extends (_b = BaseAgent, _a = ROUTED_AGENT_SIGNATURE_SYM
     }
     this.router = config.router;
   }
+  /**
+   * Creates a detached copy of this routed agent.
+   *
+   * The inherited {@link BaseAgent.clone} only deep-clones `subAgents`, but a
+   * `RoutedAgent` derives its routing targets from `config.agents`. Rebuilding
+   * through the base clone alone would re-read the already-parented original
+   * agents and throw "already has a parent agent". This override deep-clones the
+   * routing targets (unless the caller overrides `agents`) so the rebuilt
+   * constructor re-parents fresh, detached copies. The array-vs-record shape
+   * and, for records, the keys are preserved so the router keeps selecting the
+   * same targets.
+   *
+   * @param overrides Config fields to override on the clone. Overriding
+   *     `parentAgent` is rejected by the base implementation.
+   * @returns A new detached `RoutedAgent` of the same concrete class.
+   */
+  clone(overrides) {
+    const nextOverrides = { ...overrides };
+    if (!("agents" in nextOverrides)) {
+      nextOverrides.agents = cloneRoutingTargets(this.config.agents);
+    }
+    return super.clone(nextOverrides);
+  }
   /**
    * Runs the selected agent via text-based conversation.
    */
@@ -64,6 +87,14 @@ let RoutedAgent = class extends (_b = BaseAgent, _a = ROUTED_AGENT_SIGNATURE_SYM
 RoutedAgent = __decorateClass([
   experimental
 ], RoutedAgent);
+function cloneRoutingTargets(agents) {
+  if (Array.isArray(agents)) {
+    return agents.map((agent) => agent.clone());
+  }
+  return Object.fromEntries(
+    Object.entries(agents).map(([key, agent]) => [key, agent.clone()])
+  );
+}
 export {
   RoutedAgent,
   isRoutedAgent

package/dist/esm/agents/run_config.js

@@ -13,14 +13,15 @@ var StreamingMode = /* @__PURE__ */ ((StreamingMode2) => {
   return StreamingMode2;
 })(StreamingMode || {});
 function createRunConfig(params = {}) {
+  var _a;
   return {
     saveInputBlobsAsArtifacts: false,
     supportCfc: false,
     enableAffectiveDialog: false,
     streamingMode: "none" /* NONE */,
-    maxLlmCalls: validateMaxLlmCalls(params.maxLlmCalls || 500),
     pauseOnToolCalls: false,
-    ...params
+    ...params,
+    maxLlmCalls: validateMaxLlmCalls((_a = params.maxLlmCalls) != null ? _a : 500)
   };
 }
 function validateMaxLlmCalls(value) {

package/dist/esm/artifacts/in_memory_artifact_service.js

@@ -5,6 +5,7 @@ const require = topLevelCreateRequire(import.meta.url);
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import { logger } from "../utils/logger.js";
 function isInMemoryConnectionString(uri) {
   return uri === "memory://";
 }
@@ -56,6 +57,12 @@ class InMemoryArtifactService {
     if (version === void 0) {
       version = versions.length - 1;
     }
+    if (!versions[version]) {
+      logger.warn(
+        `[InMemoryArtifactService] loadArtifact: Artifact ${filename} version ${version} not found`
+      );
+      return Promise.resolve(void 0);
+    }
     return Promise.resolve(versions[version].part);
   }
   listArtifactKeys({

package/dist/esm/common.js

@@ -56,17 +56,22 @@ import {
   FileContentEncoding
 } from "./code_executors/code_execution_utils.js";
 import { AgentControlledContextCompactor } from "./context/agent_controlled_context_compactor.js";
+import { AnchoredContextCompactor } from "./context/anchored_context_compactor.js";
 import { LlmSummarizer } from "./context/summarizers/llm_summarizer.js";
 import { TokenBasedContextCompactor } from "./context/token_based_context_compactor.js";
 import { TrajectoryThoughtPruningCompactor } from "./context/trajectory_thought_pruning_compactor.js";
 import { TruncatingContextCompactor } from "./context/truncating_context_compactor.js";
-import { isCompactedEvent } from "./events/compacted_event.js";
+import { isCompactedEvent, isScratchpadEvent } from "./events/compacted_event.js";
 import {
   createEvent,
+  generateClientFunctionCallId,
   getFunctionCalls,
   getFunctionResponses,
+  hasThoughts,
   hasTrailingCodeExecutionResult,
   isFinalResponse,
+  populateClientFunctionCallId,
+  pruneThoughts,
   stringifyContent
 } from "./events/event.js";
 import { createEventActions } from "./events/event_actions.js";
@@ -83,6 +88,7 @@ import { Gemini, geminiInitParams } from "./models/google_llm.js";
 import { LLMRegistry } from "./models/registry.js";
 import { RoutedLlm } from "./models/routed_llm.js";
 import { BasePlugin, ContextCompactionTrigger } from "./plugins/base_plugin.js";
+import { GlobalInstructionPlugin } from "./plugins/global_instruction_plugin.js";
 import { LoggingPlugin } from "./plugins/logging_plugin.js";
 import { PluginManager } from "./plugins/plugin_manager.js";
 import {
@@ -108,6 +114,11 @@ 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 { ConsolidateContextTool } from "./tools/consolidate_context_tool.js";
+import {
+  ENTERPRISE_WEB_SEARCH,
+  EnterpriseWebSearchTool
+} from "./tools/enterprise_web_search_tool.js";
+import { ExampleTool } from "./tools/example_tool.js";
 import { EXIT_LOOP, ExitLoopTool } from "./tools/exit_loop_tool.js";
 import { FunctionTool, isFunctionTool } from "./tools/function_tool.js";
 import {
@@ -120,6 +131,7 @@ import {
   LoadArtifactsTool
 } from "./tools/load_artifacts_tool.js";
 import { LOAD_MEMORY, LoadMemoryTool } from "./tools/load_memory_tool.js";
+import { LOAD_WEB_PAGE, loadWebPage } from "./tools/load_web_page.js";
 import { LongRunningFunctionTool } from "./tools/long_running_tool.js";
 import {
   PRELOAD_MEMORY,
@@ -174,6 +186,7 @@ export {
   AgentControlledContextCompactor,
   AgentTool,
   AgentTransferLlmRequestProcessor,
+  AnchoredContextCompactor,
   ApigeeLlm,
   AuthCredentialTypes,
   AuthHandler,
@@ -199,8 +212,11 @@ export {
   ContextCompactorRequestProcessor,
   CredentialExchangeError,
   CredentialRefresherRegistry,
+  ENTERPRISE_WEB_SEARCH,
   EXIT_LOOP,
+  EnterpriseWebSearchTool,
   EventType,
+  ExampleTool,
   ExitLoopTool,
   FileContentEncoding,
   FunctionTool,
@@ -208,6 +224,7 @@ export {
   GOOGLE_MAPS_GROUNDING,
   GOOGLE_SEARCH,
   Gemini,
+  GlobalInstructionPlugin,
   GoogleLLMVariant,
   GoogleMapsGroundingTool,
   GoogleSearchTool,
@@ -223,6 +240,7 @@ export {
   LLMRegistry,
   LOAD_ARTIFACTS,
   LOAD_MEMORY,
+  LOAD_WEB_PAGE,
   ListSkillsTool,
   LiveRequestQueue,
   LlmAgent2 as LlmAgent,
@@ -281,11 +299,13 @@ export {
   findMatchingFunctionCall,
   functionsExportedForTestingOnly,
   geminiInitParams,
+  generateClientFunctionCallId,
   getAskUserConfirmationFunctionCalls,
   getClientLabels,
   getFunctionCalls,
   getFunctionResponses,
   getLogger,
+  hasThoughts,
   hasTrailingCodeExecutionResult,
   isAgentTool,
   isBaseAgent,
@@ -304,10 +324,14 @@ export {
   isRoutableLlmAgent,
   isRoutedAgent,
   isRunner,
+  isScratchpadEvent,
   isSequentialAgent,
   loadAllSkillsInDir,
   loadSkillFromDir,
   loadSkillFromZipBuffer,
+  loadWebPage,
+  populateClientFunctionCallId,
+  pruneThoughts,
   runWithClientLabel,
   setLogLevel,
   setLogger,

package/dist/esm/context/anchored_context_compactor.js

@@ -0,0 +1,99 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { isScratchpadEvent } from "../events/compacted_event.js";
+import { getEventTokens } from "../events/event.js";
+import { calculateRetainStartIndex } from "./compaction_utils.js";
+class AnchoredContextCompactor {
+  constructor(options) {
+    this.tokenThreshold = options.tokenThreshold;
+    this.eventRetentionSize = options.eventRetentionSize;
+    this.summarizer = options.summarizer;
+  }
+  getActiveEvents(events) {
+    let latestScratchpad = void 0;
+    for (let i = events.length - 1; i >= 0; i--) {
+      const e = events[i];
+      if (isScratchpadEvent(e)) {
+        latestScratchpad = e;
+        break;
+      }
+    }
+    if (!latestScratchpad) {
+      return events;
+    }
+    const activeRawEvents = events.filter(
+      (e) => e.timestamp > latestScratchpad.endTime && !isScratchpadEvent(e)
+    );
+    return [latestScratchpad, ...activeRawEvents];
+  }
+  shouldCompact(invocationContext) {
+    const events = invocationContext.session.events;
+    const activeEvents = this.getActiveEvents(events);
+    const hasScratchpad = activeEvents.length > 0 && isScratchpadEvent(activeEvents[0]);
+    const rawEvents = hasScratchpad ? activeEvents.slice(1) : activeEvents;
+    if (rawEvents.length <= this.eventRetentionSize) {
+      return false;
+    }
+    const retainStartIndex = calculateRetainStartIndex(
+      rawEvents,
+      this.eventRetentionSize
+    );
+    if (retainStartIndex === 0) {
+      return false;
+    }
+    const totalTokens = activeEvents.reduce(
+      (sum, event) => sum + getEventTokens(event),
+      0
+    );
+    return totalTokens > this.tokenThreshold;
+  }
+  async compact(invocationContext) {
+    const events = invocationContext.session.events;
+    const activeEvents = this.getActiveEvents(events);
+    const hasScratchpad = activeEvents.length > 0 && isScratchpadEvent(activeEvents[0]);
+    const rawEvents = hasScratchpad ? activeEvents.slice(1) : activeEvents;
+    if (rawEvents.length <= this.eventRetentionSize) {
+      return;
+    }
+    const retainStartIndex = calculateRetainStartIndex(
+      rawEvents,
+      this.eventRetentionSize
+    );
+    if (retainStartIndex === 0) {
+      return;
+    }
+    const rawEventsToCompact = rawEvents.slice(0, retainStartIndex);
+    let scratchpadEvent;
+    if (hasScratchpad) {
+      const existingScratchpad = activeEvents[0];
+      scratchpadEvent = await this.summarizer.summarize([
+        existingScratchpad,
+        ...rawEventsToCompact
+      ]);
+    } else {
+      scratchpadEvent = await this.summarizer.summarize(rawEventsToCompact);
+    }
+    const updatedScratchpad = {
+      ...scratchpadEvent,
+      isScratchpad: true,
+      author: "system"
+    };
+    const inactiveEvents = events.slice(0, events.indexOf(activeEvents[0]));
+    const retainedRawEvents = rawEvents.slice(retainStartIndex);
+    const newEventsList = [
+      ...inactiveEvents,
+      updatedScratchpad,
+      ...retainedRawEvents
+    ];
+    events.length = 0;
+    events.push(...newEventsList);
+  }
+}
+export {
+  AnchoredContextCompactor
+};

package/dist/esm/context/compaction_utils.js

@@ -0,0 +1,27 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import {
+  getFunctionCalls,
+  getFunctionResponses
+} from "../events/event.js";
+function calculateRetainStartIndex(rawEvents, eventRetentionSize) {
+  let retainStartIndex = Math.max(0, rawEvents.length - eventRetentionSize);
+  while (retainStartIndex > 0) {
+    const eventToRetain = rawEvents[retainStartIndex];
+    const previousEvent = rawEvents[retainStartIndex - 1];
+    if (getFunctionResponses(eventToRetain).length > 0 && getFunctionCalls(previousEvent).length > 0) {
+      retainStartIndex--;
+    } else {
+      break;
+    }
+  }
+  return retainStartIndex;
+}
+export {
+  calculateRetainStartIndex
+};