@google/adk 1.3.0 → 1.5.0

package/dist/web/plugins/base_plugin.js

@@ -19,6 +19,7 @@ import { experimental } from "../utils/experimental.js";
 var ContextCompactionTrigger = /* @__PURE__ */ ((ContextCompactionTrigger2) => {
   ContextCompactionTrigger2["Manual"] = "Manual";
   ContextCompactionTrigger2["Auto"] = "Auto";
+  ContextCompactionTrigger2["AgentControlled"] = "AgentControlled";
   return ContextCompactionTrigger2;
 })(ContextCompactionTrigger || {});
 class BasePlugin {

package/dist/web/plugins/global_instruction_plugin.js

@@ -0,0 +1,67 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { injectSessionState } from "../agents/instructions.js";
+import { ReadonlyContext } from "../agents/readonly_context.js";
+import { BasePlugin } from "./base_plugin.js";
+class GlobalInstructionPlugin extends BasePlugin {
+  /**
+   * Initializes the GlobalInstructionPlugin.
+   *
+   * @param globalInstruction The instruction to apply globally. Can be a string
+   *     or an InstructionProvider function that takes ReadonlyContext and
+   *     returns a string (sync or async).
+   * @param name The name of the plugin (defaults to 'global_instruction').
+   */
+  constructor(globalInstruction, name = "global_instruction") {
+    super(name);
+    this.globalInstruction = globalInstruction;
+  }
+  async beforeModelCallback(params) {
+    if (!this.globalInstruction) {
+      return;
+    }
+    const readonlyContext = new ReadonlyContext(
+      params.callbackContext.invocationContext
+    );
+    const finalGlobalInstruction = await this.resolveGlobalInstruction(readonlyContext);
+    if (!finalGlobalInstruction) {
+      return;
+    }
+    if (!params.llmRequest.config) {
+      params.llmRequest.config = {};
+    }
+    const existingInstruction = params.llmRequest.config.systemInstruction;
+    if (!existingInstruction || Array.isArray(existingInstruction) && existingInstruction.length === 0) {
+      params.llmRequest.config.systemInstruction = finalGlobalInstruction;
+      return;
+    }
+    if (typeof existingInstruction === "string") {
+      params.llmRequest.config.systemInstruction = "".concat(finalGlobalInstruction, "\n\n").concat(existingInstruction);
+    } else if (Array.isArray(existingInstruction)) {
+      params.llmRequest.config.systemInstruction = [
+        finalGlobalInstruction,
+        ...existingInstruction
+      ];
+    } else {
+      params.llmRequest.config.systemInstruction = [
+        finalGlobalInstruction,
+        existingInstruction
+      ];
+    }
+    return;
+  }
+  async resolveGlobalInstruction(readonlyContext) {
+    if (typeof this.globalInstruction === "string") {
+      return await injectSessionState(this.globalInstruction, readonlyContext);
+    }
+    return await this.globalInstruction(readonlyContext);
+  }
+}
+export {
+  GlobalInstructionPlugin
+};

package/dist/web/runner/in_memory_runner.js

@@ -14,19 +14,30 @@ class InMemoryRunner extends Runner {
    * Creates a new InMemoryRunner instance.
    *
    * @param params The configuration for the runner.
+   * @param params.app An optional application instance to run.
    * @param params.agent The root agent to run.
    * @param params.appName The application name. Defaults to `'InMemoryRunner'`.
    * @param params.plugins An optional list of plugins.
+   * @param params.resumabilityConfig An optional resumability configuration.
    */
   constructor(params) {
-    const { agent, appName = "InMemoryRunner", plugins = [] } = params;
+    var _a;
+    const {
+      agent,
+      appName = "InMemoryRunner",
+      plugins = [],
+      app,
+      resumabilityConfig
+    } = params;
     super({
+      app,
       appName,
       agent,
       plugins,
       artifactService: new InMemoryArtifactService(),
       sessionService: new InMemorySessionService(),
-      memoryService: new InMemoryMemoryService()
+      memoryService: new InMemoryMemoryService(),
+      resumabilityConfig: (_a = app == null ? void 0 : app.resumabilityConfig) != null ? _a : resumabilityConfig
     });
   }
 }

package/dist/web/runner/runner.js

@@ -1,9 +1,28 @@
 import {createRequire as topLevelCreateRequire} from 'module';
 const require = topLevelCreateRequire(import.meta.url);
+var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
 var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : Symbol.for("Symbol." + name);
 var __typeError = (msg) => {
   throw TypeError(msg);
 };
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
 var __await = function(promise, isYieldStar) {
   this[0] = promise;
   this[1] = isYieldStar;
@@ -56,17 +75,19 @@ var __forAwait = (obj, it, method) => (it = obj[__knownSymbol("asyncIterator")])
 var _a;
 import { createPartFromText } from "@google/genai";
 import { context, trace } from "@opentelemetry/api";
+import { findMatchingFunctionCall } from "../agents/functions.js";
 import {
   InvocationContext,
   newInvocationContextId
 } from "../agents/invocation_context.js";
 import { isLlmAgent } from "../agents/llm_agent.js";
 import { createRunConfig } from "../agents/run_config.js";
+import { ScopedArtifactService } from "../artifacts/scoped_artifact_service.js";
 import {
   BuiltInCodeExecutor,
   isBuiltInCodeExecutor
 } from "../code_executors/built_in_code_executor.js";
-import { createEvent, getFunctionCalls } from "../events/event.js";
+import { createEvent } from "../events/event.js";
 import { createEventActions } from "../events/event_actions.js";
 import { PluginManager } from "../plugins/plugin_manager.js";
 import {
@@ -89,14 +110,24 @@ class Runner {
    */
   constructor(input) {
     this[_a] = true;
-    var _a2;
-    this.appName = input.appName;
-    this.agent = input.agent;
-    this.pluginManager = new PluginManager((_a2 = input.plugins) != null ? _a2 : []);
+    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;
+    const agent = (_d = (_c = input.app) == null ? void 0 : _c.rootAgent) != null ? _d : input.agent;
+    if (!agent) {
+      throw new Error(
+        "agent must be provided in runner constructor (or via app.rootAgent)"
+      );
+    }
+    this.appName = appName;
+    this.agent = agent;
+    const appPlugins = (_f = (_e = input.app) == null ? void 0 : _e.plugins) != null ? _f : [];
+    const configPlugins = (_g = input.plugins) != null ? _g : [];
+    this.pluginManager = new PluginManager([...appPlugins, ...configPlugins]);
     this.artifactService = input.artifactService;
     this.sessionService = input.sessionService;
     this.memoryService = input.memoryService;
     this.credentialService = input.credentialService;
+    this.resumabilityConfig = (_i = (_h = input.app) == null ? void 0 : _h.resumabilityConfig) != null ? _i : input.resumabilityConfig;
   }
   /**
    * Runs the agent with a new, ephemeral session.
@@ -149,6 +180,9 @@ class Runner {
       const { userId, sessionId, stateDelta } = params;
       const runConfig = createRunConfig(params.runConfig);
       let newMessage = params.newMessage;
+      if (newMessage && !newMessage.role) {
+        newMessage.role = "user";
+      }
       const span = tracer.startSpan("invocation");
       const ctx = trace.setSpan(context.active(), span);
       try {
@@ -169,7 +203,7 @@ class Runner {
               if (!session) {
                 if (!this.appName) {
                   throw new Error(
-                    "Session lookup failed: appName must be provided in runner constructor"
+                    "Session lookup failed: appName must be provided in runner constructor (or via app.name)"
                   );
                 }
                 throw new Error("Session not found: ".concat(sessionId));
@@ -186,7 +220,12 @@ class Runner {
                 }
               }
               const invocationContext = new InvocationContext({
-                artifactService: this.artifactService,
+                artifactService: this.artifactService ? new ScopedArtifactService(
+                  this.artifactService,
+                  this.appName,
+                  userId,
+                  sessionId
+                ) : void 0,
                 sessionService: this.sessionService,
                 memoryService: this.memoryService,
                 credentialService: this.credentialService,
@@ -213,7 +252,7 @@ class Runner {
                   throw new Error("No parts in the newMessage.");
                 }
                 if (runConfig.saveInputBlobsAsArtifacts) {
-                  yield new __await(this.saveArtifacts(
+                  newMessage = yield new __await(this.saveArtifacts(
                     invocationContext.invocationId,
                     session.userId,
                     session.id,
@@ -315,7 +354,7 @@ class Runner {
   }
   /**
    * Saves artifacts from the message parts and replaces the inline data with
-   * a file name placeholder.
+   * a file name placeholder and optional file reference.
    *
    * @param invocationId The current invocation ID.
    * @param userId The user ID of the session.
@@ -325,110 +364,141 @@ class Runner {
   async saveArtifacts(invocationId, userId, sessionId, message) {
     var _a2;
     if (!this.artifactService || !((_a2 = message.parts) == null ? void 0 : _a2.length)) {
-      return;
+      return message;
     }
+    const sessionKey = {
+      appName: this.appName,
+      userId,
+      sessionId
+    };
+    const newParts = [];
+    let modified = false;
     for (let i = 0; i < message.parts.length; i++) {
       const part = message.parts[i];
       if (!part.inlineData) {
+        newParts.push(part);
         continue;
       }
-      const fileName = "artifact_".concat(invocationId, "_").concat(i);
-      await this.artifactService.saveArtifact({
-        appName: this.appName,
-        userId,
-        sessionId,
-        filename: fileName,
-        artifact: part
-      });
-      message.parts[i] = createPartFromText(
-        "Uploaded file: ".concat(fileName, ". It is saved into artifacts")
-      );
+      try {
+        const inlineData = part.inlineData;
+        const fileName = inlineData.displayName || "artifact_".concat(invocationId, "_").concat(i);
+        const version = await this.artifactService.saveArtifact(__spreadProps(__spreadValues({}, sessionKey), {
+          filename: fileName,
+          artifact: part
+        }));
+        newParts.push(createPartFromText('[Uploaded Artifact: "'.concat(fileName, '"]')));
+        try {
+          const artifactVersion = await this.artifactService.getArtifactVersion(
+            __spreadProps(__spreadValues({}, sessionKey), {
+              filename: fileName,
+              version
+            })
+          );
+          if ((artifactVersion == null ? void 0 : artifactVersion.canonicalUri) && /^(gs|https?):/i.test(artifactVersion.canonicalUri)) {
+            newParts.push({
+              fileData: {
+                fileUri: artifactVersion.canonicalUri,
+                mimeType: artifactVersion.mimeType || inlineData.mimeType || "",
+                displayName: fileName
+              }
+            });
+          }
+        } catch (error) {
+          logger.warn(
+            "Failed to resolve artifact version for ".concat(fileName, ":"),
+            error
+          );
+        }
+        modified = true;
+        logger.info("Successfully saved artifact: ".concat(fileName));
+      } catch (error) {
+        logger.error("Failed to save artifact for part ".concat(i, ":"), error);
+        newParts.push(part);
+      }
+    }
+    if (!modified) {
+      return message;
     }
+    return __spreadProps(__spreadValues({}, message), {
+      parts: newParts
+    });
   }
   /**
    * Determines the next agent to run to continue the session. This is primarily
    * used for session resumption.
    */
-  // TODO - b/425992518: This is where LRO integration should happen.
-  // Needs clean up before we can generalize it.
+  /**
+   * Determines the next agent to run to continue the session. This is primarily
+   * used for session resumption across tool and LRO boundaries.
+   */
   determineAgentForResumption(session, rootAgent) {
-    const event = findEventByLastFunctionResponseId(session.events);
-    if (event && event.author) {
-      return rootAgent.findAgent(event.author) || rootAgent;
-    }
-    for (let i = session.events.length - 1; i >= 0; i--) {
-      logger.info("event:", JSON.stringify(session.events[i]));
-      const event2 = session.events[i];
-      if (event2.author === "user" || !event2.author) {
-        continue;
-      }
-      if (event2.author === rootAgent.name) {
-        return rootAgent;
-      }
-      const agent = rootAgent.findSubAgent(event2.author);
-      if (!agent) {
-        logger.warn(
-          "Event from an unknown agent: ".concat(event2.author, ", event id: ").concat(event2.id)
-        );
-        continue;
-      }
-      if (this.isRoutableLlmAgent(agent)) {
-        return agent;
-      }
-    }
-    return rootAgent;
+    return determineAgentForResumption(
+      session,
+      rootAgent,
+      this.resumabilityConfig
+    );
   }
   /**
    * Whether the agent to run can transfer to any other agent in the agent tree.
    *
-   * An agent is transferable if:
-   *  - It is an instance of `LlmAgent`.
-   *  - All its ancestors are also transferable (i.e., they have
-   *    `disallowTransferToParent` set to false).
-   *
    * @param agentToRun The agent to check for transferability.
    * @returns True if the agent can transfer, False otherwise.
    */
   isRoutableLlmAgent(agentToRun) {
-    let agent = agentToRun;
-    while (agent) {
-      if (!isLlmAgent(agent)) {
-        return false;
-      }
-      if (agent.disallowTransferToParent) {
-        return false;
-      }
-      agent = agent.parentAgent;
-    }
-    return true;
+    return isRoutableLlmAgent(agentToRun);
   }
   // TODO - b/425992518: Implement runLive and related methods.
 }
-function findEventByLastFunctionResponseId(events) {
-  var _a2, _b, _c, _d;
-  if (!events.length) {
-    return null;
-  }
-  const lastEvent = events[events.length - 1];
-  const functionCallId = (_d = (_c = (_b = (_a2 = lastEvent.content) == null ? void 0 : _a2.parts) == null ? void 0 : _b.find(
-    (part) => part.functionResponse
-  )) == null ? void 0 : _c.functionResponse) == null ? void 0 : _d.id;
-  if (!functionCallId) {
-    return null;
+function determineAgentForResumption(session, rootAgent, resumabilityConfig) {
+  const event = findEventByLastFunctionResponseId(session.events);
+  const isResumable = Boolean(resumabilityConfig == null ? void 0 : resumabilityConfig.isResumable);
+  if (event && event.author && isResumable) {
+    const resumedAgent = rootAgent.findAgent(event.author);
+    if (resumedAgent) {
+      return resumedAgent;
+    }
+    logger.warn(
+      "Function response from an unknown agent: ".concat(event.author, ", event id: ").concat(event.id)
+    );
   }
-  for (let i = events.length - 2; i >= 0; i--) {
-    const event = events[i];
-    const functionCalls = getFunctionCalls(event);
-    if (!functionCalls) {
+  for (let i = session.events.length - 1; i >= 0; i--) {
+    logger.debug("event:", JSON.stringify(session.events[i]));
+    const event2 = session.events[i];
+    if (event2.author === "user" || !event2.author) {
       continue;
     }
-    for (const functionCall of functionCalls) {
-      if (functionCall.id === functionCallId) {
-        return event;
-      }
+    if (event2.author === rootAgent.name) {
+      return rootAgent;
+    }
+    const agent = rootAgent.findSubAgent(event2.author);
+    if (!agent) {
+      logger.warn(
+        "Event from an unknown agent: ".concat(event2.author, ", event id: ").concat(event2.id)
+      );
+      continue;
+    }
+    if (isRoutableLlmAgent(agent)) {
+      return agent;
     }
   }
-  return null;
+  return rootAgent;
+}
+function isRoutableLlmAgent(agentToRun) {
+  let agent = agentToRun;
+  while (agent) {
+    if (!isLlmAgent(agent)) {
+      return false;
+    }
+    if (agent.disallowTransferToParent) {
+      return false;
+    }
+    agent = agent.parentAgent;
+  }
+  return true;
+}
+function findEventByLastFunctionResponseId(events) {
+  var _a2;
+  return (_a2 = findMatchingFunctionCall(events)) != null ? _a2 : null;
 }
 function getAllToolsets(agent) {
   const toolsets = [];
@@ -452,5 +522,8 @@ function getAllToolsets(agent) {
 }
 export {
   Runner,
+  determineAgentForResumption,
+  findEventByLastFunctionResponseId,
+  isRoutableLlmAgent,
   isRunner
 };

package/dist/web/sessions/base_session_service.js

@@ -40,7 +40,12 @@ class BaseSessionService {
     }
     event = trimTempDeltaState(event);
     this.updateSessionState({ session, event });
-    session.events.push(event);
+    const index = session.events.findIndex((e) => e.id === event.id);
+    if (index >= 0) {
+      session.events[index] = event;
+    } else {
+      session.events.push(event);
+    }
     return event;
   }
   /**

package/dist/web/sessions/database_session_service.js

@@ -389,16 +389,28 @@ class DatabaseSessionService extends BaseSessionService {
           storageSession.state = __spreadValues(__spreadValues({}, storageSession.state), sessionDelta);
         }
       }
-      const newStorageEvent = txEm.create(StorageEvent, {
+      const existingStorageEvent = await txEm.findOne(StorageEvent, {
         id: trimmedEvent.id,
         appName: session.appName,
         userId: session.userId,
-        sessionId: session.id,
-        invocationId: trimmedEvent.invocationId,
-        timestamp: new Date(trimmedEvent.timestamp),
-        eventData: trimmedEvent
+        sessionId: session.id
       });
-      txEm.persist(newStorageEvent);
+      if (existingStorageEvent) {
+        existingStorageEvent.eventData = trimmedEvent;
+        existingStorageEvent.timestamp = new Date(trimmedEvent.timestamp);
+        txEm.persist(existingStorageEvent);
+      } else {
+        const newStorageEvent = txEm.create(StorageEvent, {
+          id: trimmedEvent.id,
+          appName: session.appName,
+          userId: session.userId,
+          sessionId: session.id,
+          invocationId: trimmedEvent.invocationId,
+          timestamp: new Date(trimmedEvent.timestamp),
+          eventData: trimmedEvent
+        });
+        txEm.persist(newStorageEvent);
+      }
       await txEm.commit();
       storageSession.updateTime = new Date(event.timestamp);
       const newMergedState = mergeStates(
@@ -407,7 +419,12 @@ class DatabaseSessionService extends BaseSessionService {
         storageSession.state
       );
       session.state = newMergedState;
-      session.events.push(event);
+      const index = session.events.findIndex((e) => e.id === event.id);
+      if (index >= 0) {
+        session.events[index] = event;
+      } else {
+        session.events.push(event);
+      }
       session.lastUpdateTime = storageSession.updateTime.getTime();
     });
     return event;

package/dist/web/sessions/vertex_ai_session_service.js

@@ -50,6 +50,10 @@ const HTTP_NOT_FOUND = 404;
 function isVertexAiConnectionString(uri) {
   return (uri == null ? void 0 : uri.startsWith("vertexai://")) || false;
 }
+function quoteFilterLiteral(value) {
+  const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+  return '"'.concat(escaped, '"');
+}
 let VertexAiSessionService = class extends BaseSessionService {
   constructor(options) {
     super();
@@ -213,7 +217,7 @@ let VertexAiSessionService = class extends BaseSessionService {
     do {
       const response = await this.sessions.listInternal({
         name: "reasoningEngines/".concat(reasoningEngineId),
-        config: __spreadValues(__spreadValues({}, userId ? { filter: 'user_id="'.concat(userId, '"') } : {}), pageToken ? { pageToken } : {})
+        config: __spreadValues(__spreadValues({}, userId ? { filter: "user_id=".concat(quoteFilterLiteral(userId)) } : {}), pageToken ? { pageToken } : {})
       });
       const sessions = response.sessions || [];
       for (const sessionObj of sessions) {
@@ -272,10 +276,19 @@ let VertexAiSessionService = class extends BaseSessionService {
   }
   async deleteSession({
     appName,
-    userId: _userId,
+    userId,
     sessionId
   }) {
     const reasoningEngineId = this.getReasoningEngineId(appName);
+    const session = await this.getSession({
+      appName,
+      userId,
+      sessionId,
+      config: { numRecentEvents: 0 }
+    });
+    if (!session) {
+      return;
+    }
     await this.sessions.delete({
       name: "reasoningEngines/".concat(reasoningEngineId, "/sessions/").concat(sessionId)
     });
@@ -412,5 +425,6 @@ function _fromApiEvent(apiEventObj) {
 }
 export {
   VertexAiSessionService,
-  isVertexAiConnectionString
+  isVertexAiConnectionString,
+  quoteFilterLiteral
 };

package/dist/web/skills/loader.js

@@ -103,12 +103,12 @@ function parseSkillMdContent(content) {
   if (!content.startsWith("---")) {
     throw new Error("SKILL.md must start with YAML frontmatter (---)");
   }
-  const parts = content.split("---", 3);
+  const parts = content.split("---");
   if (parts.length < 3) {
     throw new Error("SKILL.md frontmatter not properly closed with ---");
   }
   const frontmatterStr = parts[1];
-  const body = parts[2].trim();
+  const body = parts.filter((_, i) => i >= 2).join("---").trim();
   try {
     const parsed = yaml.load(frontmatterStr);
     if (typeof parsed !== "object" || parsed === null) {

package/dist/web/tools/base_toolset.js

@@ -25,7 +25,7 @@ class BaseToolset {
    * @return Whether the tool should be exposed to LLM.
    */
   isToolSelected(tool, context) {
-    if (!this.toolFilter) {
+    if (!this.toolFilter || Array.isArray(this.toolFilter) && this.toolFilter.length === 0) {
       return true;
     }
     if (typeof this.toolFilter === "function") {

package/dist/web/tools/consolidate_context_tool.js

@@ -0,0 +1,51 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Type } from "@google/genai";
+import { BaseTool } from "./base_tool.js";
+class ConsolidateContextTool extends BaseTool {
+  constructor() {
+    super({
+      name: "consolidate_context",
+      description: "Requests context consolidation (compaction) to manage history size. Use this when a subtask is complete and you want to summarize progress and clear detailed history."
+    });
+  }
+  _getDeclaration() {
+    return {
+      name: this.name,
+      description: this.description,
+      parameters: {
+        type: Type.OBJECT,
+        properties: {
+          detail: {
+            type: Type.STRING,
+            description: "Optional description of what has been accomplished so far. This detail will be used to guide the summarization of the history."
+          }
+        }
+      }
+    };
+  }
+  async runAsync({
+    args,
+    toolContext
+  }) {
+    toolContext.state.set("temp:consolidate_context", true);
+    if (args["detail"] !== void 0) {
+      toolContext.state.set(
+        "temp:consolidate_context_detail",
+        args["detail"]
+      );
+    }
+    return {
+      status: "success",
+      message: "Context consolidation requested."
+    };
+  }
+}
+export {
+  ConsolidateContextTool
+};