@google/adk 1.6.0 → 2.1.0

package/dist/types/plugins/_reflect_retry_utils.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export declare const REFLECT_AND_RETRY_RESPONSE_TYPE = "ERROR_HANDLED_BY_REFLECT_AND_RETRY_PLUGIN";
+export declare const GLOBAL_SCOPE_KEY = "__global_reflect_and_retry_scope__";
+/**
+ * Defines the lifecycle scope for tracking failure counts.
+ */
+export declare enum TrackingScope {
+    /** Track failures within the current agent invocation. */
+    INVOCATION = "invocation",
+    /** Track failures globally across all invocations. */
+    GLOBAL = "global"
+}
+/**
+ * A mapping from an item's (tool or model) name to its consecutive failure count.
+ */
+export type PerItemFailuresCounter = Map<string, number>;
+/**
+ * Response containing tool failure details and retry guidance.
+ *
+ * Field names use snake_case to match the model-facing reflection payload schema
+ * and maintain parity with ADK Python.
+ */
+export interface ToolFailureResponse {
+    response_type: string;
+    error_type: string;
+    error_details: string;
+    retry_count: number;
+    reflection_guidance: string;
+    [key: string]: unknown;
+}
+/**
+ * Resolves the scope key based on tracking scope and invocation ID.
+ *
+ * @param scope - The tracking scope (INVOCATION or GLOBAL).
+ * @param invocationId - The invocation ID (required for INVOCATION scope).
+ * @returns The resolved scope key string.
+ */
+export declare function resolveScopeKey(scope: TrackingScope, invocationId?: string): string;
+/**
+ * Thread-safe failure counter scoped by invocation or global key.
+ */
+export declare class ScopedFailureTracker {
+    private readonly scopedFailureCounters;
+    private lockPromise;
+    private acquireLock;
+    /**
+     * Atomically increments and returns the failure count for an item.
+     *
+     * @param scopeKey - The scope identifier (e.g. invocation ID or global key).
+     * @param itemName - The name of the tool or model.
+     * @returns The updated failure count.
+     */
+    increment(scopeKey: string, itemName: string): Promise<number>;
+    /**
+     * Atomically resets the failure count for an item and cleans up state.
+     *
+     * @param scopeKey - The scope identifier.
+     * @param itemName - The name of the tool or model.
+     */
+    reset(scopeKey: string, itemName: string): Promise<void>;
+    /**
+     * Gets the current failure count for an item.
+     *
+     * @param scopeKey - The scope identifier.
+     * @param itemName - The name of the tool or model.
+     */
+    getCount(scopeKey: string, itemName: string): Promise<number>;
+}

package/dist/types/plugins/base_plugin.d.ts

@@ -11,6 +11,8 @@ import { Event } from '../events/event.js';
 import { LlmRequest } from '../models/llm_request.js';
 import { LlmResponse } from '../models/llm_response.js';
 import { BaseTool } from '../tools/base_tool.js';
+import type { BaseNode } from '../workflow/base_node.js';
+import type { NodeContext } from '../workflow/node_context.js';
 /**
  * Trigger for context compaction.
  */
@@ -58,38 +60,40 @@ export declare enum ContextCompactionTrigger {
  * Example:
  * A simple plugin that logs every tool call.
  * ```typescript
+ * import {BasePlugin, BaseTool, Context, getLogger} from '@google/adk';
+ *
+ * const logger = getLogger();
+ *
  * class ToolLoggerPlugin extends BasePlugin {
  *   constructor() {
  *     super('tool_logger');
  *   }
  *
  *   override async beforeToolCallback(
- *     {tool, toolArgs, toolContext}: {
+ *     {tool, toolArgs}: {
  *       tool: BaseTool,
  *       toolArgs: Record<string, unknown>,
  *       toolContext: Context,
  *     },
  *   ): Promise<Record<string, unknown> | undefined> {
- *     this.logger.info(
- *       `[${this.name}] Calling tool '${tool.name}' with args:
- * ${JSON.stringify( toolArgs,
- *       )}`,
+ *     logger.info(
+ *       `[${this.name}] calling tool '${tool.name}' with args: ` +
+ *         JSON.stringify(toolArgs),
  *     );
  *     return;
  *   }
  *
  *   override async afterToolCallback(
- *     {tool, toolArgs, toolContext, result}: {
+ *     {tool, result}: {
  *       tool: BaseTool,
  *       toolArgs: Record<string, unknown>,
  *       toolContext: Context,
  *       result: Record<string, unknown>,
  *     },
  *   ): Promise<Record<string, unknown> | undefined> {
- *     this.logger.info(
- *       `[${this.name}] Tool '${tool.name}' finished with result:
- * ${JSON.stringify( result,
- *       )}`,
+ *     logger.info(
+ *       `[${this.name}] tool '${tool.name}' finished with result: ` +
+ *         JSON.stringify(result),
  *     );
  *     return;
  *   }
@@ -204,6 +208,39 @@ export declare abstract class BasePlugin {
         agent: BaseAgent;
         callbackContext: Context;
     }): Promise<Content | undefined>;
+    /**
+     * Callback executed before a workflow node runs.
+     *
+     * @param params.node The node that is about to run.
+     * @param params.nodeContext The node's execution context.
+     * @param params.input The input the node is about to receive.
+     * @returns An optional value. If anything other than `undefined` is returned,
+     *     the node's body is skipped and the returned value becomes its output,
+     *     which is how a plugin implements a node-level cache or a stub.
+     *     Returning `undefined` lets the node run normally.
+     */
+    beforeNodeCallback(params: {
+        node: BaseNode;
+        nodeContext: NodeContext;
+        input: unknown;
+    }): Promise<unknown>;
+    /**
+     * Callback executed after a workflow node has run.
+     *
+     * Not called for a node whose body was skipped by `beforeNodeCallback`, and
+     * not called when the node throws.
+     *
+     * @param params.node The node that has just run.
+     * @param params.nodeContext The node's execution context.
+     * @param params.output The output the node produced.
+     * @returns An optional value replacing the node's output. Returning
+     *     `undefined` keeps the original.
+     */
+    afterNodeCallback(params: {
+        node: BaseNode;
+        nodeContext: NodeContext;
+        output: unknown;
+    }): Promise<unknown>;
     /**
      * Callback executed before a request is sent to the model.
      *

package/dist/types/plugins/logging_plugin.d.ts

@@ -32,8 +32,9 @@ import { BasePlugin } from './base_plugin.js';
  * ```typescript
  * const loggingPlugin = new LoggingPlugin();
  * const runner = new Runner({
- *   agents: [myAgent],
- *   // ...
+ *   appName: 'my_app',
+ *   agent: myAgent,
+ *   sessionService: new InMemorySessionService(),
  *   plugins: [loggingPlugin],
  * });
  * ```

package/dist/types/plugins/plugin_manager.d.ts

@@ -11,6 +11,8 @@ import { Event } from '../events/event.js';
 import { LlmRequest } from '../models/llm_request.js';
 import { LlmResponse } from '../models/llm_response.js';
 import { BaseTool } from '../tools/base_tool.js';
+import type { BaseNode } from '../workflow/base_node.js';
+import type { NodeContext } from '../workflow/node_context.js';
 import { BasePlugin, ContextCompactionTrigger } from './base_plugin.js';
 /**
  * Manages the registration and execution of plugins.
@@ -28,6 +30,8 @@ import { BasePlugin, ContextCompactionTrigger } from './base_plugin.js';
  */
 export declare class PluginManager {
     private readonly plugins;
+    /** Whether any plugin is registered. */
+    get hasPlugins(): boolean;
     /**
      * Initializes the plugin service.
      *
@@ -103,6 +107,22 @@ export declare class PluginManager {
         agent: BaseAgent;
         callbackContext: Context;
     }): Promise<Content | undefined>;
+    /**
+     * Runs the `beforeNodeCallback` for all plugins.
+     */
+    runBeforeNodeCallback({ node, nodeContext, input, }: {
+        node: BaseNode;
+        nodeContext: NodeContext;
+        input: unknown;
+    }): Promise<unknown>;
+    /**
+     * Runs the `afterNodeCallback` for all plugins.
+     */
+    runAfterNodeCallback({ node, nodeContext, output, }: {
+        node: BaseNode;
+        nodeContext: NodeContext;
+        output: unknown;
+    }): Promise<unknown>;
     /**
      * Runs the `beforeToolSelection` for all plugins.
      */

package/dist/types/plugins/reflect_retry_model_plugin.d.ts

@@ -0,0 +1,132 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { FinishReason, Part } from '@google/genai';
+import { Context } from '../agents/context.js';
+import { LlmRequest } from '../models/llm_request.js';
+import { LlmResponse } from '../models/llm_response.js';
+import { TrackingScope } from './_reflect_retry_utils.js';
+import { BasePlugin } from './base_plugin.js';
+export declare const RESERVED_TOOL_CALL_ERROR_TYPE = "RESERVED_TOOL_CALL";
+export declare const ADK_HANDLE_MODEL_ERROR_TOOL_NAME = "adk_handle_model_error";
+/**
+ * Options for configuring {@link ReflectAndRetryModelPlugin}.
+ */
+export interface ReflectAndRetryModelPluginOptions {
+    /** Plugin instance identifier. Defaults to 'reflect_retry_model_plugin'. */
+    name?: string;
+    /** Maximum consecutive model failures before giving up (0 = no retries). Defaults to 3. */
+    maxRetries?: number;
+    /** If true, raises the exception when retry limit is reached. If false, returns response. Defaults to true. */
+    throwExceptionIfRetryExceeded?: boolean;
+    /** Determines the lifecycle of the error tracking state. Defaults to TrackingScope.INVOCATION. */
+    trackingScope?: TrackingScope;
+    /** A list of FinishReasons that should be treated as model errors. Defaults to [FinishReason.MALFORMED_FUNCTION_CALL]. */
+    onModelErrors?: FinishReason[];
+}
+/**
+ * Provides self-healing, concurrent-safe error recovery for model failures.
+ *
+ * This plugin intercepts model failures (such as `MALFORMED_FUNCTION_CALL`),
+ * provides structured guidance to the LLM for reflection and correction, and
+ * retries the turn up to a configurable limit.
+ *
+ * @example
+ * ```typescript
+ * import {ReflectAndRetryModelPlugin, TrackingScope} from '@google/adk';
+ *
+ * const modelRetryPlugin = new ReflectAndRetryModelPlugin({
+ *   maxRetries: 3,
+ *   trackingScope: TrackingScope.INVOCATION,
+ * });
+ * ```
+ */
+export declare class ReflectAndRetryModelPlugin extends BasePlugin {
+    readonly maxRetries: number;
+    readonly throwExceptionIfRetryExceeded: boolean;
+    readonly scope: TrackingScope;
+    readonly onModelErrors: FinishReason[];
+    private readonly tracker;
+    /**
+     * Initializes the {@link ReflectAndRetryModelPlugin}.
+     *
+     * @param options - Configuration options for the plugin.
+     */
+    constructor(options?: ReflectAndRetryModelPluginOptions);
+    /**
+     * Internal framework reflection tool handler.
+     */
+    adkHandleModelError({ retryCount, }: {
+        responseType?: string;
+        errorType?: string;
+        errorDetails?: string;
+        finishReason?: string;
+        retryCount?: number;
+    }): {
+        reflection_guidance: string;
+    };
+    /**
+     * Checks if the model response contains an error matching `onModelErrors`.
+     */
+    protected checkForModelError(llmResponse: LlmResponse): boolean;
+    /**
+     * Retrieves the model name from context.
+     */
+    protected getModelNameFromContext(callbackContext: Context): string;
+    /**
+     * Prepares the LLM request by attaching the reflection tool.
+     */
+    beforeModelCallback({ llmRequest, }: {
+        callbackContext: Context;
+        llmRequest: LlmRequest;
+    }): Promise<LlmResponse | undefined>;
+    /**
+     * Inspects LLM responses, intercepts model errors or reserved tool calls, and handles retries.
+     */
+    afterModelCallback({ callbackContext, llmResponse, }: {
+        callbackContext: Context;
+        llmResponse: LlmResponse;
+    }): Promise<LlmResponse | undefined>;
+    /**
+     * Provides the adk_handle_model_error tool for reflection and retries.
+     */
+    protected provideReflectionTool(llmRequest: LlmRequest): void;
+    /**
+     * Checks if the model response calls the reserved reflection tool.
+     */
+    protected hasReservedToolCall(llmResponse: LlmResponse): boolean;
+    /**
+     * Handles direct calls to the reserved reflection tool.
+     */
+    protected handleReservedToolCall(callbackContext: Context, _llmResponse: LlmResponse): Promise<LlmResponse | undefined>;
+    /**
+     * Handles detected model errors by initiating retry logic.
+     */
+    protected handleModelError(callbackContext: Context, llmResponse: LlmResponse): Promise<LlmResponse | undefined>;
+    /**
+     * Tracks retry count, generates retry response, and checks against limits.
+     */
+    protected handleModelRetry(callbackContext: Context, errorType?: string, errorDetails?: string, finishReason?: FinishReason): Promise<LlmResponse | undefined>;
+    /**
+     * Generates a function call part for the model retry tool.
+     */
+    protected generateModelRetryPart(retryCount: number, errorType?: string, errorDetails?: string, finishReason?: FinishReason): Part;
+    /**
+     * Generates a unique ID for the model retry tool call.
+     */
+    protected getModelRetryUuid(): string;
+    /**
+     * Returns the scope key for model failure tracking.
+     */
+    protected getModelScopeKey(callbackContext: Context): string;
+    /**
+     * Increment the failure count for a model within a scope.
+     */
+    protected incrementModelFailureCount(scopeKey: string, itemName: string): Promise<number>;
+    /**
+     * Reset the failure count for a model within a scope.
+     */
+    protected resetModelFailureCount(scopeKey: string, itemName: string): Promise<void>;
+}

package/dist/types/plugins/reflect_retry_tool_plugin.d.ts

@@ -0,0 +1,187 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Context } from '../agents/context.js';
+import { BaseTool } from '../tools/base_tool.js';
+import { TrackingScope } from './_reflect_retry_utils.js';
+import { BasePlugin } from './base_plugin.js';
+/**
+ * Options for configuring {@link ReflectAndRetryToolPlugin}.
+ */
+export interface ReflectAndRetryToolPluginOptions {
+    /**
+     * Plugin instance identifier.
+     * Defaults to 'reflect_retry_tool_plugin'.
+     */
+    name?: string;
+    /**
+     * Maximum consecutive failures before giving up (0 = no retries).
+     * Defaults to 3.
+     */
+    maxRetries?: number;
+    /**
+     * If true, raises the final exception when the retry limit is reached.
+     * If false, returns structured retry-exceeded guidance instead.
+     * Defaults to true.
+     */
+    throwExceptionIfRetryExceeded?: boolean;
+    /**
+     * Determines the lifecycle of the error tracking state.
+     * Defaults to `TrackingScope.INVOCATION` (tracking per-invocation).
+     */
+    trackingScope?: TrackingScope;
+}
+/**
+ * Provides self-healing, concurrent-safe error recovery for tool failures.
+ *
+ * This plugin intercepts tool failures, provides structured guidance to the LLM
+ * for reflection and correction, and retries the operation up to a configurable
+ * limit.
+ *
+ * **Key Features:**
+ * - **Concurrency Safe:** Uses locking to safely handle parallel tool executions.
+ * - **Configurable Scope:** Tracks failures per-invocation (default) or globally
+ *   using the {@link TrackingScope} enum.
+ * - **Extensible Scoping:** The `getScopeKey` method can be overridden to
+ *   implement custom tracking logic (e.g., per-user or per-session).
+ * - **Granular Tracking:** Failure counts are tracked per-tool within the defined
+ *   scope. A success with one tool resets its counter without affecting others.
+ * - **Custom Error Extraction:** Supports detecting errors in normal tool responses
+ *   that do not throw exceptions, by overriding `extractErrorFromResult`.
+ *
+ * @example
+ * ```typescript
+ * import {ReflectAndRetryToolPlugin, TrackingScope} from '@google/adk';
+ *
+ * // Example 1: Track failures per invocation (default)
+ * const errorPlugin = new ReflectAndRetryToolPlugin({maxRetries: 3});
+ *
+ * // Example 2: Track failures globally across all turns
+ * const globalPlugin = new ReflectAndRetryToolPlugin({
+ *   maxRetries: 5,
+ *   trackingScope: TrackingScope.GLOBAL,
+ * });
+ *
+ * // Example 3: Do not throw exception when retry limit is exceeded
+ * const softFailPlugin = new ReflectAndRetryToolPlugin({
+ *   maxRetries: 3,
+ *   throwExceptionIfRetryExceeded: false,
+ * });
+ * ```
+ */
+export declare class ReflectAndRetryToolPlugin extends BasePlugin {
+    readonly maxRetries: number;
+    readonly throwExceptionIfRetryExceeded: boolean;
+    readonly scope: TrackingScope;
+    private readonly tracker;
+    /**
+     * Initializes the {@link ReflectAndRetryToolPlugin}.
+     *
+     * @param options - Configuration options for the plugin.
+     */
+    constructor(options?: ReflectAndRetryToolPluginOptions);
+    /**
+     * 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.
+     */
+    afterToolCallback({ tool, toolArgs, toolContext, result, }: {
+        tool: BaseTool;
+        toolArgs: Record<string, unknown>;
+        toolContext: Context;
+        result: Record<string, unknown>;
+    }): Promise<Record<string, unknown> | undefined>;
+    /**
+     * 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.
+     */
+    extractErrorFromResult(params: {
+        tool: BaseTool;
+        toolArgs: Record<string, unknown>;
+        toolContext: Context;
+        result: unknown;
+    }): Promise<unknown | undefined>;
+    /**
+     * Handles tool exceptions by providing reflection guidance.
+     *
+     * @param params - The error callback parameters.
+     * @returns An optional record containing reflection guidance for the error.
+     */
+    onToolErrorCallback({ tool, toolArgs, toolContext, error, }: {
+        tool: BaseTool;
+        toolArgs: Record<string, unknown>;
+        toolContext: Context;
+        error: Error;
+    }): Promise<Record<string, unknown> | undefined>;
+    /**
+     * 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.
+     */
+    protected handleToolError(tool: BaseTool, toolArgs: Record<string, unknown>, toolContext: Context, error: unknown): Promise<Record<string, unknown> | undefined>;
+    /**
+     * 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.
+     */
+    protected getScopeKey(toolContext: Context): string;
+    /**
+     * Atomically resets the failure count for a tool and cleans up state.
+     *
+     * @param toolContext - The tool context.
+     * @param toolName - The name of the tool.
+     */
+    protected resetFailuresForTool(toolContext: Context, toolName: string): Promise<void>;
+    /**
+     * Ensures the given error is an Error instance, wrapping if not.
+     *
+     * @param error - The error object.
+     * @returns An Error instance.
+     */
+    protected ensureException(error: unknown): Error;
+    /**
+     * Formats error details for inclusion in the reflection message.
+     *
+     * @param error - The error object.
+     * @returns Formatted error string.
+     */
+    protected formatErrorDetails(error: unknown): string;
+    /**
+     * 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.
+     */
+    protected createToolReflectionResponse(tool: BaseTool, toolArgs: Record<string, unknown>, error: unknown, retryCount: number): Record<string, unknown>;
+    /**
+     * 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.
+     */
+    protected getToolRetryExceedMsg(tool: BaseTool, toolArgs: Record<string, unknown>, error: unknown): Record<string, unknown>;
+}

package/dist/types/plugins/security_plugin.d.ts

@@ -5,10 +5,11 @@
  */
 import { FunctionCall } from '@google/genai';
 import { Context } from '../agents/context.js';
+import { REQUEST_CONFIRMATION_FUNCTION_CALL_NAME } from '../agents/functions.js';
 import { Event } from '../events/event.js';
 import { BasePlugin } from '../plugins/base_plugin.js';
 import { BaseTool } from '../tools/base_tool.js';
-export declare const REQUEST_CONFIRMATION_FUNCTION_CALL_NAME = "adk_request_confirmation";
+export { REQUEST_CONFIRMATION_FUNCTION_CALL_NAME };
 /**
  * The outcome of a policy check.
  */
@@ -46,9 +47,10 @@ export declare class InMemoryPolicyEngine implements BasePolicyEngine {
     /**
      * Always returns {@link PolicyOutcome.ALLOW} for every tool call.
      *
+     * @param _context - The tool and its arguments; ignored.
      * @returns A promise resolving to an ALLOW result.
      */
-    evaluate(): Promise<PolicyCheckResult>;
+    evaluate(_context: ToolCallPolicyContext): Promise<PolicyCheckResult>;
 }
 /**
  *  Security Plugin for running Orcas agents.

package/dist/types/runner/in_memory_runner.d.ts

@@ -3,10 +3,10 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { BaseAgent } from '../agents/base_agent.js';
 import { App } from '../apps/app.js';
 import { ResumabilityConfig } from '../apps/resumability_config.js';
 import { BasePlugin } from '../plugins/base_plugin.js';
+import { RunnableRoot } from '../workflow/run_node_as_invocation.js';
 import { Runner } from './runner.js';
 /**
  * A {@link Runner} pre-configured with in-memory services.
@@ -40,7 +40,7 @@ export declare class InMemoryRunner extends Runner {
      */
     constructor(params: {
         app?: App;
-        agent?: BaseAgent;
+        agent?: RunnableRoot;
         appName?: string;
         plugins?: BasePlugin[];
         resumabilityConfig?: ResumabilityConfig;