@google/adk 2.2.0 → 2.2.1

package/dist/esm/plugins/tool_call_integrity_plugin.js

@@ -0,0 +1,339 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { createEvent, getFunctionCalls } from "../events/event.js";
+import {
+  INTERNAL_METADATA_PREFIX,
+  markRestored,
+  RESTORED_EVENT_KEY
+} from "../events/internal_metadata.js";
+import { logger } from "../utils/logger.js";
+import { BasePlugin } from "./base_plugin.js";
+const TOOL_CALL_HMAC_METADATA_KEY = `${INTERNAL_METADATA_PREFIX}fc_hmac`;
+const STAMP_PREFIX = "v1:";
+const _ToolCallIntegrityError = class _ToolCallIntegrityError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ToolCallIntegrityError";
+  }
+};
+__name(_ToolCallIntegrityError, "ToolCallIntegrityError");
+let ToolCallIntegrityError = _ToolCallIntegrityError;
+function jsonForm(value) {
+  const json = JSON.stringify(value);
+  return json === void 0 ? null : JSON.parse(json);
+}
+__name(jsonForm, "jsonForm");
+function canonicalJson(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
+  }
+  if (value !== null && typeof value === "object") {
+    const object = value;
+    const entries = Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(object[key])}`);
+    return `{${entries.join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+__name(canonicalJson, "canonicalJson");
+function jsonArgs(args) {
+  const json = jsonForm(args != null ? args : {});
+  return json != null ? json : {};
+}
+__name(jsonArgs, "jsonArgs");
+function canonicalPayload(session, event, functionCall) {
+  var _a, _b, _c, _d, _e;
+  return new TextEncoder().encode(
+    canonicalJson({
+      app_name: session.appName,
+      user_id: session.userId,
+      session_id: session.id,
+      invocation_id: (_a = event.invocationId) != null ? _a : null,
+      branch: (_b = event.branch) != null ? _b : null,
+      author: (_c = event.author) != null ? _c : null,
+      name: (_d = functionCall.name) != null ? _d : null,
+      id: (_e = functionCall.id) != null ? _e : null,
+      args: jsonArgs(functionCall.args)
+    })
+  );
+}
+__name(canonicalPayload, "canonicalPayload");
+function isStampMap(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) && Object.values(value).every(
+    // eslint-disable-next-line no-control-regex
+    (stamp) => typeof stamp === "string" && /^[\x00-\x7f]*$/.test(stamp)
+  );
+}
+__name(isStampMap, "isStampMap");
+function isRestored(event) {
+  var _a;
+  return Boolean((_a = event.customMetadata) == null ? void 0 : _a[RESTORED_EVENT_KEY]);
+}
+__name(isRestored, "isRestored");
+function getStamps(event) {
+  var _a;
+  const stamps = (_a = event.customMetadata) == null ? void 0 : _a[TOOL_CALL_HMAC_METADATA_KEY];
+  if (stamps === void 0 || stamps === null) {
+    return {};
+  }
+  if (!isStampMap(stamps)) {
+    throw new ToolCallIntegrityError(
+      `Event '${event.id}' has a malformed integrity stamp.`
+    );
+  }
+  return stamps;
+}
+__name(getStamps, "getStamps");
+function hasStamp(stamps, callId) {
+  return Object.hasOwn(stamps, callId);
+}
+__name(hasStamp, "hasStamp");
+function toHex(bytes) {
+  return Array.from(
+    new Uint8Array(bytes),
+    (b) => b.toString(16).padStart(2, "0")
+  ).join("");
+}
+__name(toHex, "toHex");
+function fromHex(hex) {
+  if (!/^[0-9a-f]{64}$/.test(hex)) {
+    return void 0;
+  }
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+__name(fromHex, "fromHex");
+function getSubtleCrypto() {
+  var _a;
+  const subtle = (_a = globalThis.crypto) == null ? void 0 : _a.subtle;
+  if (!subtle) {
+    throw new Error(
+      "ToolCallIntegrityPlugin requires the Web Crypto API (globalThis.crypto.subtle), which is not available in this environment."
+    );
+  }
+  return subtle;
+}
+__name(getSubtleCrypto, "getSubtleCrypto");
+const _ToolCallIntegrityPlugin = class _ToolCallIntegrityPlugin extends BasePlugin {
+  /**
+   * @throws {Error} If `secretKey` is empty or contains a key that is not
+   *     non-empty bytes.
+   */
+  constructor(options) {
+    var _a, _b;
+    super((_a = options.name) != null ? _a : "tool_call_integrity");
+    const secretKey = options.secretKey;
+    const rawKeys = secretKey instanceof Uint8Array ? [secretKey] : Array.isArray(secretKey) ? [...secretKey] : [];
+    if (rawKeys.length === 0 || !rawKeys.every((key) => key instanceof Uint8Array && key.length > 0)) {
+      throw new Error(
+        "secretKey must be non-empty bytes or a non-empty list of them."
+      );
+    }
+    this.keys = rawKeys.map((key) => new Uint8Array(key));
+    this.allowUnstampedCalls = (_b = options.allowUnstampedCalls) != null ? _b : false;
+  }
+  /**
+   * Returns a copy with internal metadata removed and marked as restored.
+   *
+   * Use it on events that your code copies into another session, so that the
+   * history passes the integrity check. The copy only keeps the history: its
+   * function calls are never executed.
+   *
+   * @param event The event to copy. It is not modified.
+   * @returns The marked copy, ready to append to the new session.
+   */
+  static prepareRestoredEvent(event) {
+    return markRestored(createEvent(structuredClone(event)));
+  }
+  getCryptoKeys() {
+    if (!this.cryptoKeys) {
+      const subtle = getSubtleCrypto();
+      this.cryptoKeys = Promise.all(
+        this.keys.map(
+          (key) => subtle.importKey("raw", key, { name: "HMAC", hash: "SHA-256" }, false, [
+            "sign",
+            "verify"
+          ])
+        )
+      );
+    }
+    return this.cryptoKeys;
+  }
+  async sign(payload) {
+    const [primary] = await this.getCryptoKeys();
+    const digest = await getSubtleCrypto().sign("HMAC", primary, payload);
+    return STAMP_PREFIX + toHex(digest);
+  }
+  /** `subtle.verify` compares in constant time. */
+  async verify(payload, stamp) {
+    if (!stamp.startsWith(STAMP_PREFIX)) {
+      return false;
+    }
+    const signature = fromHex(stamp.slice(STAMP_PREFIX.length));
+    if (!signature) {
+      return false;
+    }
+    const subtle = getSubtleCrypto();
+    for (const key of await this.getCryptoKeys()) {
+      if (await subtle.verify("HMAC", key, signature, payload)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  unstamped(name, callId) {
+    const message = `${name} call '${callId}' has no integrity stamp.`;
+    if (!this.allowUnstampedCalls) {
+      throw new ToolCallIntegrityError(message);
+    }
+    logger.warn(message);
+  }
+  async onEventCallback({
+    invocationContext,
+    event
+  }) {
+    var _a;
+    const session = invocationContext.session;
+    const calls = getFunctionCalls(event).filter((fc) => fc.id);
+    if (!event.partial) {
+      const seen = /* @__PURE__ */ new Set();
+      for (const fc of calls) {
+        if (seen.has(fc.id)) {
+          throw new ToolCallIntegrityError(
+            `Event '${event.id}' repeats function call ID '${fc.id}'.`
+          );
+        }
+        seen.add(fc.id);
+      }
+    }
+    const stamps = {};
+    for (const fc of calls) {
+      stamps[fc.id] = await this.sign(canonicalPayload(session, event, fc));
+    }
+    if (Object.keys(stamps).length > 0) {
+      event.customMetadata = {
+        ...(_a = event.customMetadata) != null ? _a : {},
+        [TOOL_CALL_HMAC_METADATA_KEY]: stamps
+      };
+    }
+    return void 0;
+  }
+  async beforeRunCallback({
+    invocationContext
+  }) {
+    const session = invocationContext.session;
+    for (const event of session.events) {
+      const calls = getFunctionCalls(event);
+      if (calls.length === 0 || isRestored(event)) {
+        continue;
+      }
+      const stamps = getStamps(event);
+      const verified = /* @__PURE__ */ new Set();
+      for (const fc of calls) {
+        if (!fc.id) {
+          continue;
+        }
+        if (!hasStamp(stamps, fc.id)) {
+          this.unstamped(fc.name, fc.id);
+          continue;
+        }
+        if (verified.has(fc.id)) {
+          throw new ToolCallIntegrityError(
+            `Event '${event.id}' has duplicate function call ID '${fc.id}'.`
+          );
+        }
+        const payload = canonicalPayload(session, event, fc);
+        if (!await this.verify(payload, stamps[fc.id])) {
+          throw new ToolCallIntegrityError(
+            `${fc.name} call '${fc.id}' does not match its integrity stamp.`
+          );
+        }
+        verified.add(fc.id);
+      }
+      const unmatched = Object.keys(stamps).filter((id) => !verified.has(id)).sort();
+      if (unmatched.length > 0) {
+        throw new ToolCallIntegrityError(
+          `Event '${event.id}' has integrity stamps with no matching call: ${JSON.stringify(unmatched)}.`
+        );
+      }
+    }
+    return void 0;
+  }
+  async beforeToolCallback({
+    tool,
+    toolArgs,
+    toolContext
+  }) {
+    const callId = toolContext.functionCallId;
+    if (!callId) {
+      throw new ToolCallIntegrityError(
+        `${tool.name} call has no ID, so its integrity cannot be checked.`
+      );
+    }
+    const session = toolContext.invocationContext.session;
+    const stored = [];
+    let restored = false;
+    for (const event of session.events) {
+      for (const fc of getFunctionCalls(event)) {
+        if (fc.id !== callId) {
+          continue;
+        }
+        if (isRestored(event)) {
+          restored = true;
+        } else {
+          stored.push([event, fc]);
+        }
+      }
+    }
+    if (stored.length === 0) {
+      if (restored) {
+        throw new ToolCallIntegrityError(
+          `${tool.name} call '${callId}' comes from restored history and cannot be executed.`
+        );
+      }
+      this.unstamped(tool.name, callId);
+      return void 0;
+    }
+    const trusted = [];
+    for (const [event, fc] of stored) {
+      const stamps = getStamps(event);
+      if (!hasStamp(stamps, callId)) {
+        this.unstamped(tool.name, callId);
+      } else if (!await this.verify(
+        canonicalPayload(session, event, fc),
+        stamps[callId]
+      )) {
+        throw new ToolCallIntegrityError(
+          `${tool.name} call '${callId}' does not match its integrity stamp.`
+        );
+      }
+      trusted.push(fc);
+    }
+    const executed = canonicalJson(jsonArgs(toolArgs));
+    const matches = trusted.some(
+      (fc) => fc.name === tool.name && canonicalJson(jsonArgs(fc.args)) === executed
+    );
+    if (!matches) {
+      throw new ToolCallIntegrityError(
+        `${tool.name} call '${callId}' arguments do not match its stored call.`
+      );
+    }
+    return void 0;
+  }
+};
+__name(_ToolCallIntegrityPlugin, "ToolCallIntegrityPlugin");
+let ToolCallIntegrityPlugin = _ToolCallIntegrityPlugin;
+export {
+  TOOL_CALL_HMAC_METADATA_KEY,
+  ToolCallIntegrityError,
+  ToolCallIntegrityPlugin
+};

package/dist/esm/runner/runner.js

@@ -33,6 +33,10 @@ import {
 } from "../code_executors/built_in_code_executor.js";
 import { createEvent } from "../events/event.js";
 import { createEventActions } from "../events/event_actions.js";
+import {
+  internalMetadata,
+  withoutInternalMetadata
+} from "../events/internal_metadata.js";
 import { PluginManager } from "../plugins/plugin_manager.js";
 import {
   runAsyncGeneratorWithOtelContext,
@@ -218,7 +222,8 @@ const _Runner = class _Runner {
                 author: "user",
                 actions: stateDelta ? createEventActions({ stateDelta }) : void 0,
                 content: newMessage,
-                customMetadata: params.customMetadata
+                // Callers cannot set ADK-internal keys.
+                customMetadata: withoutInternalMetadata(params.customMetadata)
               })
             });
             if ((_e = params.abortSignal) == null ? void 0 : _e.aborted) {
@@ -262,7 +267,7 @@ const _Runner = class _Runner {
                   event
                 });
                 const outputEvent = modifiedEvent ? {
-                  ...modifiedEvent,
+                  ...withInternalMetadataOf(event, modifiedEvent),
                   id: event.id,
                   invocationId: event.invocationId,
                   timestamp: event.timestamp,
@@ -514,7 +519,7 @@ const _Runner = class _Runner {
             if ((_d2 = params.abortSignal) == null ? void 0 : _d2.aborted) {
               return;
             }
-            const eventToProcess = modifiedEvent != null ? modifiedEvent : event;
+            const eventToProcess = modifiedEvent ? withInternalMetadataOf(event, modifiedEvent) : event;
             if (!eventToProcess.partial && !isLiveModelMediaEventWithInlineData(eventToProcess)) {
               await this.sessionService.appendEvent({
                 session,
@@ -533,6 +538,18 @@ const _Runner = class _Runner {
 };
 __name(_Runner, "Runner");
 let Runner = _Runner;
+function withInternalMetadataOf(original, replacement) {
+  var _a2;
+  const internal = internalMetadata(original.customMetadata);
+  if (Object.keys(internal).length === 0) {
+    return replacement;
+  }
+  return {
+    ...replacement,
+    customMetadata: { ...(_a2 = replacement.customMetadata) != null ? _a2 : {}, ...internal }
+  };
+}
+__name(withInternalMetadataOf, "withInternalMetadataOf");
 function isLiveModelMediaEventWithInlineData(event) {
   var _a2;
   const parts = (_a2 = event.content) == null ? void 0 : _a2.parts;

package/dist/esm/version.js

@@ -5,7 +5,7 @@ const require = topLevelCreateRequire(import.meta.url);
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-const version = "2.2.0";
+const version = "2.2.1";
 export {
   version
 };

package/dist/types/common.d.ts

@@ -87,6 +87,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';
@@ -121,6 +122,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';

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

@@ -0,0 +1,59 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Content, GenerateContentConfig, GenerateContentResponse, GenerateContentResponseUsageMetadata, Part } from '@google/genai';
+import { LlmResponse } from './llm_response.js';
+/** The most times one generation is resumed after the model pauses it. */
+export declare const MAX_RESUMES = 256;
+/** The contents and config of a request that resumes a paused generation. */
+export interface ResumeRequest {
+    contents: Content[];
+    config: GenerateContentConfig;
+}
+/**
+ * Returns the token that resumes `response`, or undefined if it did not pause
+ * or has no token.
+ */
+export declare function resumeToken(response: GenerateContentResponse): string | undefined;
+/**
+ * One generation, carried across the requests that resume it after the model
+ * pauses it.
+ */
+export declare class GeminiContinuation {
+    private readonly config?;
+    private readonly contents;
+    private readonly parts;
+    private usage?;
+    private token?;
+    private resumes;
+    constructor(contents: Content[], config?: GenerateContentConfig | undefined);
+    /**
+     * Adds one request's output to the generation: its parts to the content and
+     * its usage to the total.
+     */
+    addOutput(newParts: Part[], newUsage: GenerateContentResponseUsageMetadata | undefined): void;
+    /**
+     * Returns the request that resumes the generation after a request that
+     * ended with `nextToken`. Returns undefined if the request did not pause,
+     * returned the previous token again, or the generation was already resumed
+     * {@link MAX_RESUMES} times.
+     */
+    resumeRequest(nextToken: string | undefined): ResumeRequest | undefined;
+    /** Returns `response` with the content and usage of all requests, if resumed. */
+    complete(response: GenerateContentResponse): LlmResponse;
+    /**
+     * Returns the final streamed `response`, with usage summed across all
+     * requests if resumed.
+     */
+    withSummedUsage(response: LlmResponse): LlmResponse;
+    /** Returns whether a request that ended with `nextToken` is resumed. */
+    willResume(nextToken: string): boolean;
+    /** Whether the generation took more than one request. */
+    private get resumed();
+    private content;
+    private buildResumeRequest;
+    /** Appends `newParts`, joining text as the streaming aggregator does. */
+    private appendParts;
+}