@google/adk 2.4.0 → 2.5.0

package/dist/types/index.d.ts

@@ -21,7 +21,7 @@ export type { VertexAiMemoryBankServiceOptions } from './memory/vertex_ai_memory
 export { VertexAiRagMemoryService } from './memory/vertex_ai_rag_memory_service.js';
 export type { VertexAiRagMemoryServiceOptions } from './memory/vertex_ai_rag_memory_service.js';
 export { DebugLoggingPlugin, isDebugLoggingPlugin, } from './plugins/debug_logging_plugin.js';
-export { DatabaseSessionService, isStaleSessionError, StaleSessionError, } from './sessions/database_session_service.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';
@@ -38,7 +38,7 @@ export { IntegrationClient, type IntegrationClientOptions, } from './tools/appli
 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';
@@ -64,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, 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,7 +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.
+     * 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.
@@ -384,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

@@ -156,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/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/telemetry/api/instrumentation.d.ts

@@ -0,0 +1,259 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Content } from '@google/genai';
+import type { BaseAgent } from '../../agents/base_agent.js';
+import type { InvocationContext } from '../../agents/invocation_context.js';
+import type { RunConfig } from '../../agents/run_config.js';
+import type { Event } from '../../events/event.js';
+import type { LlmRequest } from '../../models/llm_request.js';
+import type { LlmResponse } from '../../models/llm_response.js';
+import type { ContextCompactionTrigger } from '../../plugins/base_plugin.js';
+import type { Skill } from '../../skills/skill.js';
+import type { BaseTool } from '../../tools/base_tool.js';
+import type { BaseNode } from '../../workflow/base_node.js';
+import { type IncomingHeaders } from './internal/trace/propagation.js';
+export type { ContentCapturingMode, ExperimentalFeature, TelemetryConfig, } from './internal/common/config.js';
+export type { IncomingHeaders } from './internal/trace/propagation.js';
+/** Parameters for starting an invocation with {@link recordInvocation}. */
+export interface RecordInvocationParams {
+    /** The runner's root agent or workflow. */
+    readonly entrypoint: BaseNode;
+    /** The session the invocation runs in. */
+    readonly sessionId: string;
+    /** The run's config, whose `telemetry` overrides apply to the invocation. */
+    readonly runConfig?: RunConfig;
+}
+/**
+ * Wraps a runner invocation in its root `invoke_workflow {entrypoint}` span.
+ *
+ * Every workflow started inside the invocation is nested below this span. A
+ * workflow entrypoint runs inside it rather than opening a second one.
+ */
+export declare function recordInvocation<T>({ entrypoint, sessionId, runConfig }: RecordInvocationParams, createGenerator: () => AsyncGenerator<T, void, void>): AsyncGenerator<T, void, void>;
+/** Parameters for starting an `invoke_agent` instrumentation scope. */
+export interface RecordAgentInvocationParams {
+    readonly agent: BaseAgent;
+    /** The context the agent was invoked with. */
+    readonly invocationContext: InvocationContext;
+}
+/**
+ * Wraps an agent invocation in an `invoke_agent {agent.name}` span.
+ */
+export declare function recordAgentInvocation<T>({ agent, invocationContext }: RecordAgentInvocationParams, createGenerator: () => AsyncGenerator<T, void, void>): AsyncGenerator<T, void, void>;
+/** Parameters for recording one model call with {@link recordInference}. */
+export interface RecordInferenceParams {
+    readonly invocationContext: InvocationContext;
+    readonly llmRequest: LlmRequest;
+    /** The event the model's responses are merged into. */
+    readonly modelResponseEvent: Event;
+}
+/**
+ * Wraps one model call in a `generate_content {model}` span and its
+ * `gen_ai.client.inference.operation.details` log record.
+ *
+ * Returns the model's responses unchanged. The span is current only while the
+ * model stream is being pulled, never while the caller handles a response, and
+ * it ends at the first response that reports a finish reason, before that
+ * response is returned. If the stream ends, fails or is closed before one
+ * arrives, the span ends then. Each call emits exactly one log record, while
+ * the span is still open.
+ */
+export declare function recordInference(params: RecordInferenceParams, createStream: () => AsyncGenerator<LlmResponse, void, void>): AsyncGenerator<LlmResponse, void, void>;
+/** Parameters for recording a live `send_data` span. */
+export interface RecordSendDataParams {
+    readonly invocationContext: InvocationContext;
+    readonly eventId: string;
+    readonly data: Content[];
+}
+/**
+ * Wraps an async operation in a `send_data` span and records the live data
+ * payload attributes when the operation completes.
+ */
+export declare function recordSendData<T>(params: RecordSendDataParams, fn: () => Promise<T>): Promise<T>;
+/** Parameters for starting an `execute_tool` instrumentation scope. */
+export interface RecordToolExecutionParams {
+    readonly tool: BaseTool;
+    readonly args: Record<string, unknown>;
+    readonly invocationContext: InvocationContext;
+}
+/** Parameters for recording a completed tool execution on its scope. */
+export interface ToolExecutionSuccessParams {
+    readonly functionResponseEvent?: Event;
+    /**
+     * The raw value returned by the tool before normalization into a
+     * `functionResponse` event, used to inspect any response-reported error type.
+     */
+    readonly rawResult: unknown;
+}
+/** Scope handle passed to the body of {@link recordToolExecution}. */
+export interface ToolExecutionScope {
+    /**
+     * Records the tool's response, including an error the tool reported in it
+     * rather than throwing.
+     */
+    recordSuccess(params: ToolExecutionSuccessParams): void;
+}
+/**
+ * Wraps a single tool call in an `execute_tool {tool.name}` span.
+ *
+ * An error that escapes `fn` is recorded on the span as `error.type` and an
+ * ERROR status, as is an error the tool reports in its response. Skill tools
+ * running inside report to the span through {@link recordSkillActivity}.
+ */
+export declare function recordToolExecution<T>({ tool, args, invocationContext }: RecordToolExecutionParams, fn: (scope: ToolExecutionScope) => Promise<T>): Promise<T>;
+/** What a skill tool is doing, reported with {@link recordSkillActivity}. */
+export type SkillActivity = {
+    readonly kind: 'load';
+    readonly skillName: string;
+} | {
+    readonly kind: 'resource';
+    readonly skillName: string;
+    readonly resourcePath: string;
+} | {
+    readonly kind: 'script';
+    readonly skillName: string;
+    readonly scriptPath: string;
+};
+/** Handle returned by {@link recordSkillActivity}. */
+export interface SkillActivityScope {
+    /** Records the skill the tool resolved. */
+    recordSkill(skill: Skill): void;
+}
+/**
+ * Reports what a skill tool is doing to the `execute_tool` span it runs
+ * under, which is renamed after the skill and records its attributes when the
+ * tool call ends.
+ *
+ * Does nothing outside a tool call. A second report in the same tool call
+ * replaces the first.
+ */
+export declare function recordSkillActivity(activity: SkillActivity): SkillActivityScope;
+/** Parameters for recording a merged tool calls span. */
+export interface RecordMergedToolCallsParams {
+    /** The id of the event that merges the parallel tool responses. */
+    readonly responseEventId: string;
+}
+/**
+ * Starts and immediately ends an `execute_tool (merged)` span for parallel
+ * tool calls whose responses were merged into one event.
+ */
+export declare function recordMergedToolCalls({ responseEventId, }: RecordMergedToolCallsParams): void;
+/**
+ * A synchronously started span scope for workflow orchestration.
+ *
+ * Workflow and node scopes return this handle instead of wrapping a callback.
+ * Their spans must start at the moment the work is scheduled, and the scope
+ * must hand the caller's promise back unchanged: an `async` wrapper adds
+ * promise ticks, which changes how concurrently scheduled nodes interleave.
+ */
+export interface SyncStartedScope {
+    /**
+     * Runs `fn` with this scope's span as the active span and returns its result
+     * as is, without awaiting it.
+     */
+    run<T>(fn: () => T): T;
+    /**
+     * Ends the span, with an ERROR status when `error` is given. Safe to call
+     * more than once; only the first call counts.
+     */
+    end(error?: unknown): void;
+}
+/** Parameters for starting an `invoke_workflow` instrumentation scope. */
+export interface RecordWorkflowInvocationParams {
+    readonly workflow: BaseNode;
+    readonly sessionId: string;
+}
+/**
+ * Starts the `invoke_workflow {workflow.name}` scope of a workflow run,
+ * synchronously.
+ *
+ * The workflow the runner was entered at runs in the runner's span instead,
+ * so its scope opens nothing. A workflow started inside another workflow is
+ * marked nested. The caller runs the orchestration through `scope.run` and
+ * calls `scope.end()` once it settles.
+ */
+export declare function recordWorkflowInvocation({ workflow, sessionId, }: RecordWorkflowInvocationParams): SyncStartedScope;
+/** Parameters for starting a workflow node's instrumentation scope. */
+export interface RecordNodeInvocationParams {
+    readonly node: BaseNode;
+    /** The name the node runs under, which may differ from `node.name`. */
+    readonly nodeName: string;
+    readonly sessionId: string;
+}
+/** Scope handle returned by {@link recordNodeInvocation}. */
+export interface NodeInvocationScope extends SyncStartedScope {
+    /** Records an event the node emitted. */
+    recordEvent(event: Event): void;
+}
+/**
+ * Starts the scope of one workflow node run, synchronously.
+ *
+ * A plain node runs in an `invoke_node {nodeName}` span that records the ids
+ * of the events it emitted. An agent or workflow node opens no node span: its
+ * own `invoke_agent` or `invoke_workflow` span stands for it.
+ *
+ * The span's parent is the span active at the call, so call this when the node
+ * is scheduled. The caller runs the node body through `scope.run` and calls
+ * `scope.end()` when the node work finishes.
+ */
+export declare function recordNodeInvocation({ node, nodeName, sessionId, }: RecordNodeInvocationParams): NodeInvocationScope;
+/** Parameters for recording a context compaction. */
+export interface RecordCompactionParams {
+    readonly invocationContext: InvocationContext;
+    readonly trigger: ContextCompactionTrigger;
+}
+/**
+ * Wraps a context compaction in a `compact_events {trigger}` span, recording
+ * the summary event it added to the session.
+ */
+export declare function recordCompaction<T>({ invocationContext, trigger }: RecordCompactionParams, fn: () => Promise<T>): Promise<T>;
+/** A `fetch` as the MCP HTTP transports call it. */
+export type McpFetch = (url: string | URL, init?: Parameters<typeof globalThis.fetch>[1]) => Promise<Response>;
+/**
+ * Returns a `fetch` for an MCP HTTP transport that reports each exchange as
+ * an `adk.experimental.mcp.http.client.response.end` log record, parented to
+ * the span active when the request was sent.
+ *
+ * Returns `fetch` unchanged, `undefined` included, unless the experimental
+ * `mcp` telemetry feature is enabled in the environment, which is read when
+ * this is called, so call it when the transport is built. The returned
+ * function sends each request with `fetch`, or the global `fetch` when that is
+ * `undefined`, and resolves with its response as soon as it arrives: the
+ * record is written in the background, and a failure to write it is logged,
+ * never thrown.
+ */
+export declare function instrumentMcpFetch(fetch: McpFetch | undefined): McpFetch | undefined;
+/** A `fetch`-compatible function. */
+export type FetchFunction = (input: Parameters<typeof globalThis.fetch>[0], init?: Parameters<typeof globalThis.fetch>[1]) => Promise<Response>;
+/**
+ * Returns a `fetch` that sends the active trace context with each request.
+ *
+ * At each call, the globally registered propagator writes the active context
+ * into the request headers: W3C `traceparent` and `tracestate` by default. A
+ * header the caller already sets is kept. When the propagator writes nothing,
+ * for example with no active trace, the request is sent with its arguments
+ * unchanged. A propagator error is logged, never thrown.
+ *
+ * @param fetchImpl The `fetch` that sends the request. Defaults to the global
+ *     `fetch`, read at each call.
+ */
+export declare function propagateTraceContext(fetchImpl?: FetchFunction): FetchFunction;
+/**
+ * Runs `fn` in the trace context that an incoming request carries.
+ *
+ * When no span is active, the globally registered propagator reads the
+ * headers (W3C `traceparent` and `tracestate` by default), and a valid remote
+ * span becomes the parent of the invocation spans `fn` starts. An already
+ * active span, such as an HTTP server span or a remote parent set earlier,
+ * stays the parent, and the headers are ignored. Missing or malformed headers
+ * leave the context unchanged; a propagator error is logged, never thrown.
+ *
+ * @param headers The incoming request headers, such as Node's
+ *     `IncomingMessage.headers`.
+ * @param fn The request handler to run.
+ * @returns What `fn` returns.
+ */
+export declare function runWithRemoteTraceContext<T>(headers: IncomingHeaders, fn: () => T): T;

package/dist/types/telemetry/api/internal/common/accumulators.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type Context } from '@opentelemetry/api';
+import type { ResolvedTelemetryConfig } from './config.js';
+import { TokenUsage } from './token_usage.js';
+declare const WORKFLOW_FRAME_SYMBOL: unique symbol;
+/** An accumulator's totals at flush time. */
+export interface Totals {
+    /** `undefined` until a model call reports usage (not the same as zero). */
+    tokens?: TokenUsage;
+    inferenceCalls: number;
+    toolCalls: number;
+    skillLoads: number;
+    compactions: number;
+}
+/** State accumulated across one agent invocation or one workflow. */
+export interface Accumulator {
+    readonly totals: Totals;
+}
+/**
+ * State accumulated across one `invoke_workflow`, root or nested.
+ *
+ * The `parent` chain is walked when a call records against every enclosing
+ * workflow; its presence is what `gen_ai.workflow.nested` reports.
+ */
+export interface WorkflowFrame extends Accumulator {
+    readonly [WORKFLOW_FRAME_SYMBOL]: true;
+    readonly parent: WorkflowFrame | undefined;
+    /** The agent or workflow the turn entered at, inherited by nested workflows. */
+    readonly rootAgentName: string;
+    readonly workflowName: string;
+    /** The config the turn was claimed under, inherited by nested workflows. */
+    readonly config: ResolvedTelemetryConfig;
+    /**
+     * The runner's workflow entrypoint, which runs inside this frame instead of
+     * opening its own. Cleared once that workflow has claimed it.
+     */
+    entrypoint: object | undefined;
+}
+/**
+ * Opens an agent accumulator frame on `parentContext`, so model and tool calls
+ * running inside count their exclusive totals against this agent invocation.
+ */
+export declare function openAgentFrame(parentContext?: Context): {
+    readonly frame: Accumulator;
+    readonly context: Context;
+};
+/** Parameters for {@link openWorkflowFrame}. */
+export interface OpenWorkflowFrameParams {
+    readonly workflowName: string;
+    /** The config to use when this is the root workflow frame. */
+    readonly config: ResolvedTelemetryConfig;
+    readonly entrypoint?: object;
+    readonly parentContext?: Context;
+}
+/**
+ * Opens a workflow accumulator frame on `parentContext`, linked to any
+ * enclosing workflow frame and inheriting its root agent name and telemetry
+ * config.
+ */
+export declare function openWorkflowFrame({ workflowName, config, entrypoint, parentContext, }: OpenWorkflowFrameParams): {
+    readonly frame: WorkflowFrame;
+    readonly context: Context;
+};
+/**
+ * Hands the runner's entrypoint frame to the workflow it was opened for, once.
+ *
+ * @returns The context to run the workflow under, or `undefined` when
+ *     `workflow` is not the unclaimed entrypoint of the enclosing frame.
+ */
+export declare function claimEntrypointWorkflowFrame(workflow: object, ctx?: Context): Context | undefined;
+/**
+ * Every accumulator a call belongs to, captured from the context when the call
+ * starts: the innermost agent (exclusive) and each enclosing workflow
+ * (inclusive).
+ */
+export interface CapturedAccumulators {
+    addInferenceCall(): void;
+    addToolCall(): void;
+    addSkillLoad(): void;
+    addCompaction(): void;
+    addTokens(usage: TokenUsage): void;
+}
+/**
+ * Captures the active agent and workflow accumulators from `ctx`.
+ */
+export declare function captureAccumulators(ctx?: Context): CapturedAccumulators;
+export {};