@google/adk 2.0.0 → 2.2.0

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/runner/runner.d.ts

@@ -10,6 +10,7 @@ import { RunConfig } from '../agents/run_config.js';
 import { App } from '../apps/app.js';
 import { ResumabilityConfig } from '../apps/resumability_config.js';
 import { BaseArtifactService } from '../artifacts/base_artifact_service.js';
+import { SessionArtifactService } from '../artifacts/session_artifact_service.js';
 import { BaseCredentialService } from '../auth/credential_service/base_credential_service.js';
 import { Event } from '../events/event.js';
 import { BaseMemoryService } from '../memory/base_memory_service.js';
@@ -37,8 +38,7 @@ export interface RunnerConfig {
      * A bare node — a `Workflow`, most usefully — is accepted as the root and
      * driven directly, so a graph does not have to be wrapped by hand to be run.
      * The accepted set is the one an edge takes: any other node-like value
-     * becomes the single node of a one-node workflow. Mirrors adk-python, whose
-     * `Runner.agent` is typed `BaseNode`.
+     * becomes the single node of a one-node workflow.
      */
     agent?: RunnableNode;
     /**
@@ -48,7 +48,7 @@ export interface RunnerConfig {
     /**
      * An optional service for storing and retrieving artifacts.
      */
-    artifactService?: BaseArtifactService;
+    artifactService?: BaseArtifactService | SessionArtifactService;
     /**
      * The service for managing sessions.
      */
@@ -111,7 +111,7 @@ export declare class Runner {
      */
     readonly agent: RunnableRoot;
     readonly pluginManager: PluginManager;
-    readonly artifactService?: BaseArtifactService;
+    readonly artifactService?: BaseArtifactService | SessionArtifactService;
     readonly sessionService: BaseSessionService;
     readonly memoryService?: BaseMemoryService;
     readonly credentialService?: BaseCredentialService;
@@ -175,9 +175,8 @@ export declare 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.
      */
     private saveArtifacts;
@@ -194,7 +193,7 @@ export declare 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.
      */
     private isRoutableLlmAgent;
     /**
@@ -242,7 +241,7 @@ export declare function determineAgentForResumption(session: Session, rootAgent:
  *    `disallowTransferToParent` set to false).
  *
  * @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.
  */
 export declare function isRoutableLlmAgent(agentToRun: BaseAgent): boolean;
 /**

package/dist/types/sessions/database_session_service.d.ts

@@ -3,7 +3,7 @@
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { Options as MikroDBOptions } from '@mikro-orm/core';
+import type { MikroORMOptions as MikroDBOptions } from './db/operations.js';
 import { Event } from '../events/event.js';
 import { AppendEventRequest, BaseSessionService, CreateSessionRequest, DeleteSessionRequest, GetSessionRequest, ListSessionsRequest, ListSessionsResponse } from './base_session_service.js';
 import { Session } from './session.js';

package/dist/types/sessions/db/operations.d.ts

@@ -3,10 +3,22 @@
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { MikroORM, Options as MikroORMOptions } from '@mikro-orm/core';
+import type { MikroORM, Options } from '@mikro-orm/core';
+/**
+ * The user-facing MikroORM config shape. Since v7 `Options` marks every key
+ * that has a default as required, so a partial config has to be described as
+ * `Partial<Options>`.
+ */
+export type MikroORMOptions = Partial<Options>;
 /**
  * Parses a database connection URI and returns MikroORM Options.
  *
+ * Dialect drivers are imported dynamically so that installing `@google/adk`
+ * does not pull in five database drivers. Adding a dialect here therefore also
+ * means adding it to core's `peerDependencies` and to dev's `dependencies` (see
+ * "Dependency declarations" in CONTRIBUTING.md);
+ * `tests/integration/lazy_load_db_drivers/driver_manifest_test.ts` enforces it.
+ *
  * @param uri The database connection URI (e.g., "postgres://user:password@host:port/database")
  * @returns MikroORM Options configured for the database
  * @throws Error if the URI is invalid or unsupported

package/dist/types/sessions/db/schema.d.ts

@@ -3,38 +3,50 @@
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { PrimaryKey } from '@mikro-orm/core';
+import { EntitySchema, type Opt, PrimaryKeyProp } from '@mikro-orm/core';
 import { Event } from '../../events/event.js';
 export declare const SCHEMA_VERSION_KEY = "schema_version";
 export declare const SCHEMA_VERSION_1_JSON = "1";
 export declare const STORAGE_KEY_COLUMN_LENGTH = 191;
+/**
+ * Fractional-second digits requested for the stored event timestamp.
+ *
+ * MySQL and MariaDB round a `datetime` column to whole seconds unless a
+ * precision is given. That collapses events written in the same second onto one
+ * value and leaves their order undefined. Other backends are unaffected:
+ * PostgreSQL already defaults to six digits and SQLite ignores the precision.
+ */
+export declare const EVENT_TIMESTAMP_PRECISION = 6;
 export declare class StorageMetadata {
     key: string;
     value: string;
 }
+export declare const storageMetadataSchema: EntitySchema<StorageMetadata, never, import("@mikro-orm/core").EntityCtor<StorageMetadata>>;
 export declare class StorageAppState {
     appName: string;
     state: Record<string, unknown>;
-    updateTime: Date;
+    updateTime: Opt<Date>;
 }
+export declare const storageAppStateSchema: EntitySchema<StorageAppState, never, import("@mikro-orm/core").EntityCtor<StorageAppState>>;
 export declare class StorageUserState {
-    [PrimaryKey.name]?: [string, string] | undefined;
     appName: string;
     userId: string;
     state: Record<string, unknown>;
-    updateTime: Date;
+    updateTime: Opt<Date>;
+    [PrimaryKeyProp]?: ['appName', 'userId'];
 }
+export declare const storageUserStateSchema: EntitySchema<StorageUserState, never, import("@mikro-orm/core").EntityCtor<StorageUserState>>;
 export declare class StorageSession {
-    [PrimaryKey.name]?: [string, string, string] | undefined;
     id: string;
     appName: string;
     userId: string;
     state: Record<string, unknown>;
-    createTime: Date;
-    updateTime: Date;
+    createTime: Opt<Date>;
+    updateTime: Opt<Date>;
+    [PrimaryKeyProp]?: ['id', 'appName', 'userId'];
 }
+export declare const storageSessionSchema: EntitySchema<StorageSession, never, import("@mikro-orm/core").EntityCtor<StorageSession>>;
 export declare class StorageEvent {
-    [PrimaryKey.name]?: [string, string, string, string] | undefined;
     id: string;
     appName: string;
     userId: string;
@@ -42,5 +54,7 @@ export declare class StorageEvent {
     invocationId: string;
     timestamp: Date;
     eventData: Event;
+    [PrimaryKeyProp]?: ['id', 'appName', 'userId', 'sessionId'];
 }
-export declare const ENTITIES: (typeof StorageMetadata | typeof StorageAppState | typeof StorageEvent)[];
+export declare const storageEventSchema: EntitySchema<StorageEvent, never, import("@mikro-orm/core").EntityCtor<StorageEvent>>;
+export declare const ENTITIES: (EntitySchema<StorageMetadata, never, import("@mikro-orm/core").EntityCtor<StorageMetadata>> | EntitySchema<StorageAppState, never, import("@mikro-orm/core").EntityCtor<StorageAppState>> | EntitySchema<StorageUserState, never, import("@mikro-orm/core").EntityCtor<StorageUserState>> | EntitySchema<StorageSession, never, import("@mikro-orm/core").EntityCtor<StorageSession>> | EntitySchema<StorageEvent, never, import("@mikro-orm/core").EntityCtor<StorageEvent>>)[];

package/dist/types/skills/skill_registry.d.ts

@@ -26,4 +26,12 @@ export interface SkillRegistry {
      * Returns the description for the search_skills tool.
      */
     searchToolDescription?(): string | undefined;
+    /**
+     * Releases resources held by the registry, such as network clients or
+     * temporary credentials.
+     *
+     * Optional: registries that hold no resources may omit it. `SkillToolset`
+     * invokes it, when present, from its own `close()`.
+     */
+    close?(): Promise<void>;
 }

package/dist/types/tools/base_tool.d.ts

@@ -33,6 +33,17 @@ export interface BaseToolParams {
  * Defined once and shared by all BaseTool instances.
  */
 declare const BASE_TOOL_SIGNATURE_SYMBOL: unique symbol;
+/**
+ * Marks a tool the model runs itself rather than the framework — see
+ * `BuiltInTool`. Such a tool claims its name in the `toolsDict` only so a
+ * function call naming it can be routed, so a genuinely callable tool of the
+ * same name takes precedence over it.
+ */
+export declare const IN_MODEL_TOOL_SYMBOL: unique symbol;
+/**
+ * Whether `tool` is one the model runs itself.
+ */
+export declare function isInModelTool(tool: unknown): boolean;
 /**
  * Type guard to check if an object is an instance of BaseTool.
  * @param obj The object to check.

package/dist/types/tools/base_toolset.d.ts

@@ -65,10 +65,9 @@ export declare abstract class BaseToolset {
      *   process the llm request. e.g. ComputerUseToolset can add computer use
      *   tool to the llm request.
      *
-     * @param toolContext The context of the tool.
-     * @param llmRequest The outgoing LLM request, mutable this method.
+     * @param _toolContext The context of the tool.
+     * @param _llmRequest The outgoing LLM request, mutable this method.
      */
-    processLlmRequest(toolContext: Context, // eslint-disable-line @typescript-eslint/no-unused-vars
-    llmRequest: LlmRequest): Promise<void>;
+    processLlmRequest(_toolContext: Context, _llmRequest: LlmRequest): Promise<void>;
 }
 export {};

package/dist/types/tools/built_in_tool.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BaseTool, IN_MODEL_TOOL_SYMBOL, ToolProcessLlmRequest } from './base_tool.js';
+/**
+ * A tool the model runs itself. It is switched on through request parameters
+ * — Google Search, URL context, the grounding and retrieval tools — and never
+ * executes here.
+ *
+ * Such a tool has no function declaration, so `BaseTool.processLlmRequest`
+ * returns before the line that registers it in `llmRequest.toolsDict`. That
+ * left the model primed with a name the framework could not route: a model
+ * that returns one as an explicit function call, rather than running it,
+ * produced a call that failed to resolve even though the user had registered
+ * the tool. Registering the name here keeps the call resolvable, and
+ * `runAsync` answers it by telling the model the tool is not callable.
+ *
+ * A tool whose `applyBuiltInConfig` returns without configuring anything —
+ * every one of them does when the request carries no model — still claims its
+ * name. That request never reaches a model, so no function call can come back
+ * for it and the registration is inert.
+ */
+export declare abstract class BuiltInTool extends BaseTool {
+    /** Marks this tool as one the model runs itself. */
+    readonly [IN_MODEL_TOOL_SYMBOL] = true;
+    /**
+     * Adds this tool's configuration to the request.
+     *
+     * @param request The request to process the LLM request.
+     */
+    protected abstract applyBuiltInConfig(request: ToolProcessLlmRequest): Promise<void>;
+    processLlmRequest(request: ToolProcessLlmRequest): Promise<void>;
+    /**
+     * Answers a function call the model should not have made. The tool is
+     * already configured on the request and its results arrive as grounding
+     * metadata, so the model is told to use those rather than call again.
+     */
+    runAsync(): Promise<unknown>;
+}

package/dist/types/tools/enterprise_web_search_tool.d.ts

@@ -1,5 +1,6 @@
 import { LlmRequest } from '../models/llm_request.js';
-import { BaseTool, ToolProcessLlmRequest } from './base_tool.js';
+import { ToolProcessLlmRequest } from './base_tool.js';
+import { BuiltInTool } from './built_in_tool.js';
 /**
  * Appends the Enterprise Web Search built-in tool to the LLM request when the
  * target model supports it.
@@ -15,10 +16,9 @@ export declare function applyEnterpriseWebSearch(llmRequest: LlmRequest): void;
  * This tool operates internally within the model and does not require or
  * perform local code execution.
  */
-export declare class EnterpriseWebSearchTool extends BaseTool {
+export declare class EnterpriseWebSearchTool extends BuiltInTool {
     constructor();
-    runAsync(): Promise<unknown>;
-    processLlmRequest({ llmRequest, }: ToolProcessLlmRequest): Promise<void>;
+    protected applyBuiltInConfig({ llmRequest, }: ToolProcessLlmRequest): Promise<void>;
 }
 /**
  * A global instance of {@link EnterpriseWebSearchTool}.

package/dist/types/tools/forwarding_artifact_service.d.ts

@@ -4,21 +4,34 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { Part } from '@google/genai';
-import { ArtifactVersion, BaseArtifactService, DeleteArtifactRequest, ListArtifactKeysRequest, ListVersionsRequest, LoadArtifactRequest, SaveArtifactRequest } from '../artifacts/base_artifact_service.js';
+import { ArtifactVersion } from '../artifacts/base_artifact_service.js';
+import { SessionArtifactService, SessionLoadArtifactRequest, SessionSaveArtifactRequest } from '../artifacts/session_artifact_service.js';
 import { Context } from '../agents/context.js';
+/**
+ * A unique symbol to identify session-scoped artifact services.
+ *
+ * Resolves to the same symbol as the one used by `isSessionArtifactService` in
+ * `session_artifact_service.ts` because `Symbol.for` looks up the global
+ * symbol registry.
+ */
+declare const SESSION_ARTIFACT_SERVICE_SIGNATURE_SYMBOL: unique symbol;
 /**
  * Artifact service that forwards to the parent tool context.
  */
-export declare class ForwardingArtifactService implements BaseArtifactService {
+export declare class ForwardingArtifactService implements SessionArtifactService {
     private readonly toolContext;
-    private readonly invocationContext;
+    /**
+     * Brands this class as a session-scoped artifact service.
+     */
+    readonly [SESSION_ARTIFACT_SERVICE_SIGNATURE_SYMBOL] = true;
     constructor(toolContext: Context);
-    saveArtifact(request: SaveArtifactRequest): Promise<number>;
-    loadArtifact(request: LoadArtifactRequest): Promise<Part | undefined>;
-    listArtifactKeys(_request: ListArtifactKeysRequest): Promise<string[]>;
+    saveArtifact(request: SessionSaveArtifactRequest): Promise<number>;
+    loadArtifact(request: SessionLoadArtifactRequest): Promise<Part | undefined>;
+    listArtifactKeys(): Promise<string[]>;
     private getArtifactService;
-    deleteArtifact(request: DeleteArtifactRequest): Promise<void>;
-    listVersions(request: ListVersionsRequest): Promise<number[]>;
-    listArtifactVersions(request: ListVersionsRequest): Promise<ArtifactVersion[]>;
-    getArtifactVersion(request: LoadArtifactRequest): Promise<ArtifactVersion | undefined>;
+    deleteArtifact(filename: string): Promise<void>;
+    listVersions(filename: string): Promise<number[]>;
+    listArtifactVersions(filename: string): Promise<ArtifactVersion[]>;
+    getArtifactVersion(request: SessionLoadArtifactRequest): Promise<ArtifactVersion | undefined>;
 }
+export {};