@google/adk 2.1.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/tools/example_tool.js

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

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

@@ -28,6 +28,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import { mergeTrackingHeaders } from "../../utils/client_labels.js";
 import { formatError } from "../../utils/error_utils.js";
 import { logger } from "../../utils/logger.js";
 import { loadOptionalPeer } from "../../utils/optional_peer.js";
@@ -39,13 +40,24 @@ function logTransportError(err) {
   logger.error("MCP transport error: " + 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: 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 loadOptionalPeer(
       MCP_SDK,
       () => Promise.resolve().then(() => __toESM(require("@modelcontextprotocol/sdk/client/index.js"), 1))
@@ -66,19 +78,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 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);