@google/adk 0.4.0 → 0.6.0

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

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { appendInstructions } from "../../models/llm_request.js";
+import { injectSessionState } from "../instructions.js";
+import { isLlmAgent } from "../llm_agent.js";
+import { ReadonlyContext } from "../readonly_context.js";
+import { BaseLlmRequestProcessor } from "./base_llm_processor.js";
+class InstructionsLlmRequestProcessor extends BaseLlmRequestProcessor {
+  /**
+   * Handles instructions and global instructions for LLM flow.
+   */
+  // eslint-disable-next-line require-yield
+  async *runAsync(invocationContext, llmRequest) {
+    const agent = invocationContext.agent;
+    if (!isLlmAgent(agent)) {
+      return;
+    }
+    const rootAgent = agent.rootAgent;
+    if (isLlmAgent(rootAgent) && rootAgent.globalInstruction) {
+      const { instruction, requireStateInjection } = await rootAgent.canonicalGlobalInstruction(
+        new ReadonlyContext(invocationContext)
+      );
+      let instructionWithState = instruction;
+      if (requireStateInjection) {
+        instructionWithState = await injectSessionState(
+          instruction,
+          new ReadonlyContext(invocationContext)
+        );
+      }
+      appendInstructions(llmRequest, [instructionWithState]);
+    }
+    if (agent.instruction) {
+      const { instruction, requireStateInjection } = await agent.canonicalInstruction(
+        new ReadonlyContext(invocationContext)
+      );
+      let instructionWithState = instruction;
+      if (requireStateInjection) {
+        instructionWithState = await injectSessionState(
+          instruction,
+          new ReadonlyContext(invocationContext)
+        );
+      }
+      appendInstructions(llmRequest, [instructionWithState]);
+    }
+  }
+}
+const INSTRUCTIONS_LLM_REQUEST_PROCESSOR = new InstructionsLlmRequestProcessor();
+export {
+  INSTRUCTIONS_LLM_REQUEST_PROCESSOR,
+  InstructionsLlmRequestProcessor
+};

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

@@ -0,0 +1,140 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import {
+  getFunctionCalls,
+  getFunctionResponses
+} from "../../events/event.js";
+import { ToolConfirmation } from "../../tools/tool_confirmation.js";
+import {
+  REQUEST_CONFIRMATION_FUNCTION_CALL_NAME,
+  handleFunctionCallList
+} from "../functions.js";
+import { isLlmAgent } from "../llm_agent.js";
+import { ReadonlyContext } from "../readonly_context.js";
+import { BaseLlmRequestProcessor } from "./base_llm_processor.js";
+class RequestConfirmationLlmRequestProcessor extends BaseLlmRequestProcessor {
+  /** Handles tool confirmation information to build the LLM request. */
+  async *runAsync(invocationContext) {
+    const agent = invocationContext.agent;
+    if (!isLlmAgent(agent)) {
+      return;
+    }
+    const events = invocationContext.session.events;
+    if (!events || events.length === 0) {
+      return;
+    }
+    const requestConfirmationFunctionResponses = {};
+    let confirmationEventIndex = -1;
+    for (let i = events.length - 1; i >= 0; i--) {
+      const event = events[i];
+      if (event.author !== "user") {
+        continue;
+      }
+      const responses = getFunctionResponses(event);
+      if (!responses) {
+        continue;
+      }
+      let foundConfirmation = false;
+      for (const functionResponse of responses) {
+        if (functionResponse.name !== REQUEST_CONFIRMATION_FUNCTION_CALL_NAME) {
+          continue;
+        }
+        foundConfirmation = true;
+        let toolConfirmation = null;
+        if (functionResponse.response && Object.keys(functionResponse.response).length === 1 && "response" in functionResponse.response) {
+          toolConfirmation = JSON.parse(
+            functionResponse.response["response"]
+          );
+        } else if (functionResponse.response) {
+          toolConfirmation = new ToolConfirmation({
+            hint: functionResponse.response["hint"],
+            payload: functionResponse.response["payload"],
+            confirmed: functionResponse.response["confirmed"]
+          });
+        }
+        if (functionResponse.id && toolConfirmation) {
+          requestConfirmationFunctionResponses[functionResponse.id] = toolConfirmation;
+        }
+      }
+      if (foundConfirmation) {
+        confirmationEventIndex = i;
+        break;
+      }
+    }
+    if (Object.keys(requestConfirmationFunctionResponses).length === 0) {
+      return;
+    }
+    for (let i = confirmationEventIndex - 1; i >= 0; i--) {
+      const event = events[i];
+      const functionCalls = getFunctionCalls(event);
+      if (!functionCalls) {
+        continue;
+      }
+      const toolsToResumeWithConfirmation = {};
+      const toolsToResumeWithArgs = {};
+      for (const functionCall of functionCalls) {
+        if (!functionCall.id || !(functionCall.id in requestConfirmationFunctionResponses)) {
+          continue;
+        }
+        const args = functionCall.args;
+        if (!args || !("originalFunctionCall" in args)) {
+          continue;
+        }
+        const originalFunctionCall = args["originalFunctionCall"];
+        if (originalFunctionCall.id) {
+          toolsToResumeWithConfirmation[originalFunctionCall.id] = requestConfirmationFunctionResponses[functionCall.id];
+          toolsToResumeWithArgs[originalFunctionCall.id] = originalFunctionCall;
+        }
+      }
+      if (Object.keys(toolsToResumeWithConfirmation).length === 0) {
+        continue;
+      }
+      for (let j = events.length - 1; j > confirmationEventIndex; j--) {
+        const eventToCheck = events[j];
+        const functionResponses = getFunctionResponses(eventToCheck);
+        if (!functionResponses) {
+          continue;
+        }
+        for (const fr of functionResponses) {
+          if (fr.id && fr.id in toolsToResumeWithConfirmation) {
+            delete toolsToResumeWithConfirmation[fr.id];
+            delete toolsToResumeWithArgs[fr.id];
+          }
+        }
+        if (Object.keys(toolsToResumeWithConfirmation).length === 0) {
+          break;
+        }
+      }
+      if (Object.keys(toolsToResumeWithConfirmation).length === 0) {
+        continue;
+      }
+      const toolsList = await agent.canonicalTools(
+        new ReadonlyContext(invocationContext)
+      );
+      const toolsDict = Object.fromEntries(
+        toolsList.map((tool) => [tool.name, tool])
+      );
+      const functionResponseEvent = await handleFunctionCallList({
+        invocationContext,
+        functionCalls: Object.values(toolsToResumeWithArgs),
+        toolsDict,
+        beforeToolCallbacks: agent.canonicalBeforeToolCallbacks,
+        afterToolCallbacks: agent.canonicalAfterToolCallbacks,
+        filters: new Set(Object.keys(toolsToResumeWithConfirmation)),
+        toolConfirmationDict: toolsToResumeWithConfirmation
+      });
+      if (functionResponseEvent) {
+        yield functionResponseEvent;
+      }
+      return;
+    }
+  }
+}
+const REQUEST_CONFIRMATION_LLM_REQUEST_PROCESSOR = new RequestConfirmationLlmRequestProcessor();
+export {
+  REQUEST_CONFIRMATION_LLM_REQUEST_PROCESSOR,
+  RequestConfirmationLlmRequestProcessor
+};

package/dist/esm/artifacts/file_artifact_service.js

@@ -307,8 +307,28 @@ class FileArtifactService {
     }
   }
 }
+const SAFE_SEGMENT_RE = /^[a-zA-Z0-9_@-][a-zA-Z0-9_.@-]{0,255}$/;
+function assertSafeSegment(value, label) {
+  if (!value || !SAFE_SEGMENT_RE.test(value)) {
+    throw new Error(
+      `[FileArtifactService] Invalid ${label}: value contains disallowed characters.`
+    );
+  }
+}
+function assertInsideRoot(resolvedPath, rootDir, label) {
+  const root = path.resolve(rootDir);
+  const resolved = path.resolve(resolvedPath);
+  if (!resolved.startsWith(root + path.sep) && resolved !== root) {
+    throw new Error(
+      `[FileArtifactService] ${label} escapes storage root. Resolved: ${resolved}, Root: ${root}`
+    );
+  }
+}
 function getUserRoot(rootDir, userId) {
-  return path.join(rootDir, "users", userId);
+  assertSafeSegment(userId, "userId");
+  const result = path.join(rootDir, "users", userId);
+  assertInsideRoot(result, rootDir, "userRoot");
+  return result;
 }
 function isUserScoped(sessionId, filename) {
   return !sessionId || filename.startsWith(USER_NAMESPACE_PREFIX);
@@ -317,7 +337,10 @@ function getUserArtifactsDir(userRoot) {
   return path.join(userRoot, "artifacts");
 }
 function getSessionArtifactsDir(baseRoot, sessionId) {
-  return path.join(baseRoot, "sessions", sessionId, "artifacts");
+  assertSafeSegment(sessionId, "sessionId");
+  const result = path.join(baseRoot, "sessions", sessionId, "artifacts");
+  assertInsideRoot(result, baseRoot, "sessionArtifactsDir");
+  return result;
 }
 function getVersionsDir(artifactDir) {
   return path.join(artifactDir, "versions");
@@ -447,5 +470,9 @@ function asPosixPath(p) {
   return p.split(path.sep).join("/");
 }
 export {
-  FileArtifactService
+  FileArtifactService,
+  assertInsideRoot,
+  assertSafeSegment,
+  getSessionArtifactsDir,
+  getUserRoot
 };

package/dist/esm/common.js

@@ -5,17 +5,22 @@
  */
 import { ActiveStreamingTool } from "./agents/active_streaming_tool.js";
 import { BaseAgent, isBaseAgent } from "./agents/base_agent.js";
-import {
-  BaseLlmRequestProcessor,
-  BaseLlmResponseProcessor
-} from "./agents/base_llm_processor.js";
-import { CallbackContext } from "./agents/callback_context.js";
+import { Context } from "./agents/context.js";
 import { functionsExportedForTestingOnly } from "./agents/functions.js";
 import { InvocationContext } from "./agents/invocation_context.js";
 import { LiveRequestQueue } from "./agents/live_request_queue.js";
 import { LlmAgent, isLlmAgent } from "./agents/llm_agent.js";
 import { LoopAgent, isLoopAgent } from "./agents/loop_agent.js";
 import { ParallelAgent, isParallelAgent } from "./agents/parallel_agent.js";
+import {
+  BaseLlmRequestProcessor,
+  BaseLlmResponseProcessor
+} from "./agents/processors/base_llm_processor.js";
+import {
+  CONTENT_REQUEST_PROCESSOR,
+  ContentRequestProcessor
+} from "./agents/processors/content_request_processor.js";
+import { ContextCompactorRequestProcessor } from "./agents/processors/context_compactor_request_processor.js";
 import { ReadonlyContext } from "./agents/readonly_context.js";
 import { StreamingMode } from "./agents/run_config.js";
 import { SequentialAgent, isSequentialAgent } from "./agents/sequential_agent.js";
@@ -23,6 +28,10 @@ import { InMemoryArtifactService } from "./artifacts/in_memory_artifact_service.
 import { AuthCredentialTypes } from "./auth/auth_credential.js";
 import { BaseCodeExecutor } from "./code_executors/base_code_executor.js";
 import { BuiltInCodeExecutor } from "./code_executors/built_in_code_executor.js";
+import { LlmSummarizer } from "./context/summarizers/llm_summarizer.js";
+import { TokenBasedContextCompactor } from "./context/token_based_context_compactor.js";
+import { TruncatingContextCompactor } from "./context/truncating_context_compactor.js";
+import { isCompactedEvent } from "./events/compacted_event.js";
 import {
   createEvent,
   getFunctionCalls,
@@ -53,19 +62,28 @@ import {
   getAskUserConfirmationFunctionCalls
 } from "./plugins/security_plugin.js";
 import { InMemoryRunner } from "./runner/in_memory_runner.js";
-import { Runner } from "./runner/runner.js";
+import { Runner, isRunner } from "./runner/runner.js";
 import { BaseSessionService } from "./sessions/base_session_service.js";
 import { InMemorySessionService } from "./sessions/in_memory_session_service.js";
 import { createSession } from "./sessions/session.js";
 import { State } from "./sessions/state.js";
 import { AgentTool, isAgentTool } from "./tools/agent_tool.js";
 import { BaseTool, isBaseTool } from "./tools/base_tool.js";
-import { BaseToolset } from "./tools/base_toolset.js";
+import { BaseToolset, isBaseToolset } from "./tools/base_toolset.js";
+import { EXIT_LOOP, ExitLoopTool } from "./tools/exit_loop_tool.js";
 import { FunctionTool, isFunctionTool } from "./tools/function_tool.js";
 import { GOOGLE_SEARCH, GoogleSearchTool } from "./tools/google_search_tool.js";
+import {
+  LOAD_ARTIFACTS,
+  LoadArtifactsTool
+} from "./tools/load_artifacts_tool.js";
+import { LOAD_MEMORY, LoadMemoryTool } from "./tools/load_memory_tool.js";
 import { LongRunningFunctionTool } from "./tools/long_running_tool.js";
+import {
+  PRELOAD_MEMORY,
+  PreloadMemoryTool
+} from "./tools/preload_memory_tool.js";
 import { ToolConfirmation } from "./tools/tool_confirmation.js";
-import { ToolContext } from "./tools/tool_context.js";
 import { LogLevel, getLogger, setLogLevel, setLogger } from "./utils/logger.js";
 import { isGemini2OrAbove } from "./utils/model_name.js";
 import { zodObjectToSchema } from "./utils/simple_zod_to_json.js";
@@ -91,8 +109,13 @@ export {
   BaseTool,
   BaseToolset,
   BuiltInCodeExecutor,
-  CallbackContext,
+  CONTENT_REQUEST_PROCESSOR,
+  ContentRequestProcessor,
+  Context,
+  ContextCompactorRequestProcessor,
+  EXIT_LOOP,
   EventType,
+  ExitLoopTool,
   FunctionTool,
   GOOGLE_SEARCH,
   Gemini,
@@ -105,15 +128,22 @@ export {
   InMemorySessionService,
   InvocationContext,
   LLMRegistry,
+  LOAD_ARTIFACTS,
+  LOAD_MEMORY,
   LiveRequestQueue,
   LlmAgent,
+  LlmSummarizer,
+  LoadArtifactsTool,
+  LoadMemoryTool,
   LogLevel,
   LoggingPlugin,
   LongRunningFunctionTool,
   LoopAgent,
+  PRELOAD_MEMORY,
   ParallelAgent,
   PluginManager,
   PolicyOutcome,
+  PreloadMemoryTool,
   REQUEST_CONFIRMATION_FUNCTION_CALL_NAME,
   ReadonlyContext,
   Runner,
@@ -121,8 +151,9 @@ export {
   SequentialAgent,
   State,
   StreamingMode,
+  TokenBasedContextCompactor,
   ToolConfirmation,
-  ToolContext,
+  TruncatingContextCompactor,
   createEvent,
   createEventActions,
   createSession,
@@ -138,12 +169,15 @@ export {
   isBaseExampleProvider,
   isBaseLlm,
   isBaseTool,
+  isBaseToolset,
+  isCompactedEvent,
   isFinalResponse,
   isFunctionTool,
   isGemini2OrAbove,
   isLlmAgent,
   isLoopAgent,
   isParallelAgent,
+  isRunner,
   isSequentialAgent,
   setLogLevel,
   setLogger,

package/dist/esm/context/base_context_compactor.js

@@ -0,0 +1,5 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */

package/dist/esm/context/summarizers/base_summarizer.js

@@ -0,0 +1,5 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */

package/dist/esm/context/summarizers/llm_summarizer.js

@@ -0,0 +1,65 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import {
+  createCompactedEvent
+} from "../../events/compacted_event.js";
+import { stringifyContent } from "../../events/event.js";
+const DEFAULT_PROMPT = "The following is a conversation history between a user and an AI agent. Please summarize the conversation, focusing on key information and decisions made, as well as any unresolved questions or tasks. The summary should be concise and capture the essence of the interaction.";
+class LlmSummarizer {
+  constructor(options) {
+    this.llm = options.llm;
+    this.prompt = options.prompt || DEFAULT_PROMPT;
+  }
+  async summarize(events) {
+    var _a, _b, _c, _d, _e, _f;
+    if (events.length === 0) {
+      throw new Error("Cannot summarize an empty list of events.");
+    }
+    const startTime = events[0].timestamp;
+    const endTime = events[events.length - 1].timestamp;
+    let formattedEvents = "";
+    for (let i = 0; i < events.length; i++) {
+      formattedEvents += `[Event ${i + 1} - Author: ${events[i].author}]
+`;
+      formattedEvents += `${stringifyContent(events[i])}
+
+`;
+    }
+    const fullPrompt = `${this.prompt}
+
+${formattedEvents}`;
+    const request = {
+      contents: [{ role: "user", parts: [{ text: fullPrompt }] }],
+      toolsDict: {},
+      liveConnectConfig: {}
+    };
+    const responseGen = this.llm.generateContentAsync(request, false);
+    let compactedContent = "";
+    const firstResponse = await responseGen.next();
+    if (firstResponse.done || !((_c = (_b = (_a = firstResponse.value.content) == null ? void 0 : _a.parts) == null ? void 0 : _b[0]) == null ? void 0 : _c.text)) {
+      throw new Error("LLM failed to return a valid summary.");
+    }
+    compactedContent += firstResponse.value.content.parts[0].text;
+    for await (const chunk of responseGen) {
+      if ((_f = (_e = (_d = chunk.content) == null ? void 0 : _d.parts) == null ? void 0 : _e[0]) == null ? void 0 : _f.text) {
+        compactedContent += chunk.content.parts[0].text;
+      }
+    }
+    return createCompactedEvent({
+      author: "system",
+      content: {
+        role: "model",
+        parts: [{ text: compactedContent }]
+      },
+      startTime,
+      endTime,
+      compactedContent
+    });
+  }
+}
+export {
+  LlmSummarizer
+};

package/dist/esm/context/token_based_context_compactor.js

@@ -0,0 +1,105 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { isCompactedEvent } from "../events/compacted_event.js";
+import { stringifyContent } from "../events/event.js";
+class TokenBasedContextCompactor {
+  constructor(options) {
+    this.tokenThreshold = options.tokenThreshold;
+    this.eventRetentionSize = options.eventRetentionSize;
+    this.summarizer = options.summarizer;
+  }
+  getActiveEvents(events) {
+    let latestCompactedEvent = void 0;
+    for (let i = events.length - 1; i >= 0; i--) {
+      const e = events[i];
+      if (isCompactedEvent(e)) {
+        if (!latestCompactedEvent || e.endTime > latestCompactedEvent.endTime) {
+          latestCompactedEvent = e;
+        }
+      }
+    }
+    if (!latestCompactedEvent) {
+      return events;
+    }
+    const activeRawEvents = events.filter(
+      (e) => !isCompactedEvent(e) && e.timestamp > latestCompactedEvent.endTime
+    );
+    return [latestCompactedEvent, ...activeRawEvents];
+  }
+  shouldCompact(invocationContext) {
+    const events = invocationContext.session.events;
+    const activeEvents = this.getActiveEvents(events);
+    const rawEvents = activeEvents.filter((e) => !isCompactedEvent(e));
+    if (rawEvents.length <= this.eventRetentionSize) {
+      return false;
+    }
+    let totalTokens = 0;
+    for (const event of activeEvents) {
+      totalTokens += getEventTokens(event);
+    }
+    return totalTokens > this.tokenThreshold;
+  }
+  async compact(invocationContext) {
+    const events = invocationContext.session.events;
+    const activeEvents = this.getActiveEvents(events);
+    const rawEvents = activeEvents.filter((e) => !isCompactedEvent(e));
+    if (rawEvents.length <= this.eventRetentionSize) {
+      return;
+    }
+    let retainStartIndex = Math.max(
+      0,
+      rawEvents.length - this.eventRetentionSize
+    );
+    while (retainStartIndex > 0) {
+      const eventToRetain = rawEvents[retainStartIndex];
+      const previousEvent = rawEvents[retainStartIndex - 1];
+      if (hasFunctionResponse(eventToRetain) && hasFunctionCall(previousEvent)) {
+        retainStartIndex--;
+      } else {
+        break;
+      }
+    }
+    if (retainStartIndex === 0) {
+      return;
+    }
+    const rawEventsToCompact = rawEvents.slice(0, retainStartIndex);
+    const compactedEventPresent = activeEvents.find(isCompactedEvent);
+    const eventsToCompact = compactedEventPresent ? [compactedEventPresent, ...rawEventsToCompact] : rawEventsToCompact;
+    const compactedEvent = await this.summarizer.summarize(eventsToCompact);
+    if (!compactedEvent.actions) {
+      compactedEvent.actions = {
+        stateDelta: {},
+        artifactDelta: {},
+        requestedAuthConfigs: [],
+        requestedToolConfirmations: {}
+      };
+    }
+    invocationContext.session.events.push(compactedEvent);
+  }
+}
+function getEventTokens(event) {
+  var _a;
+  if (((_a = event.usageMetadata) == null ? void 0 : _a.promptTokenCount) !== void 0) {
+    return event.usageMetadata.promptTokenCount;
+  }
+  const contentStr = stringifyContent(event);
+  return Math.ceil(contentStr.length / 4);
+}
+function hasFunctionCall(event) {
+  var _a, _b;
+  return !!((_b = (_a = event.content) == null ? void 0 : _a.parts) == null ? void 0 : _b.some(
+    (part) => part.functionCall !== void 0
+  ));
+}
+function hasFunctionResponse(event) {
+  var _a, _b;
+  return !!((_b = (_a = event.content) == null ? void 0 : _a.parts) == null ? void 0 : _b.some(
+    (part) => part.functionResponse !== void 0
+  ));
+}
+export {
+  TokenBasedContextCompactor
+};

package/dist/esm/context/truncating_context_compactor.js

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+class TruncatingContextCompactor {
+  constructor(options) {
+    var _a;
+    this.threshold = options.threshold;
+    this.preserveLeadingEvents = (_a = options.preserveLeadingEvents) != null ? _a : 0;
+  }
+  shouldCompact(invocationContext) {
+    const eventsLength = invocationContext.session.events.length;
+    return eventsLength > this.threshold + Math.max(0, this.preserveLeadingEvents);
+  }
+  compact(invocationContext) {
+    const events = invocationContext.session.events;
+    const excess = events.length - this.threshold - Math.max(0, this.preserveLeadingEvents);
+    if (excess <= 0) {
+      return;
+    }
+    const startIndexToRemove = Math.max(0, this.preserveLeadingEvents);
+    events.splice(startIndexToRemove, excess);
+  }
+}
+export {
+  TruncatingContextCompactor
+};

package/dist/esm/events/compacted_event.js

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { createEvent } from "./event.js";
+function isCompactedEvent(event) {
+  return "isCompacted" in event && event.isCompacted === true;
+}
+function createCompactedEvent(params = {}) {
+  return {
+    ...createEvent(params),
+    isCompacted: params.isCompacted || true,
+    startTime: params.startTime,
+    endTime: params.endTime,
+    compactedContent: params.compactedContent
+  };
+}
+export {
+  createCompactedEvent,
+  isCompactedEvent
+};