@google/adk 2.3.0 → 2.5.0

package/dist/types/common.d.ts

@@ -9,6 +9,7 @@ export { BaseAgent, isBaseAgent } from './agents/base_agent.js';
 export type { AfterAgentCallback, BaseAgentConfig, BeforeAgentCallback, SingleAgentCallback, } from './agents/base_agent.js';
 export { Context } from './agents/context.js';
 export { REQUEST_CONFIRMATION_FUNCTION_CALL_NAME, REQUEST_CREDENTIAL_FUNCTION_CALL_NAME, REQUEST_INPUT_FUNCTION_CALL_NAME, findEventByFunctionCallId, findMatchingFunctionCall, functionsExportedForTestingOnly, handleFunctionCallsLive, isToolNotFound, } from './agents/functions.js';
+export { injectSessionState } from './agents/instructions.js';
 export { InvocationContext, LlmCallsLimitExceededError, isLlmCallsLimitExceededError, requireAgent, } from './agents/invocation_context.js';
 export type { InvocationContextParams, WorkflowInstructionScope, } from './agents/invocation_context.js';
 export { LangGraphAgent, getLastHumanMessages, isLangGraphAgent, } from './agents/langgraph_agent.js';
@@ -27,8 +28,6 @@ export { CONTENT_REQUEST_PROCESSOR, ContentRequestProcessor, } from './agents/pr
 export { ContextCompactorRequestProcessor } from './agents/processors/context_compactor_request_processor.js';
 export { INTERACTIONS_REQUEST_PROCESSOR, InteractionsRequestProcessor, } from './agents/processors/interactions_request_processor.js';
 export { ReadonlyContext } from './agents/readonly_context.js';
-export { RemoteAgent, isRemoteAgent } from './agents/remote_agent.js';
-export type { RemoteAgentConfig, RemoteAgentFetch, } from './agents/remote_agent.js';
 export { RoutedAgent, isRoutedAgent } from './agents/routed_agent.js';
 export type { AgentRouter, RoutedAgentConfig } from './agents/routed_agent.js';
 export { StreamingMode, createRunConfig } from './agents/run_config.js';
@@ -140,7 +139,9 @@ export type { AppendEventRequest, CreateSessionRequest, DeleteSessionRequest, Ge
 export { InMemorySessionService } from './sessions/in_memory_session_service.js';
 export { createSession } from './sessions/session.js';
 export type { CompositeSessionKey, Session } from './sessions/session.js';
+export { StaleSessionError, isStaleSessionError, } from './sessions/stale_session_error.js';
 export { State, StateSchemaError, isStateSchemaError } from './sessions/state.js';
+export type { ContentCapturingMode, ExperimentalFeature, TelemetryConfig, } from './telemetry/api/instrumentation.js';
 export { AgentTool, isAgentTool } from './tools/agent_tool.js';
 export type { AgentToolConfig } from './tools/agent_tool.js';
 export { BaseTool, isBaseTool } from './tools/base_tool.js';
@@ -148,6 +149,12 @@ export type { BaseToolParams, RunAsyncToolRequest, ToolProcessLlmRequest, } from
 export { BaseToolset, isBaseToolset } from './tools/base_toolset.js';
 export type { ToolPredicate } from './tools/base_toolset.js';
 export { BuiltInTool } from './tools/built_in_tool.js';
+export { BaseComputer, ComputerEnvironment, isBaseComputer, } from './tools/computer_use/base_computer.js';
+export type { ComputerState, ScrollDirection, } from './tools/computer_use/base_computer.js';
+export { ComputerUseTool, isComputerUseTool, } from './tools/computer_use/computer_use_tool.js';
+export type { ComputerUseFunction, ComputerUseToolOptions, } from './tools/computer_use/computer_use_tool.js';
+export { ComputerUseToolset, adaptComputerUseTool, isComputerUseToolset, } from './tools/computer_use/computer_use_toolset.js';
+export type { AdaptComputerUseToolParams, AdaptedComputerUseFunction, ComputerUseToolsetOptions, } from './tools/computer_use/computer_use_toolset.js';
 export { ConsolidateContextTool } from './tools/consolidate_context_tool.js';
 export { ENTERPRISE_WEB_SEARCH, EnterpriseWebSearchTool, } from './tools/enterprise_web_search_tool.js';
 export { ExampleTool } from './tools/example_tool.js';
@@ -187,12 +194,15 @@ export { getClientLabels, runWithClientLabel } from './utils/client_labels.js';
 export { toGeminiSchema } from './utils/gemini_schema_util.js';
 export type { MCPToolSchema } from './utils/gemini_schema_util.js';
 export { genaiSchemaToJsonSchema } from './utils/genai_schema_to_json.js';
+export { newId, resetIdProvider, setIdProvider } from './utils/id_provider.js';
+export type { IdProvider } from './utils/id_provider.js';
 export { LogLevel, getLogger, logger, resetLogger, setLogLevel, setLogger, } from './utils/logger.js';
 export type { Logger } from './utils/logger.js';
 export { isGemini2OrAbove, isGemini35LiveTranslate, isGemini3xFlashLive, isGemini3xLive, } from './utils/model_name.js';
 export { toJsonSchema } from './utils/schema.js';
 export type { SchemaLike } from './utils/schema.js';
-export { zodObjectToSchema } from './utils/simple_zod_to_json.js';
+export { isZodObject, isZodSchema, zodObjectToSchema, } from './utils/simple_zod_to_json.js';
+export type { ZodSchema } from './utils/simple_zod_to_json.js';
 export { Task } from './utils/task.js';
 export type { TaskExecutable } from './utils/task.js';
 export { GoogleLLMVariant } from './utils/variant_utils.js';
@@ -205,25 +215,18 @@ export { SearchSkillsTool } from './tools/skill/search_skills_tool.js';
 export * from './artifacts/base_artifact_service.js';
 export * from './features/feature_registry.js';
 export * from './memory/base_memory_service.js';
-export * from './sessions/base_session_service.js';
+export { mergeStates, trimTempDeltaState, trimTempState, } from './sessions/base_session_service.js';
 export * from './tools/base_tool.js';
-export { BaseNode, BranchPath, DEFAULT_ROUTE, Edge, FunctionNode, Graph, JoinNode, NodeContext, NodeReportedError, NodeSchemaValidationError, NodeStatus, NodeTimeoutError, NodeTool, ParallelWorker, RequestInput, START, ToolNode, Workflow, WorkflowNode, asRunnableRoot, commonPrefixOf, createNodeErrorEvent, createNodeState, createSubBranch, isNodeErrorEvent, isNodeReportedError, isNodeSchemaValidationError, isNodeState, isNodeTimeoutError, isRequestInput, isRunnableRoot, isWorkflow, node, normalizeRetryExceptions, prepareRetryConfig, } from './workflow/index.js';
+export { BaseNode, BranchPath, DEFAULT_ROUTE, Edge, FunctionNode, Graph, JoinNode, NodeContext, NodeReportedError, NodeSchemaValidationError, NodeStatus, NodeTimeoutError, NodeTool, ParallelWorker, RequestInput, START, ToolNode, Workflow, WorkflowNode, asRunnableRoot, commonPrefixOf, createNodeErrorEvent, createNodeState, createSubBranch, isNodeErrorEvent, isNodeReportedError, isNodeSchemaValidationError, isNodeState, isNodeTimeoutError, isParallelWorker, isRequestInput, isRunnableRoot, isWorkflow, node, normalizeRetryExceptions, prepareRetryConfig, } from './workflow/index.js';
 export type { BaseNodeConfig, BuildNodeOptions, ChainElement, CreateNodeErrorEventParams, DynamicEntry, EdgeItem, ErrorClass, FunctionNodeConfig, FunctionNodeHandler, FunctionNodeResult, NodeContextOptions, NodeErrorEvent, NodeLike, NodeOptions, NodeResult, NodeState, ParallelWorkerConfig, PreparedRetryConfig, RequestInputParams, RetryConfig, RouteValue, RoutingMap, RunNodeOptions, RunnableNode, RunnableRoot, ScheduleDynamicNode, ScheduleDynamicNodeOptions, ToolNodeConfig, WorkflowConfig, } from './workflow/index.js';
 export { App, isApp, validateAppName } from './apps/app.js';
 export type { AppOptions } from './apps/app.js';
-export * from './artifacts/base_artifact_service.js';
-export * from './features/feature_registry.js';
-export * from './memory/base_memory_service.js';
-export * from './sessions/base_session_service.js';
-export * from './tools/base_tool.js';
-export { convertSessionToEvalFormat, createEmptyState, } from './cli/utils/evals.js';
-export type { EvaluationItem, IntermediateAgentResponseItem, ToolUseItem, } from './cli/utils/evals.js';
-export { CrewaiTool, isCrewaiTool } from './tools/crewai_tool.js';
-export type { CrewaiSchemaLike, CrewaiToolConfig, CrewaiToolLike, } from './tools/crewai_tool.js';
+export { RUNNER_CLEANUP_TIMEOUT_MS, closeRunners } from './cli/utils/cleanup.js';
+export { convertSessionToEvalFormat, convertSessionToEvalInvocations, createEmptyState, } from './cli/utils/evals.js';
+export type { EvalCase, EvalIntermediateData, EvalInvocation, EvalSessionInput, EvalSet, EvaluationItem, IntermediateAgentResponseItem, ToolUseItem, } from './cli/utils/evals.js';
 export { buildFunctionDeclarationForLangchain, buildFunctionDeclarationForParamsForCrewai, buildFunctionDeclarationUtil, } from './tools/function_tool.js';
 export type { CallLiveToolRequest } from './tools/function_tool.js';
-export { LangchainTool, isLangchainTool } from './tools/langchain_tool.js';
-export type { LangchainSchemaLike, LangchainToolConfig, LangchainToolLike, } from './tools/langchain_tool.js';
+export type { LoadMemoryResponse, LoadMemoryToolOptions, } from './tools/load_memory_tool.js';
 export { isBaseRetrievalTool } from './tools/retrieval/base_retrieval_tool.js';
-export { ToolboxTool, isToolboxTool } from './tools/toolbox_tool.js';
-export type { ToolboxClientLike, ToolboxToolOptions, } from './tools/toolbox_tool.js';
+export { ToolboxToolset, isToolboxToolset } from './tools/toolbox_toolset.js';
+export type { ToolboxLoadOptions, ToolboxToolLike, ToolboxToolsetClientLike, ToolboxToolsetOptions, } from './tools/toolbox_toolset.js';

package/dist/types/context/compaction_utils.d.ts

@@ -24,7 +24,19 @@ export declare function isEventVisibleInIsolationScope(event: Event, currentIsol
  * Determines the baseline index to retain from active raw events,
  * ensuring we don't split between a function call and its response.
  *
- * @param rawEvents The active raw events to consider for compaction.
+ * Two checks protect a pair, mirroring the two places that can otherwise
+ * observe half of it:
+ * - Adjacent pairs: while the event before the split contains a function call
+ *   and the event at the split contains a function response, move the split
+ *   earlier.
+ * - Non-adjacent pairs: extend the retained tail back to the nearest preceding
+ *   call for every retained response ID, following any dependencies that
+ *   extension exposes. This matches the content builder, which pairs calls and
+ *   responses by ID alone after filtering by scope and branch, so a call on a
+ *   sub-agent branch answered by an unbranched user response is still kept.
+ *
+ * @param rawEvents The active raw events to consider for compaction. They are
+ *   already filtered to the caller's isolation scope.
  * @param eventRetentionSize The minimum number of raw events to keep at the end of the session.
  * @returns The index in `rawEvents` at which to split. Events before this index will be compacted.
  */

package/dist/types/errors/input_validation_error.d.ts

@@ -9,6 +9,7 @@
 export declare class InputValidationError extends Error {
     /**
      * @param message A message describing why the input is invalid.
+     * @param options Standard error options, e.g. `{cause}`.
      */
-    constructor(message?: string);
+    constructor(message?: string, options?: ErrorOptions);
 }

package/dist/types/events/event.d.ts

@@ -201,6 +201,9 @@ export declare function pruneThoughts(event: Event): Event;
 export declare function isEvent(obj: unknown): obj is Event;
 /**
  * Generates a new unique ID for the event.
+ *
+ * The ID comes from the provider set with `setIdProvider`, or is 8 random
+ * alphanumeric characters when none is set.
  */
 export declare function createNewEventId(): string;
 /**

package/dist/types/features/feature_registry.d.ts

@@ -7,6 +7,7 @@
  * Feature names.
  */
 export declare enum FeatureName {
+    COMPUTER_USE = "COMPUTER_USE",
     PROGRESSIVE_SSE_STREAMING = "PROGRESSIVE_SSE_STREAMING"
 }
 /**

package/dist/types/index.d.ts

@@ -22,6 +22,7 @@ export { VertexAiRagMemoryService } from './memory/vertex_ai_rag_memory_service.
 export type { VertexAiRagMemoryServiceOptions } from './memory/vertex_ai_rag_memory_service.js';
 export { DebugLoggingPlugin, isDebugLoggingPlugin, } from './plugins/debug_logging_plugin.js';
 export { DatabaseSessionService } from './sessions/database_session_service.js';
+export type { DatabaseSessionServiceOptions } from './sessions/database_session_service.js';
 export { getSessionServiceFromUri } from './sessions/registry.js';
 export { VertexAiSessionService } from './sessions/vertex_ai_session_service.js';
 export type { VertexAiCreateSessionRequest, VertexAiSessionServiceOptions, } from './sessions/vertex_ai_session_service.js';
@@ -34,9 +35,10 @@ export { SecretManagerClient, type SecretManagerClientOptions, } from './tools/a
 export { ApplicationIntegrationToolset, type ApplicationIntegrationToolsetOptions, } from './tools/application_integration_tool/application_integration_toolset.js';
 export { actionRequest, actionResponse, ConnectionsClient, CONNECTOR_BASE_SPEC, connectorPayload, createOperation, createOperationRequest, deleteOperation, deleteOperationRequest, executeCustomQueryRequest, getActionOperation, getOperation, getOperationRequest, listOperation, listOperationRequest, updateOperation, updateOperationRequest, type ActionSchema, type ConnectionDetails, type ConnectionsClientOptions, type ConnectorSpec, type EntityOperationOptions, type EntitySchemaAndOperations, type EntitySchemaOperationOptions, type GetActionOperationOptions, } from './tools/application_integration_tool/clients/connections_client.js';
 export { IntegrationClient, type IntegrationClientOptions, } from './tools/application_integration_tool/clients/integration_client.js';
+export { IntegrationConnectorTool, type IntegrationConnectorToolOptions, } from './tools/application_integration_tool/integration_connector_tool.js';
 export { LOAD_WEB_PAGE, loadWebPage } from './tools/load_web_page.js';
 export type { LoadWebPageOptions } from './tools/load_web_page.js';
-export { credentialToParam, dictToAuthScheme, INTERNAL_AUTH_PREFIX, openidDictToSchemeCredential, openidUrlToSchemeCredential, serviceAccountDictToSchemeCredential, serviceAccountSchemeCredential, tokenToSchemeCredential, } from './tools/openapi_tool/auth/auth_helpers.js';
+export { credentialToParam, INTERNAL_AUTH_PREFIX, openidRecordToSchemeCredential, openidUrlToSchemeCredential, recordToAuthScheme, serviceAccountRecordToSchemeCredential, serviceAccountSchemeCredential, tokenToSchemeCredential, } from './tools/openapi_tool/auth/auth_helpers.js';
 export type { OpenIdConfig } from './tools/openapi_tool/auth/auth_helpers.js';
 export { AutoAuthCredentialExchanger } from './tools/openapi_tool/auth/credential_exchangers/auto_auth_credential_exchanger.js';
 export type { CustomCredentialExchangers } from './tools/openapi_tool/auth/credential_exchangers/auto_auth_credential_exchanger.js';
@@ -62,12 +64,15 @@ export { RunSkillScriptTool } from './tools/skill/run_skill_script_tool.js';
 export { SkillToolset } from './tools/skill/skill_toolset.js';
 export type { JsonObject } from './utils/json_utils.js';
 export * from './integrations/agent_registry/agent_registry.js';
-export * from './telemetry/google_cloud.js';
-export * from './telemetry/setup.js';
+export { runWithAgentEngineContext } from './telemetry/export/agent_engine.js';
+export { agentRuntimeRequestHooks, type AgentRuntimeRequestHooks, } from './telemetry/export/agent_runtime.js';
+export * from './telemetry/export/google_cloud.js';
+export * from './telemetry/export/setup.js';
 export * from './tools/google_api_tool/index.js';
-export { DEFAULT_CRITERIA, EVAL_SESSION_ID_PREFIX, EvalStatus, getEvaluationCriteriaOrDefault, getRootAgent, MISSING_EVAL_DEPENDENCIES_MESSAGE, parseAndGetEvalsToRun, RESPONSE_EVALUATION_SCORE_KEY, RESPONSE_MATCH_SCORE_KEY, runEvals, TOOL_TRAJECTORY_SCORE_KEY, tryGetResetFunc, } from './cli/cli_eval.js';
-export type { AddSessionToEvalSetRequest, EvalEntry, EvalInitialSession, EvalMetric, EvalMetricResult, EvalResult, EvalSetItem, InvocationEvalMetricResult, RunEvalRequest, RunEvalResult, RunEvalsOptions, } from './cli/cli_eval.js';
+export { convertEvalSetToSchema, DEFAULT_CRITERIA, EVAL_SESSION_ID_PREFIX, EvalStatus, getEvaluationCriteriaOrDefault, getRootAgent, loadEvalSetFromFile, LocalEvalSetResultsManager, LocalEvalSetsManager, MISSING_EVAL_DEPENDENCIES_MESSAGE, normalizeEvalCase, parseAndGetEvalsToRun, RESPONSE_EVALUATION_SCORE_KEY, RESPONSE_MATCH_SCORE_KEY, runEvals, TOOL_TRAJECTORY_SCORE_KEY, tryGetResetFunc, } from './cli/cli_eval.js';
+export type { AddSessionToEvalSetRequest, EvalCaseResult, EvalEntry, EvalInitialSession, EvalMetric, EvalMetricResult, EvalResult, EvalSetItem, EvalSetResult, InvocationEvalMetricResult, RunEvalRequest, RunEvalResult, RunEvalsOptions, SaveEvalSetResultParams, } from './cli/cli_eval.js';
 export { loadDotenvForAgent, walkToRootUntilFound } from './cli/utils/envs.js';
-export { LOGGING_FORMAT, logToStderr, logToTmpFolder } from './cli/utils/logs.js';
+export { LOGGING_FORMAT, logToTmpFolder, setupAdkLogger, } from './cli/utils/logs.js';
 export type { LogToTmpFolderOptions } from './cli/utils/logs.js';
+export { validatePathSegment } from './cli/utils/path_validation.js';
 export * from './tools/mcp/index.js';

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

@@ -139,9 +139,9 @@ export declare abstract class BasePlugin {
      *
      * @param _params.invocationContext The context for the entire invocation, containing
      *     session information, the root agent, etc.
-     * @returns An optional `Event` to be returned to the ADK. Returning a value
-     *     to halt execution of the runner and ends the runner with that event.
-     *     Return `undefined` to proceed normally.
+     * @returns An optional `Content` to be returned to the ADK. Returning a value
+     *     halts execution of the runner and ends the run with an event containing
+     *     that content. Return `undefined` to proceed normally.
      */
     beforeRunCallback(_params: {
         invocationContext: InvocationContext;
@@ -165,10 +165,12 @@ export declare abstract class BasePlugin {
         event: Event;
     }): Promise<Event | undefined>;
     /**
-     * Callback executed after an ADK runner run has completed.
+     * Callback executed after successful completion, abort, or early iterator close.
      *
      * This is the final callback in the ADK lifecycle, suitable for cleanup,
-     * final logging, or reporting tasks.
+     * final logging, or reporting tasks. It is skipped when execution fails;
+     * {@link onRunErrorCallback} is called instead. Receiving this callback does
+     * not imply success: recognized cancellation still propagates to the caller.
      *
      * @param _params.invocationContext The context for the entire invocation.
      * @returns undefined
@@ -176,6 +178,28 @@ export declare abstract class BasePlugin {
     afterRunCallback(_params: {
         invocationContext: InvocationContext;
     }): Promise<void>;
+    /**
+     * Observes an error escaping an agent's execution or lifecycle callbacks.
+     *
+     * Notification-only: return values are ignored and callback failures are
+     * logged. The original execution error always propagates.
+     */
+    onAgentErrorCallback(_params: {
+        agent: BaseAgent;
+        callbackContext: Context;
+        error: Error;
+    }): Promise<void>;
+    /**
+     * Observes an error in the run lifecycle, including before/after-run callbacks.
+     *
+     * Notification-only: return values are ignored and callback failures are
+     * logged. The original execution error always propagates. A completion-hook
+     * failure during early iterator close is reported but does not prevent closing.
+     */
+    onRunErrorCallback(_params: {
+        invocationContext: InvocationContext;
+        error: Error;
+    }): Promise<void>;
     /**
      * Callback executed before an agent's primary logic is invoked.
      *
@@ -195,14 +219,14 @@ export declare abstract class BasePlugin {
     /**
      * Callback executed after an agent's primary logic has completed.
      *
-     * This callback can be used to inspect, log, or modify the agent's final
-     * result before it is returned.
+     * This callback can be used to inspect, log, or append an additional event
+     * after the agent's execution completes.
      *
      * @param _params.agent The agent that has just run.
      * @param _params.callbackContext The context for the agent invocation.
-     * @returns An optional `Content` object. If a value is returned, it will
-     *     replace the agent's original result. Returning `undefined` uses the
-     *     original, unmodified result.
+     * @returns An optional `Content` object. If a value is returned, it will be
+     *     emitted as an additional event appended after the agent's execution.
+     *     Returning `undefined` emits no additional content event.
      */
     afterAgentCallback(_params: {
         agent: BaseAgent;
@@ -250,8 +274,8 @@ export declare abstract class BasePlugin {
      *
      * @param _params.callbackContext The context for the current agent call.
      * @param _params.llmRequest The prepared request object to be sent to the model.
-     * @returns An optional value. The interpretation of a non-`undefined`
-     *     trigger an early exit and returns the response immediately. Returning
+     * @returns An optional `LlmResponse`. Returning a non-`undefined` value
+     *     triggers an early exit and returns that response immediately. Returning
      *     `undefined` allows the LLM request to proceed normally.
      */
     beforeModelCallback(_params: {
@@ -275,7 +299,7 @@ export declare abstract class BasePlugin {
         llmResponse: LlmResponse;
     }): Promise<LlmResponse | undefined>;
     /**
-     * Callback executed when a model call encounters an error.
+     * Callback executed when a model call encounters an `Error`.
      *
      * This callback provides an opportunity to handle model errors gracefully,
      * potentially providing alternative responses or recovery mechanisms.
@@ -283,10 +307,11 @@ export declare abstract class BasePlugin {
      * @param _params.callbackContext The context for the current agent call.
      * @param _params.llmRequest The request that was sent to the model when the error
      *     occurred.
-     * @param _params.error The exception that was raised during model execution.
-     * @returns An optional LlmResponse. If an LlmResponse is returned, it will be
-     *     used instead of propagating the error. Returning `undefined` allows
-     *     the original error to be raised.
+     * @param _params.error The `Error` instance thrown during model execution.
+     * @returns An optional `LlmResponse`. If an `LlmResponse` is returned, it
+     *     will be used instead of the default error response. Returning
+     *     `undefined` causes an error response/event with `errorCode` and
+     *     `errorMessage` derived from `error` to be yielded.
      */
     onModelErrorCallback(_params: {
         callbackContext: Context;
@@ -376,17 +401,8 @@ export declare abstract class BasePlugin {
         result: Record<string, unknown>;
     }): Promise<Record<string, unknown> | undefined>;
     /**
-     * Callback executed when a tool call encounters an error.
-      tool: BaseTool;
-      toolArgs: Record<string, unknown>;
-      toolContext: Context;
-      result: Record<string, unknown>;
-    }): Promise<Record<string, unknown> | undefined> {
-      return;
-    }
-  
-    /**
-     * Callback executed when a tool call encounters an error.
+     * Callback executed when a tool call encounters an `Error` or cannot be
+     * resolved.
      *
      * This callback provides an opportunity to handle tool errors gracefully,
      * potentially providing alternative responses or recovery mechanisms.
@@ -394,10 +410,13 @@ export declare abstract class BasePlugin {
      * @param _params.tool The tool instance that encountered an error.
      * @param _params.toolArgs The arguments that were passed to the tool.
      * @param _params.toolContext The context specific to the tool execution.
-     * @param _params.error The exception that was raised during tool execution.
+     * @param _params.error The `Error` that was raised during tool resolution or
+     *     execution.
      * @returns An optional dictionary. If a dictionary is returned, it will be
-     *     used as the tool response instead of propagating the error. Returning
-     *     `undefined` allows the original error to be raised.
+     *     used as the tool response instead of the default error response.
+     *     Returning `undefined` causes `{error: error.message}` to be returned as
+     *     the tool response (unlike adk-python, which re-raises). Non-`Error`
+     *     throwables bypass this callback and become `{error: thrownValue}`.
      */
     onToolErrorCallback(_params: {
         tool: BaseTool;

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

@@ -67,6 +67,19 @@ export declare class PluginManager {
      *     the proper type for the plugin method.
      */
     private runCallbacks;
+    /** Notifies every plugin without allowing one failure to hide another. */
+    private runNotificationCallbacks;
+    /** Runs the notification-only agent error callback for every plugin. */
+    runOnAgentErrorCallback(params: {
+        agent: BaseAgent;
+        callbackContext: Context;
+        error: Error;
+    }): Promise<void>;
+    /** Runs the notification-only run error callback for every plugin. */
+    runOnRunErrorCallback(params: {
+        invocationContext: InvocationContext;
+        error: Error;
+    }): Promise<void>;
     /**
      * Runs the `onUserMessageCallback` for all plugins.
      */

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

@@ -177,6 +177,16 @@ export declare class Runner {
         abortSignal?: AbortSignal;
         customMetadata?: Record<string, unknown>;
     }): AsyncGenerator<Event, void, undefined>;
+    /**
+     * Closes the runner and cleans up all toolsets reachable from the root agent
+     * or workflow.
+     */
+    close(): Promise<void>;
+    private runAsyncWithPlugins;
+    /** Finalizes a started run, including when its consumer closes the iterator. */
+    private runWithPluginLifecycle;
+    private finishRun;
+    private notifyRunError;
     /**
      * Runs whatever this runner was given as its root.
      *
@@ -260,6 +270,7 @@ export declare class Runner {
         abortSignal?: AbortSignal;
         liveSessionResumptionHandle?: string;
     }): AsyncGenerator<Event, void, undefined>;
+    private runLiveWithPlugins;
 }
 /**
  * Determines the next agent to run to continue the session. This is primarily

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

@@ -139,6 +139,11 @@ export declare abstract class BaseSessionService {
      */
     private updateSessionState;
 }
+/**
+ * Places `event` into `session.events`, replacing the entry with the same id
+ * if one is already there and appending it otherwise.
+ */
+export declare function upsertSessionEvent(session: Session, event: Event): void;
 /**
  * Removes temporary state delta keys from the event.
  */
@@ -151,8 +156,6 @@ export declare function trimTempDeltaState(event: Event): Event;
  * and `JSON.parse` makes `__proto__` an own key, so copying it into a plain
  * object literal would invoke the inherited `__proto__` setter: the entry is
  * dropped and the new state object is re-parented onto the attacker's object.
- * `State.get`/`State.has` use the `in` operator, so every key on that object
- * would then read back as session state.
  */
 export declare function trimTempState(state: Record<string, unknown>): Record<string, unknown>;
 /**

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

@@ -7,6 +7,21 @@ 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';
+export { isStaleSessionError, StaleSessionError } from './stale_session_error.js';
+/**
+ * Options for configuring {@link DatabaseSessionService}.
+ */
+export interface DatabaseSessionServiceOptions extends MikroDBOptions {
+    /**
+     * How to handle stale sessions in {@link DatabaseSessionService.appendEvent}.
+     *
+     * - `'reject'` (default): throws a {@link StaleSessionError} without persisting changes.
+     * - `'reload'`: reloads stored events and state into the session object after writing.
+     *
+     * @deprecated 'reload' is deprecated and will be removed in a future release. Use 'reject' (the default) and re-read the session with `getSession` to retry.
+     */
+    staleSession?: 'reject' | 'reload';
+}
 /**
  * Checks if a URI is a database connection URI.
  *
@@ -22,7 +37,8 @@ export declare class DatabaseSessionService extends BaseSessionService {
     private initialized;
     private options?;
     private connectionString?;
-    constructor(connectionStringOrOptions: MikroDBOptions | string);
+    private readonly staleSession;
+    constructor(connectionStringOrOptions: DatabaseSessionServiceOptions | string, options?: DatabaseSessionServiceOptions);
     init(): Promise<void>;
     createSession({ appName, userId, state, sessionId, }: CreateSessionRequest): Promise<Session>;
     getSession({ appName, userId, sessionId, config, }: GetSessionRequest): Promise<Session | undefined>;

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

@@ -25,7 +25,8 @@ export type MikroORMOptions = Partial<Options>;
  */
 export declare function getConnectionOptionsFromUri(uri: string): Promise<MikroORMOptions>;
 /**
- * Creates a database and tables if they don't exist.
+ * Creates a database and any missing entity tables without altering existing
+ * tables.
  *
  * @param orm The MikroORM instance.
  * @returns Promise<void>

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

@@ -9,12 +9,14 @@ 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.
+ * Fractional-second digits requested for stored session, state, and event
+ * timestamp columns.
  *
  * 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.
+ * value and rounds session `update_time` up across a second boundary. 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 {

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

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+declare const STALE_SESSION_ERROR_SIGNATURE_SYMBOL: unique symbol;
+/**
+ * Error thrown when a session write loses an optimistic concurrency race.
+ */
+export declare class StaleSessionError extends Error {
+    readonly [STALE_SESSION_ERROR_SIGNATURE_SYMBOL] = true;
+    constructor(message: string);
+}
+/**
+ * Type guard for {@link StaleSessionError}.
+ *
+ * @param obj The value to check.
+ * @returns True if obj is a {@link StaleSessionError}.
+ */
+export declare function isStaleSessionError(obj: unknown): obj is StaleSessionError;
+export {};

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

@@ -9,7 +9,7 @@ import { Frontmatter, Skill } from './skill.js';
  *
  * @param content - The raw content of the SKILL.md file.
  * @returns An object containing the parsed frontmatter and the remaining markdown body.
- * @throws {Error} If the content is not properly formatted with YAML frontmatter.
+ * @throws {InputValidationError} If the content is not properly formatted with YAML frontmatter.
  */
 export declare function parseSkillMdContent(content: string): {
     frontmatter: Frontmatter;
@@ -44,7 +44,8 @@ export declare function loadAllSkillsInDir(skillsBasePath: string): Promise<Reco
  *
  * @param zipBuffer - The raw Buffer of the zip file containing the skill.
  * @returns A Skill object with all components loaded.
- * @throws {Error} If a member name is a traversal path, if SKILL.md is missing,
+ * @throws {NotFoundError} If the archive has no SKILL.md.
+ * @throws {InputValidationError} If a member name is a traversal path,
  * or if the skill name is missing or is not a bare path segment.
  */
 export declare function loadSkillFromZipBuffer(zipBuffer: Buffer): Skill;