@softactivate/adk 1.1.0

package/dist/esm/auth/oauth2/oauth2_credential_exchanger.js

@@ -0,0 +1,177 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { logger } from "../../utils/logger.js";
+import {
+  getOAuthGrantTypeFromFlow,
+  OAuthGrantType
+} from "../auth_schemes.js";
+import {
+  CredentialExchangeError
+} from "../exchanger/base_credential_exchanger.js";
+import {
+  createOAuth2TokenRequestBody,
+  fetchOAuth2Tokens,
+  getTokenEndpoint,
+  parseAuthorizationCode
+} from "./oauth2_utils.js";
+class OAuth2CredentialExchanger {
+  async exchange({
+    authCredential,
+    authScheme
+  }) {
+    var _a;
+    if (!authScheme) {
+      throw new CredentialExchangeError(
+        "authScheme is required for OAuth2 credential exchange"
+      );
+    }
+    if ((_a = authCredential.oauth2) == null ? void 0 : _a.accessToken) {
+      return {
+        credential: authCredential,
+        wasExchanged: false
+      };
+    }
+    const grantType = determineGrantType(authScheme);
+    if (grantType === OAuthGrantType.CLIENT_CREDENTIALS) {
+      return exchangeClientCredentials({ authCredential, authScheme });
+    }
+    if (grantType === OAuthGrantType.AUTHORIZATION_CODE) {
+      return exchangeAuthorizationCode({ authCredential, authScheme });
+    }
+    logger.warn(`Unsupported OAuth2 grant type: ${grantType}`);
+    return {
+      credential: authCredential,
+      wasExchanged: false
+    };
+  }
+}
+function determineGrantType(authScheme) {
+  var _a;
+  if ("flows" in authScheme && authScheme.flows) {
+    return getOAuthGrantTypeFromFlow(authScheme.flows);
+  }
+  if (authScheme.grantTypesSupported) {
+    const oidcScheme = authScheme;
+    if ((_a = oidcScheme.grantTypesSupported) == null ? void 0 : _a.includes("client_credentials")) {
+      return OAuthGrantType.CLIENT_CREDENTIALS;
+    }
+    return OAuthGrantType.AUTHORIZATION_CODE;
+  }
+  return void 0;
+}
+async function exchangeClientCredentials({
+  authCredential,
+  authScheme
+}) {
+  var _a, _b;
+  const tokenEndpoint = getTokenEndpoint(authScheme);
+  if (!tokenEndpoint) {
+    throw new CredentialExchangeError(
+      "Token endpoint not found in auth scheme."
+    );
+  }
+  if (!((_a = authCredential.oauth2) == null ? void 0 : _a.clientId) || !((_b = authCredential.oauth2) == null ? void 0 : _b.clientSecret)) {
+    throw new CredentialExchangeError(
+      "clientId and clientSecret are required for client credentials exchange."
+    );
+  }
+  const body = createOAuth2TokenRequestBody({
+    grantType: "client_credentials",
+    clientId: authCredential.oauth2.clientId,
+    clientSecret: authCredential.oauth2.clientSecret
+  });
+  try {
+    const oauth2Auth = await fetchOAuth2Tokens(tokenEndpoint, body);
+    return {
+      credential: {
+        ...authCredential,
+        oauth2: {
+          ...authCredential.oauth2,
+          ...oauth2Auth
+        }
+      },
+      wasExchanged: true
+    };
+  } catch (error) {
+    throw new CredentialExchangeError(
+      `Failed to exchange tokens: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+async function exchangeAuthorizationCode({
+  authCredential,
+  authScheme
+}) {
+  var _a, _b, _c, _d;
+  const tokenEndpoint = getTokenEndpoint(authScheme);
+  if (!tokenEndpoint) {
+    throw new CredentialExchangeError(
+      "Token endpoint not found in auth scheme."
+    );
+  }
+  if (!((_a = authCredential.oauth2) == null ? void 0 : _a.clientId) || !((_b = authCredential.oauth2) == null ? void 0 : _b.clientSecret) || !((_c = authCredential.oauth2) == null ? void 0 : _c.authCode) && !((_d = authCredential.oauth2) == null ? void 0 : _d.authResponseUri)) {
+    throw new CredentialExchangeError(
+      "clientId, clientSecret, and either authCode or authResponseUri are required for authorization code exchange."
+    );
+  }
+  let code = authCredential.oauth2.authCode;
+  if (!code && authCredential.oauth2.authResponseUri) {
+    code = parseAuthorizationCode(authCredential.oauth2.authResponseUri);
+  }
+  if (authCredential.oauth2.authResponseUri && authCredential.oauth2.state) {
+    try {
+      const url = new URL(authCredential.oauth2.authResponseUri);
+      const receivedState = url.searchParams.get("state") || void 0;
+      if (authCredential.oauth2.state !== receivedState) {
+        throw new CredentialExchangeError(
+          "State mismatch detected. Potential CSRF attack."
+        );
+      }
+    } catch (e) {
+      throw new CredentialExchangeError(
+        `Failed to parse authResponseUri for state validation: ${e instanceof Error ? e.message : String(e)}`
+      );
+    }
+  }
+  if (!code) {
+    throw new CredentialExchangeError(
+      "Authorization code not found in auth response."
+    );
+  }
+  const body = createOAuth2TokenRequestBody({
+    grantType: "authorization_code",
+    clientId: authCredential.oauth2.clientId,
+    clientSecret: authCredential.oauth2.clientSecret,
+    code,
+    redirectUri: authCredential.oauth2.redirectUri,
+    codeVerifier: authCredential.oauth2.codeVerifier
+  });
+  try {
+    const oauth2Auth = await fetchOAuth2Tokens(tokenEndpoint, body);
+    return {
+      credential: {
+        ...authCredential,
+        oauth2: {
+          ...authCredential.oauth2,
+          ...oauth2Auth
+        }
+      },
+      wasExchanged: true
+    };
+  } catch (error) {
+    throw new CredentialExchangeError(
+      `Failed to exchange tokens: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+export {
+  OAuth2CredentialExchanger,
+  determineGrantType,
+  exchangeAuthorizationCode,
+  exchangeClientCredentials
+};

package/dist/esm/auth/oauth2/oauth2_credential_refresher.js

@@ -0,0 +1,85 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { logger } from "../../utils/logger.js";
+import {
+  fetchOAuth2Tokens,
+  getTokenEndpoint,
+  isTokenExpired
+} from "./oauth2_utils.js";
+class OAuth2CredentialRefresher {
+  /**
+   * Check if the OAuth2 credential needs to be refreshed.
+   *
+   * @param authCredential The OAuth2 credential to check.
+   * @param authScheme The OAuth2 authentication scheme (optional).
+   * @returns True if the credential needs to be refreshed, False otherwise.
+   */
+  async isRefreshNeeded(authCredential) {
+    if (!authCredential.oauth2) {
+      return false;
+    }
+    if (authCredential.oauth2 && authCredential.oauth2.expiresAt) {
+      return isTokenExpired(authCredential.oauth2);
+    }
+    return false;
+  }
+  /**
+   * Refresh the OAuth2 credential.
+   *
+   * @param authCredential The OAuth2 credential to refresh.
+   * @param authScheme The OAuth2 authentication scheme.
+   * @returns The refreshed credential.
+   */
+  async refresh(authCredential, authScheme) {
+    if (!authCredential.oauth2 || !authScheme) {
+      return authCredential;
+    }
+    if (!authCredential.oauth2.refreshToken) {
+      logger.warn("No refresh token available to refresh credential");
+      return authCredential;
+    }
+    const isNeeded = await this.isRefreshNeeded(authCredential);
+    if (!isNeeded) {
+      return authCredential;
+    }
+    const tokenEndpoint = getTokenEndpoint(authScheme);
+    if (!tokenEndpoint) {
+      logger.warn("Token endpoint not found in auth scheme.");
+      return authCredential;
+    }
+    if (!authCredential.oauth2.clientId || !authCredential.oauth2.clientSecret) {
+      logger.warn("clientId and clientSecret are required for token refresh.");
+      return authCredential;
+    }
+    const body = new URLSearchParams();
+    body.set("grant_type", "refresh_token");
+    body.set("refresh_token", authCredential.oauth2.refreshToken);
+    body.set("client_id", authCredential.oauth2.clientId);
+    body.set("client_secret", authCredential.oauth2.clientSecret);
+    try {
+      const data = await fetchOAuth2Tokens(tokenEndpoint, body);
+      const updatedOAuth2 = {
+        ...authCredential.oauth2,
+        accessToken: data.accessToken || authCredential.oauth2.accessToken,
+        refreshToken: data.refreshToken || authCredential.oauth2.refreshToken,
+        expiresIn: data.expiresIn,
+        expiresAt: data.expiresAt || authCredential.oauth2.expiresAt
+      };
+      return {
+        ...authCredential,
+        oauth2: updatedOAuth2
+      };
+    } catch (error) {
+      logger.error("Failed to refresh tokens:", error);
+      return authCredential;
+    }
+  }
+}
+export {
+  OAuth2CredentialRefresher
+};

package/dist/esm/auth/oauth2/oauth2_discovery.js

@@ -0,0 +1,156 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { z } from "zod";
+import { logger } from "../../utils/logger.js";
+const AuthorizationServerMetadataSchema = z.object({
+  issuer: z.string(),
+  authorization_endpoint: z.string(),
+  token_endpoint: z.string(),
+  scopes_supported: z.array(z.string()).optional(),
+  registration_endpoint: z.string().optional()
+});
+const ProtectedResourceMetadataSchema = z.object({
+  resource: z.string(),
+  authorization_servers: z.array(z.string()).default([])
+});
+class OAuth2DiscoveryManager {
+  /**
+   * Discovers the OAuth2 authorization server metadata.
+   */
+  async discoverAuthServerMetadata(issuerUrl) {
+    if (!validateDiscoveryUrl(issuerUrl)) {
+      return void 0;
+    }
+    let baseUrl;
+    let path;
+    try {
+      const url = new URL(issuerUrl);
+      baseUrl = `${url.protocol}//${url.host}`;
+      path = url.pathname;
+    } catch (e) {
+      logger.warn(`Failed to parse issuerUrl ${issuerUrl}: ${e}`);
+      return void 0;
+    }
+    const endpointsToTry = [];
+    if (path && path !== "/") {
+      endpointsToTry.push(
+        `${baseUrl}/.well-known/oauth-authorization-server${path}`,
+        `${baseUrl}/.well-known/openid-configuration${path}`,
+        `${baseUrl}${path}/.well-known/openid-configuration`
+      );
+    } else {
+      endpointsToTry.push(
+        `${baseUrl}/.well-known/oauth-authorization-server`,
+        `${baseUrl}/.well-known/openid-configuration`
+      );
+    }
+    for (const endpoint of endpointsToTry) {
+      try {
+        const response = await fetch(endpoint, {
+          method: "GET",
+          headers: {
+            Accept: "application/json"
+          }
+        });
+        if (!response.ok) {
+          continue;
+        }
+        const data = await response.json();
+        const metadata = AuthorizationServerMetadataSchema.parse(data);
+        if (metadata.issuer.replace(/\/$/, "") === issuerUrl.replace(/\/$/, "")) {
+          return metadata;
+        } else {
+          logger.warn(
+            `Issuer in metadata ${metadata.issuer} does not match issuerUrl ${issuerUrl}`
+          );
+        }
+      } catch (e) {
+        logger.debug(`Failed to fetch metadata from ${endpoint}: ${e}`);
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Discovers the OAuth2 protected resource metadata.
+   */
+  async discoverResourceMetadata(resourceUrl) {
+    if (!validateDiscoveryUrl(resourceUrl)) {
+      return void 0;
+    }
+    let baseUrl;
+    let path;
+    try {
+      const url = new URL(resourceUrl);
+      baseUrl = `${url.protocol}//${url.host}`;
+      path = url.pathname;
+    } catch (e) {
+      logger.warn(`Failed to parse resourceUrl ${resourceUrl}: ${e}`);
+      return void 0;
+    }
+    let wellKnownEndpoint;
+    if (path && path !== "/") {
+      wellKnownEndpoint = `${baseUrl}/.well-known/oauth-protected-resource${path}`;
+    } else {
+      wellKnownEndpoint = `${baseUrl}/.well-known/oauth-protected-resource`;
+    }
+    try {
+      const response = await fetch(wellKnownEndpoint, {
+        method: "GET",
+        headers: {
+          Accept: "application/json"
+        }
+      });
+      if (!response.ok) {
+        return void 0;
+      }
+      const data = await response.json();
+      const metadata = ProtectedResourceMetadataSchema.parse(data);
+      if (metadata.resource.replace(/\/$/, "") === resourceUrl.replace(/\/$/, "")) {
+        return metadata;
+      } else {
+        logger.warn(
+          `Resource in metadata ${metadata.resource} does not match resourceUrl ${resourceUrl}`
+        );
+      }
+    } catch (e) {
+      logger.debug(`Failed to fetch metadata from ${wellKnownEndpoint}: ${e}`);
+    }
+    return void 0;
+  }
+}
+function validateDiscoveryUrl(urlStr) {
+  try {
+    const url = new URL(urlStr);
+    if (url.protocol !== "https:") {
+      logger.warn(`Unsafe protocol for discovery URL: ${url.protocol}`);
+      return false;
+    }
+    const host = url.hostname.toLowerCase();
+    if (host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host.startsWith("10.") || host.startsWith("192.168.") || host.startsWith("169.254.")) {
+      logger.warn(`Unsafe host for discovery URL: ${host}`);
+      return false;
+    }
+    const match = host.match(/^172\.(\d+)\./);
+    if (match) {
+      const secondOctet = parseInt(match[1], 10);
+      if (secondOctet >= 16 && secondOctet <= 31) {
+        logger.warn(`Unsafe host for discovery URL: ${host}`);
+        return false;
+      }
+    }
+    return true;
+  } catch (e) {
+    logger.warn(`Failed to parse URL for validation ${urlStr}: ${e}`);
+    return false;
+  }
+}
+export {
+  AuthorizationServerMetadataSchema,
+  OAuth2DiscoveryManager,
+  ProtectedResourceMetadataSchema
+};

package/dist/esm/auth/oauth2/oauth2_utils.js

@@ -0,0 +1,87 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { logger } from "../../utils/logger.js";
+function getTokenEndpoint(authScheme) {
+  if (authScheme.type === "openIdConnect" && authScheme.tokenEndpoint) {
+    return authScheme.tokenEndpoint;
+  }
+  if (authScheme.type === "oauth2" && authScheme.flows) {
+    const flows = authScheme.flows;
+    const flow = flows.authorizationCode || flows.clientCredentials || flows.password || flows.implicit;
+    if (flow && "tokenUrl" in flow) {
+      return flow.tokenUrl;
+    }
+  }
+  return void 0;
+}
+async function fetchOAuth2Tokens(endpoint, body) {
+  try {
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded"
+      },
+      body: body.toString()
+    });
+    if (!response.ok) {
+      throw new Error(`Token request failed with status ${response.status}`);
+    }
+    const data = await response.json();
+    return {
+      accessToken: data.access_token,
+      refreshToken: data.refresh_token,
+      idToken: data.id_token,
+      expiresIn: data.expires_in,
+      expiresAt: data.expires_in ? Date.now() + data.expires_in * 1e3 : void 0
+    };
+  } catch (e) {
+    logger.error(`Failed to fetch OAuth2 tokens: ${e}`);
+    throw e;
+  }
+}
+function parseAuthorizationCode(uri) {
+  try {
+    const url = new URL(uri);
+    return url.searchParams.get("code") || void 0;
+  } catch (e) {
+    logger.warn(`Failed to parse authorization URI ${uri}: ${e}`);
+    return void 0;
+  }
+}
+function createOAuth2TokenRequestBody(params) {
+  const body = new URLSearchParams();
+  body.set("grant_type", params.grantType);
+  body.set("client_id", params.clientId);
+  body.set("client_secret", params.clientSecret);
+  if (params.grantType === "authorization_code") {
+    body.set("code", params.code);
+    if (params.redirectUri) {
+      body.set("redirect_uri", params.redirectUri);
+    }
+    if (params.codeVerifier) {
+      body.set("code_verifier", params.codeVerifier);
+    }
+  } else if (params.grantType === "refresh_token") {
+    body.set("refresh_token", params.refreshToken);
+  }
+  return body;
+}
+function isTokenExpired(token, leeway = 60) {
+  if (typeof token.expiresAt !== "number") {
+    return false;
+  }
+  const expirationThreshold = token.expiresAt - leeway * 1e3;
+  return expirationThreshold < Date.now();
+}
+export {
+  createOAuth2TokenRequestBody,
+  fetchOAuth2Tokens,
+  getTokenEndpoint,
+  isTokenExpired,
+  parseAuthorizationCode
+};

package/dist/esm/auth/refresher/base_credential_refresher.js

@@ -0,0 +1,16 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+class CredentialRefresherError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CredentialRefresherError";
+  }
+}
+export {
+  CredentialRefresherError
+};

package/dist/esm/auth/refresher/credential_refresher_registry.js

@@ -0,0 +1,40 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AuthCredentialTypes } from "../auth_credential.js";
+class CredentialRefresherRegistry {
+  constructor() {
+    this.refreshers = {
+      [AuthCredentialTypes.API_KEY]: void 0,
+      [AuthCredentialTypes.HTTP]: void 0,
+      [AuthCredentialTypes.OAUTH2]: void 0,
+      [AuthCredentialTypes.OPEN_ID_CONNECT]: void 0,
+      [AuthCredentialTypes.SERVICE_ACCOUNT]: void 0
+    };
+  }
+  /**
+   * Register a refresher instance for a credential type.
+   *
+   * @param credentialType The credential type to register for.
+   * @param refresherInstance The refresher instance to register.
+   */
+  register(credentialType, refresherInstance) {
+    this.refreshers[credentialType] = refresherInstance;
+  }
+  /**
+   * Get the refresher instance for a credential type.
+   *
+   * @param credentialType The credential type to get refresher for.
+   * @returns The refresher instance if registered, undefined otherwise.
+   */
+  getRefresher(credentialType) {
+    return this.refreshers[credentialType];
+  }
+}
+export {
+  CredentialRefresherRegistry
+};

package/dist/esm/code_executors/base_code_executor.js

@@ -0,0 +1,63 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+var _a;
+const BASE_CODE_EXECUTOR_SIGNATURE_SYMBOL = Symbol.for(
+  "google.adk.baseCodeExecutor"
+);
+function isBaseCodeExecutor(obj) {
+  return typeof obj === "object" && obj !== null && BASE_CODE_EXECUTOR_SIGNATURE_SYMBOL in obj && obj[BASE_CODE_EXECUTOR_SIGNATURE_SYMBOL] === true;
+}
+_a = BASE_CODE_EXECUTOR_SIGNATURE_SYMBOL;
+class BaseCodeExecutor {
+  constructor() {
+    /** A unique symbol to identify BaseCodeExecutor class. */
+    this[_a] = true;
+    /**
+     * If true, extract and process data files from the model request
+     * and attach them to the code executor.
+     *
+     * Supported data file MimeTypes are [text/csv].
+     * Default to false.
+     */
+    this.optimizeDataFile = false;
+    /**
+     * Whether the code executor is stateful. Default to false.
+     */
+    this.stateful = false;
+    /**
+     * The number of attempts to retry on consecutive code execution errors.
+     * Default to 2.
+     */
+    this.errorRetryAttempts = 2;
+    /**
+     * The list of the enclosing delimiters to identify the code blocks.
+     * For example, the delimiter('```javascript\\n', '\\n```') can be used to
+     * identify code blocks with the following format:
+     *
+     * ```javascript
+     *  console.log("hello")
+     * ```
+     */
+    this.codeBlockDelimiters = [
+      ["```tool_code\n", "\n```"],
+      ["```python\n", "\n```"],
+      ["```javascript\n", "\n```"],
+      ["```typescript\n", "\n```"],
+      ["```bash\n", "\n```"],
+      ["```sh\n", "\n```"]
+    ];
+    /**
+     * The delimiters to format the code execution result.
+     */
+    this.executionResultDelimiters = ["```tool_output\n", "\n```"];
+  }
+}
+export {
+  BaseCodeExecutor,
+  isBaseCodeExecutor
+};

package/dist/esm/code_executors/built_in_code_executor.js

@@ -0,0 +1,45 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+var _a, _b;
+import { isGemini2OrAbove } from "../utils/model_name.js";
+import { BaseCodeExecutor } from "./base_code_executor.js";
+const BUILT_IN_CODE_EXECUTOR_SIGNATURE_SYMBOL = Symbol.for(
+  "google.adk.builtInCodeExecutor"
+);
+function isBuiltInCodeExecutor(obj) {
+  return typeof obj === "object" && obj !== null && BUILT_IN_CODE_EXECUTOR_SIGNATURE_SYMBOL in obj && obj[BUILT_IN_CODE_EXECUTOR_SIGNATURE_SYMBOL] === true;
+}
+class BuiltInCodeExecutor extends (_b = BaseCodeExecutor, _a = BUILT_IN_CODE_EXECUTOR_SIGNATURE_SYMBOL, _b) {
+  constructor() {
+    super(...arguments);
+    /** A unique symbol to identify BuiltInCodeExecutor class. */
+    this[_a] = true;
+  }
+  executeCode(_params) {
+    return Promise.resolve({
+      stdout: "",
+      stderr: "",
+      outputFiles: []
+    });
+  }
+  processLlmRequest(llmRequest) {
+    if (llmRequest.model && isGemini2OrAbove(llmRequest.model)) {
+      llmRequest.config = llmRequest.config || {};
+      llmRequest.config.tools = llmRequest.config.tools || [];
+      llmRequest.config.tools.push({ codeExecution: {} });
+      return;
+    }
+    throw new Error(
+      `Gemini code execution tool is not supported for model ${llmRequest.model}`
+    );
+  }
+}
+export {
+  BuiltInCodeExecutor,
+  isBuiltInCodeExecutor
+};