@google/adk 2.2.0 → 2.3.0

package/dist/types/cli/cli_eval.d.ts

@@ -0,0 +1,173 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BaseAgent } from '../agents/base_agent.js';
+import { BaseArtifactService } from '../artifacts/base_artifact_service.js';
+import { BaseSessionService } from '../sessions/base_session_service.js';
+import { EvaluationItem } from './utils/evals.js';
+/**
+ * Error message when evaluation dependencies are missing.
+ */
+export declare const MISSING_EVAL_DEPENDENCIES_MESSAGE = "Eval module is not installed, please install via `pip install google-adk[eval]`.";
+/**
+ * Metric key for average tool trajectory score.
+ */
+export declare const TOOL_TRAJECTORY_SCORE_KEY = "tool_trajectory_avg_score";
+/**
+ * Metric key for response match (ROUGE-1) score.
+ */
+export declare const RESPONSE_MATCH_SCORE_KEY = "response_match_score";
+/**
+ * Metric key for LLM-based response evaluation score.
+ */
+export declare const RESPONSE_EVALUATION_SCORE_KEY = "response_evaluation_score";
+/**
+ * Prefix applied to session IDs generated during evaluation runs.
+ */
+export declare const EVAL_SESSION_ID_PREFIX = "___eval___session___";
+/**
+ * Default evaluation criteria thresholds when no config file is supplied.
+ */
+export declare const DEFAULT_CRITERIA: Record<string, number>;
+/**
+ * Outcome status of an evaluation metric or case.
+ */
+export declare enum EvalStatus {
+    PASSED = 1,
+    FAILED = 2,
+    NOT_EVALUATED = 3
+}
+/**
+ * An evaluation metric definition and its pass threshold.
+ */
+export interface EvalMetric {
+    metric_name: string;
+    threshold: number;
+}
+/**
+ * Result of evaluating a single metric.
+ */
+export interface EvalMetricResult extends EvalMetric {
+    score?: number;
+    eval_status: EvalStatus;
+}
+/**
+ * Per-invocation evaluation metric breakdown.
+ */
+export interface InvocationEvalMetricResult {
+    actual_invocation: EvaluationItem;
+    expected_invocation: EvaluationItem;
+    eval_metric_results: EvalMetricResult[];
+}
+/**
+ * Complete evaluation result for a single eval case in an evalset.
+ */
+export interface EvalResult {
+    eval_set_file: string;
+    eval_id: string;
+    final_eval_status: EvalStatus;
+    eval_metric_results: Array<[EvalMetric, EvalMetricResult]>;
+    overall_eval_metric_results: EvalMetricResult[];
+    eval_metric_result_per_invocation: InvocationEvalMetricResult[];
+    session_id: string;
+    user_id?: string;
+}
+/**
+ * Request payload for adding a session to an eval set (`add_session`).
+ */
+export interface AddSessionToEvalSetRequest {
+    evalId: string;
+    sessionId: string;
+    userId: string;
+}
+/**
+ * Request payload for running evaluations on an eval set (`run_eval`).
+ */
+export interface RunEvalRequest {
+    evalIds: string[];
+    evalMetrics: EvalMetric[];
+}
+/**
+ * Result returned for a single evaluation case by the `run_eval` endpoint.
+ */
+export interface RunEvalResult extends EvalResult {
+    evalSetFile: string;
+    evalSetId: string;
+    evalId: string;
+    finalEvalStatus: EvalStatus;
+    evalMetricResults: Array<[EvalMetric, EvalMetricResult]>;
+    overallEvalMetricResults: EvalMetricResult[];
+    evalMetricResultPerInvocation: InvocationEvalMetricResult[];
+    userId?: string;
+    sessionId: string;
+}
+/**
+ * Initial session metadata for an evaluation case.
+ */
+export interface EvalInitialSession {
+    state?: Record<string, unknown>;
+    app_name?: string;
+    user_id?: string;
+}
+/**
+ * A named evaluation case within an evalset file.
+ */
+export interface EvalEntry {
+    name: string;
+    data: EvaluationItem[];
+    initial_session?: EvalInitialSession;
+}
+/**
+ * Alias for a single evaluation case entry in an evalset.
+ */
+export type EvalSetItem = EvalEntry;
+/**
+ * Options for running evaluations via `runEvals`.
+ */
+export interface RunEvalsOptions {
+    evalCasesByEvalSetId: Record<string, EvalEntry[] | string[]>;
+    rootAgent: BaseAgent;
+    resetFunc?: () => void | Promise<void>;
+    evalMetrics?: EvalMetric[];
+    printDetailedResults?: boolean;
+    sessionService?: BaseSessionService;
+    artifactService?: BaseArtifactService;
+}
+/**
+ * Loads evaluation criteria from a JSON config file, or returns `DEFAULT_CRITERIA`
+ * if no path is supplied.
+ *
+ * @param evalConfigFilePath Optional path to a `test_config.json` file.
+ * @returns Map of metric names to numeric thresholds.
+ */
+export declare function getEvaluationCriteriaOrDefault(evalConfigFilePath?: string): Record<string, number>;
+/**
+ * Dynamically imports an agent module and returns its `rootAgent`.
+ *
+ * @param agentModuleFilePath File or directory path to the agent module.
+ * @returns The loaded `BaseAgent` instance.
+ */
+export declare function getRootAgent(agentModuleFilePath: string): Promise<BaseAgent>;
+/**
+ * Attempts to retrieve an optional `reset_data` or `resetData` function from
+ * the agent module.
+ *
+ * @param agentModuleFilePath File or directory path to the agent module.
+ * @returns The reset function if exported, or `undefined`.
+ */
+export declare function tryGetResetFunc(agentModuleFilePath: string): Promise<(() => void | Promise<void>) | undefined>;
+/**
+ * Parses CLI evalset file arguments of the form `file_path` or
+ * `file_path:eval_1,eval_2` into a mapping from file path to requested eval IDs.
+ *
+ * @param evalSetFilePaths Array of evalset file specifications.
+ * @returns Mapping of evalset file path to list of eval case names.
+ */
+export declare function parseAndGetEvalsToRun(evalSetFilePaths: string[]): Record<string, string[]>;
+/**
+ * Runs a collection of evaluation cases against `rootAgent` and yields an
+ * `EvalResult` for each case.
+ */
+export declare function runEvals(optionsOrMap: RunEvalsOptions | Record<string, EvalEntry[] | string[]>, rootAgentArg?: BaseAgent, resetFuncArg?: () => void | Promise<void>, evalMetricsArg?: EvalMetric[], printDetailedResultsArg?: boolean, sessionServiceArg?: BaseSessionService, artifactServiceArg?: BaseArtifactService): AsyncGenerator<EvalResult, void, void>;

package/dist/types/cli/utils/envs.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Walks up the directory tree starting from `folder` until `filename` is found,
+ * or until the filesystem root is reached.
+ *
+ * @param folder The directory to start searching from.
+ * @param filename The file name to look for. Defaults to `'.env'`.
+ * @returns The absolute path to the found file, or `''` if not found.
+ */
+export declare function walkToRootUntilFound(folder: string, filename?: string): string;
+/**
+ * Walks up from the agent directory to the root directory and loads the first
+ * `.env` file found into `process.env` with override semantics.
+ *
+ * @param agentName The name or path of the agent.
+ * @param agentParentFolder The parent directory containing the agent. Defaults to `'.'`.
+ * @param filename The dotenv filename to search for. Defaults to `'.env'`.
+ */
+export declare function loadDotenvForAgent(agentName: string, agentParentFolder?: string, filename?: string): void;

package/dist/types/cli/utils/evals.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Part } from '@google/genai';
+import { BaseAgent } from '../../agents/base_agent.js';
+import { Session } from '../../sessions/session.js';
+/**
+ * Represents a single expected tool invocation in an evaluation item.
+ */
+export interface ToolUseItem {
+    tool_name: string;
+    tool_input: Record<string, unknown>;
+    mock_tool_output?: unknown;
+}
+/**
+ * Represents an intermediate agent response tuple of `[author, parts]`.
+ */
+export type IntermediateAgentResponseItem = [string, Part[]];
+/**
+ * Represents a single turn in an evaluation dataset converted from a session.
+ */
+export interface EvaluationItem {
+    query: string;
+    expected_tool_use: ToolUseItem[];
+    expected_intermediate_agent_responses: IntermediateAgentResponseItem[];
+    reference: string;
+}
+/**
+ * Converts a session into a list of evaluation items suitable for saving into
+ * an evalset or running through `runEvals`.
+ *
+ * @param session The session whose events should be converted.
+ * @returns An array of `EvaluationItem` records, one per user turn.
+ */
+export declare function convertSessionToEvalFormat(session?: Session): EvaluationItem[];
+/**
+ * Creates a state object initialized with empty strings `''` for all `{var}`
+ * placeholders referenced in the instruction strings of `agent` and its
+ * sub-agents, overridden by any keys provided in `initializedStates`.
+ *
+ * @param agent The root agent to inspect.
+ * @param initializedStates Optional pre-initialized state values that take precedence.
+ * @returns The combined state record.
+ */
+export declare function createEmptyState(agent: BaseAgent, initializedStates?: Record<string, unknown>): Record<string, unknown>;

package/dist/types/cli/utils/logs.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { LogLevel } from '../../utils/logger.js';
+/**
+ * Standard log format template for CLI log output.
+ */
+export declare const LOGGING_FORMAT = "%(asctime)s - %(levelname)s - %(filename)s:%(lineno)d - %(message)s";
+/**
+ * Options for configuring `logToTmpFolder`.
+ */
+export interface LogToTmpFolderOptions {
+    /** Minimum log level to record. Defaults to `LogLevel.INFO`. */
+    level?: LogLevel;
+    /** Subdirectory inside the system temp folder. Defaults to `'agents_log'`. */
+    subFolder?: string;
+    /** Prefix for generated log files. Defaults to `'agent'`. */
+    logFilePrefix?: string;
+    /** Timestamp suffix for the log filename. Defaults to `YYYYMMDD_HHMMSS`. */
+    logFileTimestamp?: string;
+}
+/**
+ * Configures the global ADK logger to write formatted log records to `stderr`.
+ *
+ * @param level The minimum `LogLevel` to emit. Defaults to `LogLevel.INFO`.
+ */
+export declare function logToStderr(level?: LogLevel): void;
+/**
+ * Configures the global ADK logger to write formatted log records to a timestamped
+ * file in the system temporary directory and updates the `<prefix>.latest.log`
+ * symlink to point to the newest file.
+ *
+ * @param options Configuration options for the temporary log file.
+ * @returns The absolute path to the created log file.
+ */
+export declare function logToTmpFolder(options?: LogToTmpFolderOptions): string;

package/dist/types/code_executors/code_execution_utils.d.ts

@@ -90,6 +90,29 @@ export interface CodeExecutionResult {
  * @return The file content as a base64-encoded bytes.
  */
 export declare function getEncodedFileContent(data: string): string;
+/**
+ * Gets the language of the code in a block from the block's leading delimiter.
+ *
+ * @param leadingDelimiter The leading delimiter of a code block, for example
+ *     '```javascript\n'.
+ * @return The language that the fence tag names, or
+ *     `CodeExecutionLanguage.UNSPECIFIED` for a tag that is not known. The
+ *     executor decides what to do with an unspecified language.
+ */
+export declare function getCodeBlockLanguage(leadingDelimiter: string): CodeExecutionLanguage;
+/**
+ * A code block extracted from a model response.
+ */
+export interface ExtractedCodeBlock {
+    /**
+     * The code in the block, or an empty string if there is no block.
+     */
+    code: string;
+    /**
+     * The language of the code, from the fence that matched it.
+     */
+    language: CodeExecutionLanguage;
+}
 /**
  * Extracts the first code block from the content and truncate everything after
  * it.
@@ -100,6 +123,22 @@ export declare function getEncodedFileContent(data: string): string;
  * @return The first code block if found, otherwise an empty string.
  */
 export declare function extractCodeAndTruncateContent(content: Content, codeBlockDelimiters: Array<[string, string]>): string;
+/**
+ * Extracts the first code block and its language from the content, and
+ * truncates everything after it.
+ *
+ * An `executableCode` part holds Python. A code block in text has the
+ * language of the fence tag in its leading delimiter: see
+ * {@link getCodeBlockLanguage}.
+ *
+ * @param content The mutable content to extract the code from.
+ * @param codeBlockDelimiters The list of the enclosing delimiters to identify
+ *     the code blocks.
+ * @return The first code block and its language. With no code block, the
+ *     code is an empty string and the language is
+ *     `CodeExecutionLanguage.UNSPECIFIED`.
+ */
+export declare function extractCodeBlockAndTruncateContent(content: Content, codeBlockDelimiters: Array<[string, string]>): ExtractedCodeBlock;
 /**
  * Builds an executable code part with code string.
  *

package/dist/types/code_executors/code_executor_context.d.ts

@@ -1,5 +1,6 @@
 import { State } from '../sessions/state.js';
 import { File } from './code_execution_utils.js';
+export declare const CONTEXT_KEY = "_code_execution_context";
 /**
  * The parameters for updating the code execution result.
  * */

package/dist/types/common.d.ts

@@ -8,9 +8,11 @@ export type { ActiveStreamingToolParams } from './agents/active_streaming_tool.j
 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, isToolNotFound, } from './agents/functions.js';
-export { InvocationContext, requireAgent } from './agents/invocation_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 { 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';
+export type { CompiledGraphLike, LangGraphAIMessage, LangGraphAgentConfig, LangGraphContentPart, LangGraphHumanMessage, LangGraphInvokeInput, LangGraphInvokeOutput, LangGraphMessageContent, LangGraphMessageLike, LangGraphRunnableConfig, LangGraphStateSnapshot, LangGraphSystemMessage, } from './agents/langgraph_agent.js';
 export { LiveRequestQueue } from './agents/live_request_queue.js';
 export type { LiveRequest } from './agents/live_request_queue.js';
 export { LlmAgent as Agent, LlmAgent, isLlmAgent } from './agents/llm_agent.js';
@@ -20,13 +22,16 @@ export type { LoopAgentConfig } from './agents/loop_agent.js';
 export { ParallelAgent, isParallelAgent } from './agents/parallel_agent.js';
 export { AgentTransferLlmRequestProcessor } from './agents/processors/agent_transfer_llm_request_processor.js';
 export { BaseLlmRequestProcessor, BaseLlmResponseProcessor, } from './agents/processors/base_llm_processor.js';
+export { CodeExecutionResponseProcessor } from './agents/processors/code_execution_request_processor.js';
 export { CONTENT_REQUEST_PROCESSOR, ContentRequestProcessor, } from './agents/processors/content_request_processor.js';
 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 } from './agents/run_config.js';
+export { StreamingMode, createRunConfig } from './agents/run_config.js';
 export type { RunConfig } from './agents/run_config.js';
 export { SequentialAgent, isSequentialAgent } from './agents/sequential_agent.js';
 export type { TranscriptionEntry } from './agents/transcription_entry.js';
@@ -44,7 +49,7 @@ export type { AuthCredential, HttpAuth, HttpCredentials, OAuth2Auth, ServiceAcco
 export { AuthHandler } from './auth/auth_handler.js';
 export { AUTH_PREPROCESSOR, AuthPreprocessor } from './auth/auth_preprocessor.js';
 export { AuthProviderRegistry } from './auth/auth_provider_registry.js';
-export { OAuthGrantType } from './auth/auth_schemes.js';
+export { AuthSchemeType, OAuthGrantType, getOAuthGrantTypeFromFlow, } from './auth/auth_schemes.js';
 export type { AuthScheme, OpenIdConnectWithConfig } from './auth/auth_schemes.js';
 export type { AuthConfig } from './auth/auth_tool.js';
 export type { BaseAuthProvider } from './auth/base_auth_provider.js';
@@ -87,6 +92,7 @@ export { createEvent, generateClientFunctionCallId, getFunctionCalls, getFunctio
 export type { CreateEventParams, Event, NodeInfo, Route, RouteKey, } from './events/event.js';
 export { createEventActions } from './events/event_actions.js';
 export type { EventActions } from './events/event_actions.js';
+export { INTERNAL_METADATA_PREFIX, RESTORED_EVENT_KEY, markRestored, publicEvent, publicMetadata, publicSession, } from './events/internal_metadata.js';
 export { EventType, toStructuredEvents } from './events/structured_events.js';
 export type { ActivityEvent, CallCodeEvent, CodeResultEvent, ContentEvent, ErrorEvent, FinishedEvent, StructuredEvent, ThoughtEvent, ToolCallEvent, ToolConfirmationEvent, ToolResultEvent, } from './events/structured_events.js';
 export { BaseExampleProvider, isBaseExampleProvider, } from './examples/base_example_provider.js';
@@ -103,7 +109,9 @@ export { ChromeBuiltInLlm, ChromeModelUnavailableError, stripAdkIdentityPreamble
 export type { ChromeBuiltInDiagnostic, ChromeBuiltInLlmParams, ChromeCreateCoreOptions, ChromeCreateMonitor, ChromeCreateOptions, ChromeExpectedModality, ChromeLanguageModelFactory, ChromeLanguageModelSession, ChromeMessage, ChromeMessageContent, ChromeModelAvailability, ChromePromptOptions, } from './models/chrome_prompt_llm.js';
 export { Gemini, geminiInitParams } from './models/google_llm.js';
 export type { GeminiParams } from './models/google_llm.js';
+export { appendInstructions } from './models/llm_request.js';
 export type { LlmRequest } from './models/llm_request.js';
+export { createLlmResponse } from './models/llm_response.js';
 export type { LlmResponse } from './models/llm_response.js';
 export { LLMRegistry } from './models/registry.js';
 export type { BaseLlmType } from './models/registry.js';
@@ -114,6 +122,7 @@ export { BuiltInPlanner, isBuiltInPlanner } from './planners/built_in_planner.js
 export { PlanReActPlanner } from './planners/plan_re_act_planner.js';
 export { GLOBAL_SCOPE_KEY, REFLECT_AND_RETRY_RESPONSE_TYPE, ScopedFailureTracker, TrackingScope, resolveScopeKey, type PerItemFailuresCounter, type ToolFailureResponse, } from './plugins/_reflect_retry_utils.js';
 export { BasePlugin, ContextCompactionTrigger } from './plugins/base_plugin.js';
+export type { DebugEntry, DebugLoggingPluginOptions, InvocationDebugState, } from './plugins/debug_logging_plugin.js';
 export { GlobalInstructionPlugin } from './plugins/global_instruction_plugin.js';
 export { LoggingPlugin } from './plugins/logging_plugin.js';
 export { PluginManager } from './plugins/plugin_manager.js';
@@ -121,6 +130,8 @@ export { ADK_HANDLE_MODEL_ERROR_TOOL_NAME, RESERVED_TOOL_CALL_ERROR_TYPE, Reflec
 export { ReflectAndRetryToolPlugin, type ReflectAndRetryToolPluginOptions, } from './plugins/reflect_retry_tool_plugin.js';
 export { InMemoryPolicyEngine, PolicyOutcome, SecurityPlugin, getAskUserConfirmationFunctionCalls, } from './plugins/security_plugin.js';
 export type { BasePolicyEngine, PolicyCheckResult, ToolCallPolicyContext, } from './plugins/security_plugin.js';
+export { ToolCallIntegrityError, ToolCallIntegrityPlugin, } from './plugins/tool_call_integrity_plugin.js';
+export type { ToolCallIntegrityPluginOptions } from './plugins/tool_call_integrity_plugin.js';
 export { InMemoryRunner } from './runner/in_memory_runner.js';
 export { Runner, determineAgentForResumption, findEventByLastFunctionResponseId, isRoutableLlmAgent, isRunner, } from './runner/runner.js';
 export type { RunnerConfig } from './runner/runner.js';
@@ -173,9 +184,13 @@ export type { WebMCPDocument, WebMCPExecuteToolOptions, WebMCPGetToolsOptions, W
 export { AsyncQueue } from './utils/async_queue.js';
 export { renameReservedKeywords, toSnakeCaseName } from './utils/case_utils.js';
 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 { 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 { Task } from './utils/task.js';
@@ -201,3 +216,14 @@ 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 { 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 { 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';

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

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Event } from './event.js';
+export declare const INVOCATION_ABORTED = "INVOCATION_ABORTED";
+export declare const ABORT_MESSAGE = "Invocation was aborted by client.";
+/**
+ * Returns whether `event` was synthesized to seal an aborted invocation.
+ */
+export declare function isAbortEvent(event: Event): boolean;
+/** Parameters for {@link buildAbortEvents}. */
+export interface BuildAbortEventsParams {
+    /** The session history, in chronological order. */
+    events: Event[];
+    /** The aborted invocation; only its events are considered. */
+    invocationId: string;
+    /** Author of the abort event returned when nothing is dangling. */
+    rootAgentName: string;
+    /**
+     * Branch for calls whose event has no branch, and for the abort event
+     * returned when nothing is dangling.
+     */
+    branch?: string;
+}
+/**
+ * Returns the events that seal an aborted invocation.
+ *
+ * Each dangling function call gets a synthetic error response carrying the
+ * author, branch and isolation scope of the event that issued it, so the
+ * response pairs with its call in the issuing agent's own view. Calls sharing
+ * those three values are grouped into one event. If nothing is dangling, a
+ * single content-less abort event authored by the root agent is returned
+ * instead.
+ *
+ * Long-running calls (including confirmation and credential requests) are
+ * sealed too: the invocation that issued them is gone, so they are not left
+ * pending for a later turn.
+ *
+ * @returns The synthetic events, in the order they should be appended.
+ */
+export declare function buildAbortEvents({ events, invocationId, rootAgentName, branch, }: BuildAbortEventsParams): Event[];

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

@@ -178,6 +178,10 @@ export declare function hasTrailingCodeExecutionResult(event: Event): boolean;
 export declare function stringifyContent(event: Event): string;
 /**
  * Estimates the number of tokens in the event based on usage metadata or characters.
+ *
+ * Prefers `initialPromptTokenCount`, because the promptTokenCount of a
+ * generation that @google/genai resumed after continuation pauses is summed
+ * over every resumed request, each of which resent the prompt.
  */
 export declare function getEventTokens(event: Event): number;
 /**

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

@@ -0,0 +1,78 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * `Event.customMetadata` keys that only ADK code may write.
+ *
+ * Mirrors adk-python's `google.adk.events._internal_metadata`.
+ */
+import type { Session } from '../sessions/session.js';
+import type { Event } from './event.js';
+type Metadata = Record<string, unknown>;
+/**
+ * Prefix of `customMetadata` keys that callers cannot set.
+ *
+ * Keys with this prefix are dropped from the `customMetadata` passed to
+ * `Runner.runAsync`, and from events that are restored into a session or
+ * received from a remote A2A agent. Stored events keep them, but they are
+ * removed from API responses, saved session files and A2A messages.
+ *
+ * The value matches adk-python so a session store shared between the two
+ * treats the same keys as internal.
+ */
+export declare const INTERNAL_METADATA_PREFIX = "__adk_internal_";
+/** Set on events that ADK restored into a session from outside it. */
+export declare const RESTORED_EVENT_KEY = "__adk_internal_restored_event";
+/**
+ * Returns `metadata` without keys that have the internal prefix.
+ *
+ * Use it where callers supply metadata. Dropped keys are logged at debug level,
+ * because a caller set a key it cannot set.
+ *
+ * @param metadata A `customMetadata` value. It is not modified.
+ * @returns A new object without internal keys. A value that is not a plain
+ *     object, such as `undefined`, is returned unchanged.
+ */
+export declare function withoutInternalMetadata<T>(metadata: T): T;
+/**
+ * Returns `metadata` as callers see it, without internal keys.
+ *
+ * Use it where events leave ADK. Removal there is routine, so nothing is
+ * logged.
+ *
+ * @param metadata A `customMetadata` value. It is not modified.
+ * @returns A new object without internal keys, or `undefined` if nothing is
+ *     left. A value that is not a plain object is returned unchanged.
+ */
+export declare function publicMetadata<T>(metadata: T): T | undefined;
+/** Returns only the keys of `metadata` that have the internal prefix. */
+export declare function internalMetadata(metadata: unknown): Metadata;
+/**
+ * Marks an event restored from outside the session, in place.
+ *
+ * Internal metadata carried by the event is removed first, so a caller cannot
+ * supply its own.
+ *
+ * @param event The event about to be appended to a new session.
+ * @returns The same event.
+ */
+export declare function markRestored<T extends Event>(event: T): T;
+/**
+ * Returns the event as callers see it, without internal metadata.
+ *
+ * @param event A stored event. It is not modified.
+ * @returns The same event if it has no internal keys. Otherwise a copy whose
+ *     `customMetadata` drops them, or is `undefined` if nothing else is left.
+ */
+export declare function publicEvent<T extends Event>(event: T): T;
+/**
+ * Returns the session as callers see it, without internal metadata.
+ *
+ * @param session A stored session. It is not modified.
+ * @returns The same session if no event changes. Otherwise a copy whose events
+ *     are passed through {@link publicEvent}.
+ */
+export declare function publicSession<T extends Session>(session: T): T;
+export {};

package/dist/types/examples/example_util.d.ts

@@ -6,6 +6,23 @@
 import { Session } from '../sessions/session.js';
 import { BaseExampleProvider } from './base_example_provider.js';
 import { Example } from './example.js';
+/**
+ * Throws unless `examples` is a well-formed list of {@link Example}s.
+ *
+ * Mirrors `TypeAdapter(list[Example]).validate_python` in the adk-python
+ * `ExampleTool` constructor. {@link Example} is erased at compile time, so a
+ * value that reaches the SDK from untyped JavaScript or from a configuration
+ * file is otherwise unchecked, and a malformed entry only fails later while the
+ * few-shot instruction is rendered.
+ *
+ * The value is checked but not replaced, so it keeps reference identity and no
+ * defensive copy is made.
+ *
+ * @param examples - The value to check.
+ * @throws {InputValidationError} When the value is not a list of well-formed
+ *   examples. The message names the path of each failing field.
+ */
+export declare function validateExamples(examples: unknown): asserts examples is Example[];
 /**
  * Converts a list of examples to a string that can be used in a system
  * instruction.