@google/adk 1.3.0 → 1.5.0

package/dist/cjs/plugins/base_plugin.js

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

package/dist/cjs/plugins/global_instruction_plugin.js

@@ -0,0 +1,97 @@
+/**
+  * @license
+  * Copyright 2026 Google LLC
+  * SPDX-License-Identifier: Apache-2.0
+  */
+
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var global_instruction_plugin_exports = {};
+__export(global_instruction_plugin_exports, {
+  GlobalInstructionPlugin: () => GlobalInstructionPlugin
+});
+module.exports = __toCommonJS(global_instruction_plugin_exports);
+var import_instructions = require("../agents/instructions.js");
+var import_readonly_context = require("../agents/readonly_context.js");
+var import_base_plugin = require("./base_plugin.js");
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+class GlobalInstructionPlugin extends import_base_plugin.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 import_readonly_context.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 = `${finalGlobalInstruction}
+
+${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 (0, import_instructions.injectSessionState)(this.globalInstruction, readonlyContext);
+    }
+    return await this.globalInstruction(readonlyContext);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  GlobalInstructionPlugin
+});

package/dist/cjs/runner/in_memory_runner.js

@@ -41,19 +41,30 @@ class InMemoryRunner extends import_runner.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 import_in_memory_artifact_service.InMemoryArtifactService(),
       sessionService: new import_in_memory_session_service.InMemorySessionService(),
-      memoryService: new import_in_memory_memory_service.InMemoryMemoryService()
+      memoryService: new import_in_memory_memory_service.InMemoryMemoryService(),
+      resumabilityConfig: (_a = app == null ? void 0 : app.resumabilityConfig) != null ? _a : resumabilityConfig
     });
   }
 }

package/dist/cjs/runner/runner.js

@@ -25,14 +25,19 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var runner_exports = {};
 __export(runner_exports, {
   Runner: () => Runner,
+  determineAgentForResumption: () => determineAgentForResumption,
+  findEventByLastFunctionResponseId: () => findEventByLastFunctionResponseId,
+  isRoutableLlmAgent: () => isRoutableLlmAgent,
   isRunner: () => isRunner
 });
 module.exports = __toCommonJS(runner_exports);
 var import_genai = require("@google/genai");
 var import_api = require("@opentelemetry/api");
+var import_functions = require("../agents/functions.js");
 var import_invocation_context = require("../agents/invocation_context.js");
 var import_llm_agent = require("../agents/llm_agent.js");
 var import_run_config = require("../agents/run_config.js");
+var import_scoped_artifact_service = require("../artifacts/scoped_artifact_service.js");
 var import_built_in_code_executor = require("../code_executors/built_in_code_executor.js");
 var import_event = require("../events/event.js");
 var import_event_actions = require("../events/event_actions.js");
@@ -60,14 +65,24 @@ class Runner {
    */
   constructor(input) {
     this[_a] = true;
-    var _a2;
-    this.appName = input.appName;
-    this.agent = input.agent;
-    this.pluginManager = new import_plugin_manager.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 import_plugin_manager.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.
@@ -117,6 +132,9 @@ class Runner {
     const { userId, sessionId, stateDelta } = params;
     const runConfig = (0, import_run_config.createRunConfig)(params.runConfig);
     let newMessage = params.newMessage;
+    if (newMessage && !newMessage.role) {
+      newMessage.role = "user";
+    }
     const span = import_tracing.tracer.startSpan("invocation");
     const ctx = import_api.trace.setSpan(import_api.context.active(), span);
     try {
@@ -136,7 +154,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: ${sessionId}`);
@@ -153,7 +171,12 @@ class Runner {
             }
           }
           const invocationContext = new import_invocation_context.InvocationContext({
-            artifactService: this.artifactService,
+            artifactService: this.artifactService ? new import_scoped_artifact_service.ScopedArtifactService(
+              this.artifactService,
+              this.appName,
+              userId,
+              sessionId
+            ) : void 0,
             sessionService: this.sessionService,
             memoryService: this.memoryService,
             credentialService: this.credentialService,
@@ -180,7 +203,7 @@ class Runner {
               throw new Error("No parts in the newMessage.");
             }
             if (runConfig.saveInputBlobsAsArtifacts) {
-              await this.saveArtifacts(
+              newMessage = await this.saveArtifacts(
                 invocationContext.invocationId,
                 session.userId,
                 session.id,
@@ -268,7 +291,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.
@@ -278,110 +301,144 @@ 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_${invocationId}_${i}`;
-      await this.artifactService.saveArtifact({
-        appName: this.appName,
-        userId,
-        sessionId,
-        filename: fileName,
-        artifact: part
-      });
-      message.parts[i] = (0, import_genai.createPartFromText)(
-        `Uploaded file: ${fileName}. It is saved into artifacts`
-      );
+      try {
+        const inlineData = part.inlineData;
+        const fileName = inlineData.displayName || `artifact_${invocationId}_${i}`;
+        const version = await this.artifactService.saveArtifact({
+          ...sessionKey,
+          filename: fileName,
+          artifact: part
+        });
+        newParts.push((0, import_genai.createPartFromText)(`[Uploaded Artifact: "${fileName}"]`));
+        try {
+          const artifactVersion = await this.artifactService.getArtifactVersion(
+            {
+              ...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) {
+          import_logger.logger.warn(
+            `Failed to resolve artifact version for ${fileName}:`,
+            error
+          );
+        }
+        modified = true;
+        import_logger.logger.info(`Successfully saved artifact: ${fileName}`);
+      } catch (error) {
+        import_logger.logger.error(`Failed to save artifact for part ${i}:`, error);
+        newParts.push(part);
+      }
+    }
+    if (!modified) {
+      return message;
     }
+    return {
+      ...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--) {
-      import_logger.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) {
-        import_logger.logger.warn(
-          `Event from an unknown agent: ${event2.author}, event id: ${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 (!(0, import_llm_agent.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;
+    }
+    import_logger.logger.warn(
+      `Function response from an unknown agent: ${event.author}, event id: ${event.id}`
+    );
   }
-  for (let i = events.length - 2; i >= 0; i--) {
-    const event = events[i];
-    const functionCalls = (0, import_event.getFunctionCalls)(event);
-    if (!functionCalls) {
+  for (let i = session.events.length - 1; i >= 0; i--) {
+    import_logger.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) {
+      import_logger.logger.warn(
+        `Event from an unknown agent: ${event2.author}, event id: ${event2.id}`
+      );
+      continue;
+    }
+    if (isRoutableLlmAgent(agent)) {
+      return agent;
     }
   }
-  return null;
+  return rootAgent;
+}
+function isRoutableLlmAgent(agentToRun) {
+  let agent = agentToRun;
+  while (agent) {
+    if (!(0, import_llm_agent.isLlmAgent)(agent)) {
+      return false;
+    }
+    if (agent.disallowTransferToParent) {
+      return false;
+    }
+    agent = agent.parentAgent;
+  }
+  return true;
+}
+function findEventByLastFunctionResponseId(events) {
+  var _a2;
+  return (_a2 = (0, import_functions.findMatchingFunctionCall)(events)) != null ? _a2 : null;
 }
 function getAllToolsets(agent) {
   const toolsets = [];
@@ -406,5 +463,8 @@ function getAllToolsets(agent) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Runner,
+  determineAgentForResumption,
+  findEventByLastFunctionResponseId,
+  isRoutableLlmAgent,
   isRunner
 });

package/dist/cjs/sessions/base_session_service.js

@@ -70,7 +70,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/cjs/sessions/database_session_service.js

@@ -382,16 +382,28 @@ class DatabaseSessionService extends import_base_session_service.BaseSessionServ
           storageSession.state = { ...storageSession.state, ...sessionDelta };
         }
       }
-      const newStorageEvent = txEm.create(import_schema.StorageEvent, {
+      const existingStorageEvent = await txEm.findOne(import_schema.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(import_schema.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 = (0, import_base_session_service.mergeStates)(
@@ -400,7 +412,12 @@ class DatabaseSessionService extends import_base_session_service.BaseSessionServ
         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/cjs/sessions/vertex_ai_session_service.js

@@ -33,7 +33,8 @@ var __decorateClass = (decorators, target, key, kind) => {
 var vertex_ai_session_service_exports = {};
 __export(vertex_ai_session_service_exports, {
   VertexAiSessionService: () => VertexAiSessionService,
-  isVertexAiConnectionString: () => isVertexAiConnectionString
+  isVertexAiConnectionString: () => isVertexAiConnectionString,
+  quoteFilterLiteral: () => quoteFilterLiteral
 });
 module.exports = __toCommonJS(vertex_ai_session_service_exports);
 var import_client = require("@google-cloud/vertexai/build/src/genai/client.js");
@@ -55,6 +56,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 `"${escaped}"`;
+}
 let VertexAiSessionService = class extends import_base_session_service.BaseSessionService {
   constructor(options) {
     super();
@@ -222,7 +227,7 @@ let VertexAiSessionService = class extends import_base_session_service.BaseSessi
       const response = await this.sessions.listInternal({
         name: `reasoningEngines/${reasoningEngineId}`,
         config: {
-          ...userId ? { filter: `user_id="${userId}"` } : {},
+          ...userId ? { filter: `user_id=${quoteFilterLiteral(userId)}` } : {},
           ...pageToken ? { pageToken } : {}
         }
       });
@@ -283,10 +288,19 @@ let VertexAiSessionService = class extends import_base_session_service.BaseSessi
   }
   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/${reasoningEngineId}/sessions/${sessionId}`
     });
@@ -425,5 +439,6 @@ function _fromApiEvent(apiEventObj) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   VertexAiSessionService,
-  isVertexAiConnectionString
+  isVertexAiConnectionString,
+  quoteFilterLiteral
 });

package/dist/cjs/skills/loader.js

@@ -123,12 +123,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 = import_js_yaml.default.load(frontmatterStr);
     if (typeof parsed !== "object" || parsed === null) {

package/dist/cjs/tools/base_toolset.js

@@ -53,7 +53,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") {