@google/adk 2.1.0 → 2.2.1

package/dist/cjs/plugins/tool_call_integrity_plugin.js

@@ -0,0 +1,364 @@
+/**
+  * @license
+  * Copyright 2026 Google LLC
+  * SPDX-License-Identifier: Apache-2.0
+  */
+
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var tool_call_integrity_plugin_exports = {};
+__export(tool_call_integrity_plugin_exports, {
+  TOOL_CALL_HMAC_METADATA_KEY: () => TOOL_CALL_HMAC_METADATA_KEY,
+  ToolCallIntegrityError: () => ToolCallIntegrityError,
+  ToolCallIntegrityPlugin: () => ToolCallIntegrityPlugin
+});
+module.exports = __toCommonJS(tool_call_integrity_plugin_exports);
+var import_event = require("../events/event.js");
+var import_internal_metadata = require("../events/internal_metadata.js");
+var import_logger = require("../utils/logger.js");
+var import_base_plugin = require("./base_plugin.js");
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const TOOL_CALL_HMAC_METADATA_KEY = `${import_internal_metadata.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[import_internal_metadata.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 import_base_plugin.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 (0, import_internal_metadata.markRestored)((0, import_event.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);
+    }
+    import_logger.logger.warn(message);
+  }
+  async onEventCallback({
+    invocationContext,
+    event
+  }) {
+    var _a;
+    const session = invocationContext.session;
+    const calls = (0, import_event.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 = (0, import_event.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 (0, import_event.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;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TOOL_CALL_HMAC_METADATA_KEY,
+  ToolCallIntegrityError,
+  ToolCallIntegrityPlugin
+});

package/dist/cjs/runner/runner.js

@@ -45,6 +45,7 @@ var import_session_artifact_service = require("../artifacts/session_artifact_ser
 var import_built_in_code_executor = require("../code_executors/built_in_code_executor.js");
 var import_event = require("../events/event.js");
 var import_event_actions = require("../events/event_actions.js");
+var import_internal_metadata = require("../events/internal_metadata.js");
 var import_plugin_manager = require("../plugins/plugin_manager.js");
 var import_tracing = require("../telemetry/tracing.js");
 var import_base_toolset = require("../tools/base_toolset.js");
@@ -230,7 +231,8 @@ const _Runner = class _Runner {
                 author: "user",
                 actions: stateDelta ? (0, import_event_actions.createEventActions)({ stateDelta }) : void 0,
                 content: newMessage,
-                customMetadata: params.customMetadata
+                // Callers cannot set ADK-internal keys.
+                customMetadata: (0, import_internal_metadata.withoutInternalMetadata)(params.customMetadata)
               })
             });
             if ((_e = params.abortSignal) == null ? void 0 : _e.aborted) {
@@ -274,7 +276,7 @@ const _Runner = class _Runner {
                   event
                 });
                 const outputEvent = modifiedEvent ? {
-                  ...modifiedEvent,
+                  ...withInternalMetadataOf(event, modifiedEvent),
                   id: event.id,
                   invocationId: event.invocationId,
                   timestamp: event.timestamp,
@@ -526,7 +528,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,
@@ -545,6 +547,18 @@ const _Runner = class _Runner {
 };
 __name(_Runner, "Runner");
 let Runner = _Runner;
+function withInternalMetadataOf(original, replacement) {
+  var _a2;
+  const internal = (0, import_internal_metadata.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/cjs/tools/example_tool.js

@@ -59,7 +59,7 @@ const _ExampleTool = class _ExampleTool extends import_base_tool.BaseTool {
       return;
     }
     (0, import_llm_request.appendInstructions)(llmRequest, [
-      (0, import_example_util.buildExampleSi)(this.examples, parts[0].text, llmRequest.model)
+      await (0, import_example_util.buildExampleSi)(this.examples, parts[0].text, llmRequest.model)
     ]);
   }
 };

package/dist/cjs/tools/mcp/mcp_session_manager.js

@@ -38,6 +38,7 @@ __export(mcp_session_manager_exports, {
   MCPSessionManager: () => MCPSessionManager
 });
 module.exports = __toCommonJS(mcp_session_manager_exports);
+var import_client_labels = require("../../utils/client_labels.js");
 var import_error_utils = require("../../utils/error_utils.js");
 var import_logger = require("../../utils/logger.js");
 var import_optional_peer = require("../../utils/optional_peer.js");
@@ -54,13 +55,24 @@ function logTransportError(err) {
   import_logger.logger.error("MCP transport error: " + (0, import_error_utils.formatError)(err));
 }
 __name(logTransportError, "logTransportError");
+function buildTransportOptions(params) {
+  const { transportOptions, header } = params;
+  const callerHeaders = (transportOptions == null ? void 0 : transportOptions.requestInit) === void 0 ? header : transportOptions.requestInit.headers;
+  return {
+    ...transportOptions,
+    requestInit: {
+      ...transportOptions == null ? void 0 : transportOptions.requestInit,
+      headers: (0, import_client_labels.mergeTrackingHeaders)(callerHeaders)
+    }
+  };
+}
+__name(buildTransportOptions, "buildTransportOptions");
 const _MCPSessionManager = class _MCPSessionManager {
   constructor(connectionParams) {
     this.activeSessions = /* @__PURE__ */ new Set();
     this.connectionParams = connectionParams;
   }
   async createSession() {
-    var _a;
     const { Client } = await (0, import_optional_peer.loadOptionalPeer)(
       MCP_SDK,
       () => Promise.resolve().then(() => __toESM(require("@modelcontextprotocol/sdk/client/index.js"), 1))
@@ -81,19 +93,13 @@ const _MCPSessionManager = class _MCPSessionManager {
           break;
         }
         case "StreamableHTTPConnectionParams": {
-          const options = (_a = this.connectionParams.transportOptions) != null ? _a : {};
-          if (!options.requestInit && this.connectionParams.header !== void 0) {
-            options.requestInit = {
-              headers: this.connectionParams.header
-            };
-          }
           const { StreamableHTTPClientTransport } = await (0, import_optional_peer.loadOptionalPeer)(
             MCP_SDK,
             () => Promise.resolve().then(() => __toESM(require("@modelcontextprotocol/sdk/client/streamableHttp.js"), 1))
           );
           const transport = new StreamableHTTPClientTransport(
             new URL(this.connectionParams.url),
-            options
+            buildTransportOptions(this.connectionParams)
           );
           transport.onerror = logTransportError;
           await client.connect(transport);