@google/adk 2.1.0 → 2.2.0

package/dist/esm/tools/openapi_tool/openapi_spec_parser/openapi_spec_parser.js

@@ -16,6 +16,7 @@ var __decorateClass = (decorators, target, key, kind) => {
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import { toSnakeCaseName } from "../../../utils/case_utils.js";
 import { experimental } from "../../../utils/experimental.js";
 import { OperationParser } from "./operation_parser.js";
 const VALID_SCHEMA_TYPES = /* @__PURE__ */ new Set([
@@ -47,9 +48,13 @@ __decorateClass([
 OpenApiSpecParser = __decorateClass([
   experimental
 ], OpenApiSpecParser);
+function deepCopy(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+__name(deepCopy, "deepCopy");
 function resolveReferences(spec) {
   const resolvedCache = /* @__PURE__ */ new Map();
-  const specCopy = JSON.parse(JSON.stringify(spec));
+  const specCopy = deepCopy(spec);
   const recursiveResolve = /* @__PURE__ */ __name((obj, currentDoc, seenRefs = /* @__PURE__ */ new Set()) => {
     if (typeof obj !== "object" || obj === null) {
       return obj;
@@ -67,13 +72,13 @@ function resolveReferences(spec) {
       }
       seenRefs.add(refString);
       if (resolvedCache.has(refString)) {
-        return resolvedCache.get(refString);
+        return deepCopy(resolvedCache.get(refString));
       }
       let resolvedValue = resolveRef(refString, currentDoc);
       if (resolvedValue !== void 0) {
         resolvedValue = recursiveResolve(resolvedValue, currentDoc, seenRefs);
         resolvedCache.set(refString, resolvedValue);
-        return resolvedValue;
+        return deepCopy(resolvedValue);
       } else {
         return obj;
       }
@@ -104,7 +109,6 @@ function resolveRef(refString, currentDoc) {
 }
 __name(resolveRef, "resolveRef");
 function sanitizeSchemaTypes(openapiSpec) {
-  const specCopy = JSON.parse(JSON.stringify(openapiSpec));
   const sanitizeTypeField = /* @__PURE__ */ __name((schemaDict) => {
     if (!("type" in schemaDict)) return;
     const typeValue = schemaDict["type"];
@@ -150,7 +154,7 @@ function sanitizeSchemaTypes(openapiSpec) {
     }
     return objRecord;
   }, "sanitizeRecursive");
-  return sanitizeRecursive(specCopy, false);
+  return sanitizeRecursive(openapiSpec, false);
 }
 __name(sanitizeSchemaTypes, "sanitizeSchemaTypes");
 function resolveServerUrl(server) {
@@ -198,7 +202,7 @@ function collectOperations(spec, options = {}) {
       const opParams = operation.parameters || [];
       operation.parameters = [...opParams, ...pathParams];
       if (!operation.operationId) {
-        operation.operationId = `${method}_${path.replace(/[^a-zA-Z0-9]/g, "_")}`;
+        operation.operationId = toSnakeCaseName(`${path}_${method}`);
       }
       const parser = new OperationParser(operation, {
         preservePropertyNames
@@ -215,6 +219,7 @@ function collectOperations(spec, options = {}) {
         endpoint: { baseUrl, path, method },
         operation,
         parameters: parser.getParameters(),
+        returnValue: parser.getReturnValue(),
         authScheme
       });
     }

package/dist/esm/tools/openapi_tool/openapi_spec_parser/operation_parser.js

@@ -16,23 +16,48 @@ var __decorateClass = (decorators, target, key, kind) => {
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import {
+  renameReservedKeywords,
+  toSnakeCaseName
+} from "../../../utils/case_utils.js";
 import { experimental } from "../../../utils/experimental.js";
+import {
+  generateParamDoc,
+  generateReturnDoc,
+  getTypeHint
+} from "../common/common.js";
 let OperationParser = class {
+  /**
+   * @param operation The operation to parse. A string is parsed as JSON, and a
+   *     plain object is used as given.
+   * @param options.preservePropertyNames Keeps the original parameter and
+   *     function names instead of converting them to snake_case.
+   * @param options.shouldParse Whether to parse the operation during
+   *     construction. Defaults to `true`.
+   */
   constructor(operation, options = {}) {
-    this.operation = operation;
     this.params = [];
-    var _a;
+    var _a, _b;
+    this.operation = typeof operation === "string" ? JSON.parse(operation) : operation;
     this.preservePropertyNames = (_a = options.preservePropertyNames) != null ? _a : false;
-    this.processOperationParameters();
-    this.processRequestBody();
-    this.processReturnValue();
-    this.dedupeParamNames();
+    if ((_b = options.shouldParse) != null ? _b : true) {
+      this.processOperationParameters();
+      this.processRequestBody();
+      this.returnValue = this.processReturnValue();
+      this.dedupeParamNames();
+    }
+  }
+  static load(operation, params, returnValue) {
+    const parser = new this(operation, { shouldParse: false });
+    parser.params = params;
+    parser.returnValue = returnValue;
+    return parser;
   }
   getParamName(originalName) {
     if (this.preservePropertyNames) {
       return originalName;
     }
-    return originalName.replace(/[A-Z]/g, (g) => "_" + g.toLowerCase()).replace(/^_/, "");
+    return renameReservedKeywords(toSnakeCaseName(originalName));
   }
   processOperationParameters() {
     const parameters = this.operation.parameters || [];
@@ -54,6 +79,7 @@ let OperationParser = class {
     }
   }
   processRequestBody() {
+    var _a;
     const requestBody = this.operation.requestBody;
     if (!requestBody || "$ref" in requestBody) {
       return;
@@ -64,9 +90,9 @@ let OperationParser = class {
       return;
     }
     const mediaTypeObject = content[firstMimeType];
-    const schema = mediaTypeObject.schema;
+    const schema = (_a = mediaTypeObject.schema) != null ? _a : {};
     const description = requestBody.description || "";
-    if (schema && !("$ref" in schema)) {
+    if (!("$ref" in schema)) {
       if (schema.type === "object") {
         const properties = schema.properties || {};
         if (Object.keys(properties).length > 0) {
@@ -121,16 +147,16 @@ let OperationParser = class {
     if (min20x) {
       const response = responses[min20x];
       if (!("$ref" in response) && response.content) {
-        const firstMimeType = Object.keys(response.content)[0];
-        if (firstMimeType) {
-          const schema = response.content[firstMimeType].schema;
+        for (const mediaType of Object.values(response.content)) {
+          const schema = mediaType.schema;
           if (schema && !("$ref" in schema)) {
             returnSchema = schema;
+            break;
           }
         }
       }
     }
-    this.returnValue = {
+    return {
       originalName: "",
       paramLocation: "",
       paramSchema: returnSchema,
@@ -178,6 +204,32 @@ let OperationParser = class {
   getDescription() {
     return this.operation.description || this.operation.summary || "";
   }
+  getAuthSchemeName() {
+    var _a, _b;
+    const security = (_a = this.operation.security) != null ? _a : [];
+    return security.length > 0 ? (_b = Object.keys(security[0])[0]) != null ? _b : "" : "";
+  }
+  getReturnValue() {
+    return this.returnValue;
+  }
+  getReturnTypeHint() {
+    var _a;
+    return getTypeHint((_a = this.returnValue) == null ? void 0 : _a.paramSchema);
+  }
+  getPydocString() {
+    var _a;
+    const description = this.operation.summary || this.operation.description || "";
+    const argLines = this.params.map((param) => `    ${generateParamDoc(param)}`).join("\n");
+    const returnDoc = generateReturnDoc((_a = this.operation.responses) != null ? _a : {});
+    const returnBlock = returnDoc ? `
+
+${returnDoc}` : "";
+    return `"""${description}
+
+Args:
+${argLines}${returnBlock}
+"""`;
+  }
 };
 __name(OperationParser, "OperationParser");
 __decorateClass([
@@ -192,6 +244,21 @@ __decorateClass([
 __decorateClass([
   experimental
 ], OperationParser.prototype, "getDescription", 1);
+__decorateClass([
+  experimental
+], OperationParser.prototype, "getAuthSchemeName", 1);
+__decorateClass([
+  experimental
+], OperationParser.prototype, "getReturnValue", 1);
+__decorateClass([
+  experimental
+], OperationParser.prototype, "getReturnTypeHint", 1);
+__decorateClass([
+  experimental
+], OperationParser.prototype, "getPydocString", 1);
+__decorateClass([
+  experimental
+], OperationParser, "load", 1);
 OperationParser = __decorateClass([
   experimental
 ], OperationParser);

package/dist/esm/tools/openapi_tool/openapi_spec_parser/tool_auth_handler.js

@@ -16,71 +16,183 @@ var __decorateClass = (decorators, target, key, kind) => {
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import { cloneDeep } from "lodash-es";
+import {
+  isAuthCredential
+} from "../../../auth/auth_credential.js";
 import { experimental } from "../../../utils/experimental.js";
+import { stableHash } from "../../../utils/hash_utils.js";
+import { logger } from "../../../utils/logger.js";
 import { AutoAuthCredentialExchanger } from "../auth/credential_exchangers/auto_auth_credential_exchanger.js";
+import { AuthCredentialMissingError } from "../auth/credential_exchangers/base_auth_credential_exchanger.js";
+const DEFAULT_CREDENTIAL_KEY = "default_openapi_key";
 const _ToolContextCredentialStore = class _ToolContextCredentialStore {
   constructor(context) {
     this.context = context;
   }
-  getCredentialKey(authScheme) {
-    const schemeName = (authScheme == null ? void 0 : authScheme.type) || "default";
-    return `${schemeName}_existing_exchanged_credential`;
+  /**
+   * Returns the state key that holds the credential exchanged for this scheme
+   * and credential pair.
+   *
+   * Both operands are hashed into the key, so two tools configured with
+   * different schemes, or with different credentials under one scheme, never
+   * share a slot.
+   *
+   * The key deliberately carries no `temp:` prefix. Session state is a copy and
+   * only the delta is persisted, and `temp:` is cleared at the end of a run,
+   * while an exchanged token has to stay readable across runs.
+   */
+  getCredentialKey(authScheme, authCredential) {
+    const schemeName = authScheme ? `${authScheme.type}_${stableHash(authScheme)}` : "";
+    const credentialName = authCredential ? `${authCredential.authType}_${stableHash(authCredential)}` : "";
+    return `${schemeName}_${credentialName}_existing_exchanged_credential`;
   }
-  getCredential(authScheme) {
-    const key = this.getCredentialKey(authScheme);
-    return this.context.state.get(key);
+  /**
+   * Returns the credential stored for this scheme and credential pair, or
+   * `undefined` when there is none.
+   *
+   * @throws Error if the state entry under the key is not an
+   *     {@link AuthCredential}, which means something else wrote to the key.
+   */
+  getCredential(authScheme, authCredential) {
+    const key = this.getCredentialKey(authScheme, authCredential);
+    const stored = this.context.state.get(key);
+    if (stored === void 0 || stored === null) {
+      return void 0;
+    }
+    if (!isAuthCredential(stored)) {
+      throw new Error(
+        `State entry '${key}' is not an AuthCredential. Another writer has taken this key.`
+      );
+    }
+    return stored;
   }
   storeCredential(key, credential) {
-    this.context.state.set(key, credential);
+    this.context.state.set(key, JSON.parse(JSON.stringify(credential)));
+  }
+  /**
+   * Makes the credential under `key` unreadable again.
+   *
+   * adk-python deletes the state entry. `State` has no delete, so this writes
+   * `undefined`, which `State.get` returns for a missing key as well, and
+   * {@link getCredential} therefore misses exactly as a delete would make it.
+   */
+  removeCredential(key) {
+    this.context.state.set(key, void 0);
   }
 };
 __name(_ToolContextCredentialStore, "ToolContextCredentialStore");
 let ToolContextCredentialStore = _ToolContextCredentialStore;
 let ToolAuthHandler = class {
-  constructor(context, authScheme, authCredential, credentialKey) {
+  constructor(context, authScheme, authCredential, options = {}) {
     this.context = context;
-    this.authScheme = authScheme;
-    this.authCredential = authCredential;
-    this.credentialKey = credentialKey;
+    var _a;
+    this.authScheme = authScheme ? cloneDeep(authScheme) : void 0;
+    this.authCredential = authCredential ? cloneDeep(authCredential) : void 0;
+    this.credentialKey = options.credentialKey;
+    this.credentialExchanger = options.credentialExchanger;
+    this.credentialStore = (_a = options.credentialStore) != null ? _a : new ToolContextCredentialStore(context);
   }
   static fromToolContext(context, authScheme, authCredential, options = {}) {
-    return new ToolAuthHandler(
-      context,
-      authScheme,
-      authCredential,
-      options.credentialKey
-    );
+    return new ToolAuthHandler(context, authScheme, authCredential, options);
   }
   async prepareAuthCredentials() {
     if (!this.authScheme) {
       return { state: "done" };
     }
-    const store = new ToolContextCredentialStore(this.context);
-    const existingCredential = store.getCredential(this.authScheme);
+    const existingCredential = this.credentialStore.getCredential(
+      this.authScheme,
+      this.authCredential
+    );
     if (existingCredential) {
-      return { state: "done", authCredential: existingCredential };
+      return {
+        state: "done",
+        authScheme: this.authScheme,
+        authCredential: existingCredential
+      };
     }
     const authConfig = {
       authScheme: this.authScheme,
       rawAuthCredential: this.authCredential,
-      credentialKey: this.credentialKey || "default_openapi_key"
+      credentialKey: this.credentialKey || DEFAULT_CREDENTIAL_KEY
     };
     const authResponseCredential = this.context.getAuthResponse(authConfig);
     const credential = authResponseCredential != null ? authResponseCredential : this.authCredential;
-    if (!credential) {
-      this.context.requestCredential(authConfig);
-      return { state: "pending" };
+    const exchanged = credential ? await this.tryExchange(credential) : void 0;
+    if (!exchanged) {
+      this.requestCredential(authConfig);
+      return {
+        state: "pending",
+        authScheme: this.authScheme,
+        authCredential: this.authCredential
+      };
     }
-    const exchanger = new AutoAuthCredentialExchanger();
-    const result = await exchanger.exchange({
+    if (authResponseCredential || exchanged.wasExchanged) {
+      const key = this.credentialStore.getCredentialKey(
+        this.authScheme,
+        this.authCredential
+      );
+      this.credentialStore.storeCredential(key, exchanged.credential);
+    }
+    return {
+      state: "done",
       authScheme: this.authScheme,
-      authCredential: credential
-    });
-    if (authResponseCredential || result.wasExchanged) {
-      const key = store.getCredentialKey(this.authScheme);
-      store.storeCredential(key, result.credential);
+      authCredential: exchanged.credential
+    };
+  }
+  /**
+   * Exchanges `credential`, or returns `undefined` when the exchange failed.
+   *
+   * An exchange failure is transient far more often than it is fatal, so it
+   * becomes a `pending` result the client can resume from rather than an
+   * exception that fails the whole tool call.
+   */
+  async tryExchange(credential) {
+    var _a;
+    const exchanger = (_a = this.credentialExchanger) != null ? _a : new AutoAuthCredentialExchanger();
+    try {
+      return await exchanger.exchange({
+        authScheme: this.authScheme,
+        authCredential: credential
+      });
+    } catch (e) {
+      logger.error(
+        `Failed to exchange credential: ${e instanceof Error ? e.message : e}`
+      );
+      return void 0;
+    }
+  }
+  /**
+   * Asks the client for a credential, after checking that an interactive
+   * scheme has the OAuth2 client configuration it cannot proceed without.
+   *
+   * @throws Error if an `oauth2` or `openIdConnect` scheme has no OAuth2
+   *     credential.
+   * @throws AuthCredentialMissingError if that credential omits `clientId` or
+   *     `clientSecret`.
+   */
+  requestCredential(authConfig) {
+    var _a, _b;
+    const schemeType = (_a = this.authScheme) == null ? void 0 : _a.type;
+    if (schemeType === "oauth2" || schemeType === "openIdConnect") {
+      const oauth2 = (_b = this.authCredential) == null ? void 0 : _b.oauth2;
+      if (!oauth2) {
+        throw new Error(
+          `authCredential is empty for scheme ${schemeType}. Please create AuthCredential using OAuth2Auth.`
+        );
+      }
+      if (!oauth2.clientId) {
+        throw new AuthCredentialMissingError(
+          "OAuth2 credentials clientId is missing."
+        );
+      }
+      if (!oauth2.clientSecret) {
+        throw new AuthCredentialMissingError(
+          "OAuth2 credentials clientSecret is missing."
+        );
+      }
     }
-    return { state: "done", authCredential: result.credential };
+    this.context.requestCredential(authConfig);
   }
 };
 __name(ToolAuthHandler, "ToolAuthHandler");
@@ -94,5 +206,6 @@ ToolAuthHandler = __decorateClass([
   experimental
 ], ToolAuthHandler);
 export {
-  ToolAuthHandler
+  ToolAuthHandler,
+  ToolContextCredentialStore
 };

package/dist/esm/tools/openapi_tool/openapi_toolset.js

@@ -18,6 +18,7 @@ var __decorateClass = (decorators, target, key, kind) => {
  */
 import yaml from "js-yaml";
 import { experimental } from "../../utils/experimental.js";
+import { logger } from "../../utils/logger.js";
 import { BaseToolset } from "../base_toolset.js";
 import { OpenApiSpecParser } from "./openapi_spec_parser/openapi_spec_parser.js";
 import { createRestApiTool } from "./rest_api_tool.js";
@@ -29,8 +30,10 @@ let OpenAPIToolset = class extends BaseToolset {
     if (!spec && options.specStr) {
       if (options.specType === "yaml" || !options.specType && options.specStr.trim().startsWith("---")) {
         spec = yaml.load(options.specStr);
-      } else {
+      } else if (options.specType === "json" || !options.specType) {
         spec = JSON.parse(options.specStr);
+      } else {
+        throw new Error(`Unsupported spec type: ${options.specType}`);
       }
     }
     if (!spec) {
@@ -51,7 +54,9 @@ let OpenAPIToolset = class extends BaseToolset {
           description: op.description,
           endpoint: op.endpoint,
           operation: op.operation,
-          authScheme: op.authScheme
+          authScheme: op.authScheme,
+          parameters: op.parameters,
+          authCredential: op.authCredential
         },
         {
           preservePropertyNames: options.preservePropertyNames,
@@ -60,6 +65,7 @@ let OpenAPIToolset = class extends BaseToolset {
         }
       );
       this.tools.push(tool);
+      logger.info(`Parsed tool: ${tool.name}`);
     }
     if (options.authScheme || options.authCredential) {
       for (const tool of this.tools) {
@@ -80,6 +86,9 @@ let OpenAPIToolset = class extends BaseToolset {
       return true;
     });
   }
+  getTool(toolName) {
+    return this.tools.find((tool) => tool.name === toolName);
+  }
   async close() {
     return Promise.resolve();
   }
@@ -88,6 +97,9 @@ __name(OpenAPIToolset, "OpenAPIToolset");
 __decorateClass([
   experimental
 ], OpenAPIToolset.prototype, "getTools", 1);
+__decorateClass([
+  experimental
+], OpenAPIToolset.prototype, "getTool", 1);
 __decorateClass([
   experimental
 ], OpenAPIToolset.prototype, "close", 1);