@google/adk 2.0.0 → 2.2.0

package/dist/cjs/plugins/reflect_retry_tool_plugin.js

@@ -0,0 +1,276 @@
+/**
+  * @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 __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+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 reflect_retry_tool_plugin_exports = {};
+__export(reflect_retry_tool_plugin_exports, {
+  ReflectAndRetryToolPlugin: () => ReflectAndRetryToolPlugin
+});
+module.exports = __toCommonJS(reflect_retry_tool_plugin_exports);
+var import_reflect_retry_utils = require("./_reflect_retry_utils.js");
+var import_base_plugin = require("./base_plugin.js");
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const _ReflectAndRetryToolPlugin = class _ReflectAndRetryToolPlugin extends import_base_plugin.BasePlugin {
+  /**
+   * Initializes the {@link ReflectAndRetryToolPlugin}.
+   *
+   * @param options - Configuration options for the plugin.
+   */
+  constructor(options = {}) {
+    var _a, _b, _c, _d;
+    super((_a = options.name) != null ? _a : "reflect_retry_tool_plugin");
+    const retries = (_b = options.maxRetries) != null ? _b : 3;
+    if (retries < 0) {
+      throw new Error("maxRetries must be a non-negative integer.");
+    }
+    this.maxRetries = retries;
+    this.throwExceptionIfRetryExceeded = (_c = options.throwExceptionIfRetryExceeded) != null ? _c : true;
+    this.scope = (_d = options.trackingScope) != null ? _d : import_reflect_retry_utils.TrackingScope.INVOCATION;
+    this.tracker = new import_reflect_retry_utils.ScopedFailureTracker();
+  }
+  /**
+   * Handles successful tool calls or extracts and processes errors.
+   *
+   * @param params - The tool callback parameters.
+   * @returns An optional record containing reflection guidance if an error is
+   *   detected, or undefined if the tool call was successful or the response is
+   *   already a reflection message.
+   */
+  async afterToolCallback({
+    tool,
+    toolArgs,
+    toolContext,
+    result
+  }) {
+    if (result && typeof result === "object" && result["response_type"] === import_reflect_retry_utils.REFLECT_AND_RETRY_RESPONSE_TYPE) {
+      return void 0;
+    }
+    const error = await this.extractErrorFromResult({
+      tool,
+      toolArgs,
+      toolContext,
+      result
+    });
+    if (error != null) {
+      return await this.handleToolError(tool, toolArgs, toolContext, error);
+    }
+    await this.resetFailuresForTool(toolContext, tool.name);
+    return void 0;
+  }
+  /**
+   * Extracts an error from a successful tool result and triggers retry logic.
+   *
+   * This is useful when a tool call finishes without throwing an exception but
+   * the result contains an error payload like `{status: 'error', message: '...'}`
+   * that should be handled by the plugin.
+   *
+   * @param params - Tool execution context and result.
+   * @returns The extracted error if any, or undefined if no error was detected.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async extractErrorFromResult(params) {
+    return void 0;
+  }
+  /**
+   * Handles tool exceptions by providing reflection guidance.
+   *
+   * @param params - The error callback parameters.
+   * @returns An optional record containing reflection guidance for the error.
+   */
+  async onToolErrorCallback({
+    tool,
+    toolArgs,
+    toolContext,
+    error
+  }) {
+    return await this.handleToolError(tool, toolArgs, toolContext, error);
+  }
+  /**
+   * Central, thread-safe logic for processing tool errors.
+   *
+   * @param tool - The tool that was called.
+   * @param toolArgs - The arguments passed to the tool.
+   * @param toolContext - The context of the tool call.
+   * @param error - The error to be handled.
+   * @returns An optional record containing reflection guidance for the error.
+   */
+  async handleToolError(tool, toolArgs, toolContext, error) {
+    if (this.maxRetries === 0) {
+      if (this.throwExceptionIfRetryExceeded) {
+        throw this.ensureException(error);
+      }
+      return this.getToolRetryExceedMsg(tool, toolArgs, error);
+    }
+    const scopeKey = this.getScopeKey(toolContext);
+    const currentRetries = await this.tracker.increment(scopeKey, tool.name);
+    if (currentRetries <= this.maxRetries) {
+      return this.createToolReflectionResponse(
+        tool,
+        toolArgs,
+        error,
+        currentRetries
+      );
+    }
+    if (this.throwExceptionIfRetryExceeded) {
+      throw this.ensureException(error);
+    } else {
+      return this.getToolRetryExceedMsg(tool, toolArgs, error);
+    }
+  }
+  /**
+   * Returns a unique key for the state tracker based on the configured scope.
+   *
+   * This method can be overridden in a subclass to implement custom scoping
+   * logic, for example tracking failures on a per-user or per-session basis.
+   *
+   * @param toolContext - The tool context.
+   * @returns The resolved scope key.
+   */
+  getScopeKey(toolContext) {
+    return (0, import_reflect_retry_utils.resolveScopeKey)(this.scope, toolContext.invocationId);
+  }
+  /**
+   * Atomically resets the failure count for a tool and cleans up state.
+   *
+   * @param toolContext - The tool context.
+   * @param toolName - The name of the tool.
+   */
+  async resetFailuresForTool(toolContext, toolName) {
+    const scopeKey = this.getScopeKey(toolContext);
+    await this.tracker.reset(scopeKey, toolName);
+  }
+  /**
+   * Ensures the given error is an Error instance, wrapping if not.
+   *
+   * @param error - The error object.
+   * @returns An Error instance.
+   */
+  ensureException(error) {
+    return error instanceof Error ? error : new Error(String(error));
+  }
+  /**
+   * Formats error details for inclusion in the reflection message.
+   *
+   * @param error - The error object.
+   * @returns Formatted error string.
+   */
+  formatErrorDetails(error) {
+    if (error instanceof Error) {
+      const name = error.name || "Error";
+      return `${name}: ${error.message}`;
+    }
+    return String(error);
+  }
+  /**
+   * Generates structured reflection guidance for tool failures.
+   *
+   * @param tool - The tool that failed.
+   * @param toolArgs - The arguments supplied to the tool.
+   * @param error - The error encountered.
+   * @param retryCount - The current retry count.
+   * @returns The structured tool failure response record.
+   */
+  createToolReflectionResponse(tool, toolArgs, error, retryCount) {
+    const argsSummary = JSON.stringify(toolArgs != null ? toolArgs : {}, null, 2);
+    const errorDetails = this.formatErrorDetails(error);
+    const reflectionMessage = `
+The call to tool \`${tool.name}\` failed.
+
+**Error Details:**
+\`\`\`
+${errorDetails}
+\`\`\`
+
+**Tool Arguments Used:**
+\`\`\`json
+${argsSummary}
+\`\`\`
+
+**Reflection Guidance:**
+This is retry attempt **${retryCount} of ${this.maxRetries}**. Analyze the error and the arguments you provided. Do not repeat the exact same call. Consider the following before your next attempt:
+
+1.  **Invalid Parameters**: Does the error suggest that one or more arguments are incorrect, badly formatted, or missing? Review the tool's schema and your arguments.
+2.  **State or Preconditions**: Did a previous step fail or not produce the necessary state/resource for this tool to succeed?
+3.  **Alternative Approach**: Is this the right tool for the job? Could another tool or a different sequence of steps achieve the goal?
+4.  **Simplify the Task**: Can you break the problem down into smaller, simpler steps?
+5.  **Wrong Function Name**: Does the error indicates the tool is not found? Please check again and only use available tools.
+
+Formulate a new plan based on your analysis and try a corrected or different approach.
+`.trim();
+    const response = {
+      response_type: import_reflect_retry_utils.REFLECT_AND_RETRY_RESPONSE_TYPE,
+      error_type: error instanceof Error ? error.name || "Error" : "ToolError",
+      error_details: error instanceof Error ? error.message : String(error),
+      retry_count: retryCount,
+      reflection_guidance: reflectionMessage
+    };
+    return response;
+  }
+  /**
+   * Generates guidance when the maximum retry limit is exceeded.
+   *
+   * @param tool - The tool that failed.
+   * @param toolArgs - The arguments supplied to the tool.
+   * @param error - The error encountered.
+   * @returns The structured retry-exceeded failure response record.
+   */
+  getToolRetryExceedMsg(tool, toolArgs, error) {
+    const errorDetails = this.formatErrorDetails(error);
+    const argsSummary = JSON.stringify(toolArgs != null ? toolArgs : {}, null, 2);
+    const reflectionMessage = `
+The tool \`${tool.name}\` has failed consecutively ${this.maxRetries} times and the retry limit has been exceeded.
+
+**Last Error:**
+\`\`\`
+${errorDetails}
+\`\`\`
+
+**Last Arguments Used:**
+\`\`\`json
+${argsSummary}
+\`\`\`
+
+**Final Instruction:**
+**Do not attempt to use the \`${tool.name}\` tool again for this task.** You must now try a different approach. Acknowledge the failure and devise a new strategy, potentially using other available tools or informing the user that the task cannot be completed.
+`.trim();
+    const response = {
+      response_type: import_reflect_retry_utils.REFLECT_AND_RETRY_RESPONSE_TYPE,
+      error_type: error instanceof Error ? error.name || "Error" : "ToolError",
+      error_details: error instanceof Error ? error.message : String(error),
+      retry_count: this.maxRetries,
+      reflection_guidance: reflectionMessage
+    };
+    return response;
+  }
+};
+__name(_ReflectAndRetryToolPlugin, "ReflectAndRetryToolPlugin");
+let ReflectAndRetryToolPlugin = _ReflectAndRetryToolPlugin;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ReflectAndRetryToolPlugin
+});

package/dist/cjs/runner/runner.js

@@ -41,6 +41,7 @@ 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_session_artifact_service = require("../artifacts/session_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");
@@ -49,6 +50,7 @@ var import_tracing = require("../telemetry/tracing.js");
 var import_base_toolset = require("../tools/base_toolset.js");
 var import_logger = require("../utils/logger.js");
 var import_model_name = require("../utils/model_name.js");
+var import_redact_inline_data = require("../utils/redact_inline_data.js");
 var import_run_node_as_invocation = require("../workflow/run_node_as_invocation.js");
 /**
  * @license
@@ -56,7 +58,7 @@ var import_run_node_as_invocation = require("../workflow/run_node_as_invocation.
  * SPDX-License-Identifier: Apache-2.0
  */
 var _a;
-const RUNNER_SIGNATURE_SYMBOL = Symbol.for("google.adk.runner");
+const RUNNER_SIGNATURE_SYMBOL = /* @__PURE__ */ Symbol.for("google.adk.runner");
 function isRunner(obj) {
   return typeof obj === "object" && obj !== null && RUNNER_SIGNATURE_SYMBOL in obj && obj[RUNNER_SIGNATURE_SYMBOL] === true;
 }
@@ -163,7 +165,9 @@ const _Runner = class _Runner {
                 `Session lookup failed: appName must be provided in runner constructor (or via app.name)`
               );
             }
-            throw new Error(`Session not found: ${sessionId}`);
+            throw new Error(
+              `Session not found: ${sessionId} (appName=${this.appName}, userId=${userId})`
+            );
           }
           if (runConfig.supportCfc && (0, import_llm_agent.isLlmAgent)(this.agent)) {
             const modelName = this.agent.canonicalModel.model;
@@ -177,7 +181,7 @@ const _Runner = class _Runner {
             }
           }
           const invocationContext = new import_invocation_context.InvocationContext({
-            artifactService: this.artifactService ? new import_scoped_artifact_service.ScopedArtifactService(
+            artifactService: this.artifactService ? (0, import_session_artifact_service.isSessionArtifactService)(this.artifactService) ? this.artifactService : new import_scoped_artifact_service.ScopedArtifactService(
               this.artifactService,
               this.appName,
               userId,
@@ -191,6 +195,7 @@ const _Runner = class _Runner {
             session,
             userContent: newMessage,
             runConfig,
+            a2aMetadata: runConfig.a2aMetadata,
             pluginManager: this.pluginManager,
             abortSignal: params.abortSignal
           });
@@ -210,9 +215,8 @@ const _Runner = class _Runner {
             }
             if (runConfig.saveInputBlobsAsArtifacts) {
               newMessage = await this.saveArtifacts(
+                invocationContext.artifactService,
                 invocationContext.invocationId,
-                session.userId,
-                session.id,
                 newMessage
               );
               if ((_d = params.abortSignal) == null ? void 0 : _d.aborted) {
@@ -325,21 +329,15 @@ const _Runner = class _Runner {
    * Saves artifacts from the message parts and replaces the inline data with
    * a file name placeholder and optional file reference.
    *
+   * @param artifactService The session-scoped artifact service to save to.
    * @param invocationId The current invocation ID.
-   * @param userId The user ID of the session.
-   * @param sessionId The session ID of the session.
    * @param message The message containing parts to process.
    */
-  async saveArtifacts(invocationId, userId, sessionId, message) {
+  async saveArtifacts(artifactService, invocationId, message) {
     var _a2;
-    if (!this.artifactService || !((_a2 = message.parts) == null ? void 0 : _a2.length)) {
+    if (!artifactService || !((_a2 = message.parts) == null ? void 0 : _a2.length)) {
       return message;
     }
-    const sessionKey = {
-      appName: this.appName,
-      userId,
-      sessionId
-    };
     const newParts = [];
     let modified = false;
     for (let i = 0; i < message.parts.length; i++) {
@@ -351,20 +349,16 @@ const _Runner = class _Runner {
       try {
         const inlineData = part.inlineData;
         const fileName = inlineData.displayName || `artifact_${invocationId}_${i}`;
-        const version = await this.artifactService.saveArtifact({
-          ...sessionKey,
+        const version = await artifactService.saveArtifact({
           filename: fileName,
           artifact: part
         });
         newParts.push((0, import_genai.createPartFromText)(`[Uploaded Artifact: "${fileName}"]`));
         try {
-          const artifactVersion = await this.artifactService.getArtifactVersion(
-            {
-              ...sessionKey,
-              filename: fileName,
-              version
-            }
-          );
+          const artifactVersion = await artifactService.getArtifactVersion({
+            filename: fileName,
+            version
+          });
           if ((artifactVersion == null ? void 0 : artifactVersion.canonicalUri) && /^(gs|https?):/i.test(artifactVersion.canonicalUri)) {
             newParts.push({
               fileData: {
@@ -414,7 +408,7 @@ const _Runner = class _Runner {
    * Whether the agent to run can transfer to any other agent in the agent tree.
    *
    * @param agentToRun The agent to check for transferability.
-   * @returns True if the agent can transfer, False otherwise.
+   * @returns True if the agent can transfer, false otherwise.
    */
   isRoutableLlmAgent(agentToRun) {
     return isRoutableLlmAgent(agentToRun);
@@ -477,7 +471,7 @@ const _Runner = class _Runner {
             return;
           }
           const invocationContext = new import_invocation_context.InvocationContext({
-            artifactService: this.artifactService ? new import_scoped_artifact_service.ScopedArtifactService(
+            artifactService: this.artifactService ? (0, import_session_artifact_service.isSessionArtifactService)(this.artifactService) ? this.artifactService : new import_scoped_artifact_service.ScopedArtifactService(
               this.artifactService,
               this.appName,
               params.userId,
@@ -490,6 +484,7 @@ const _Runner = class _Runner {
             agent,
             session,
             runConfig,
+            a2aMetadata: runConfig.a2aMetadata,
             pluginManager: this.pluginManager,
             liveRequestQueue: params.liveRequestQueue,
             abortSignal: params.abortSignal,
@@ -567,6 +562,14 @@ 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 conflictingAuthors = (0, import_functions.getConflictingFunctionResponseAuthors)(
+      session.events
+    );
+    if (conflictingAuthors) {
+      throw new Error(
+        `Function responses in the last event resolve to function calls from more than one agent (at least "${conflictingAuthors[0]}" and "${conflictingAuthors[1]}"); cannot determine a single agent to resume.`
+      );
+    }
     const resumedAgent = rootAgent.findAgent(event.author);
     if (resumedAgent) {
       return resumedAgent;
@@ -578,7 +581,7 @@ function determineAgentForResumption(session, rootAgent, resumabilityConfig) {
     }
   }
   for (let i = session.events.length - 1; i >= 0; i--) {
-    import_logger.logger.debug("event:", JSON.stringify(session.events[i]));
+    import_logger.logger.debug("event:", (0, import_redact_inline_data.stringifyWithRedactedInlineData)(session.events[i]));
     const event2 = session.events[i];
     if (event2.author === "user" || !event2.author) {
       continue;