@softactivate/adk 1.1.0 → 1.2.0

package/dist/types/tools/openapi_tool/auth/credential_exchangers/auto_auth_credential_exchanger.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AuthCredential } from '../../../../auth/auth_credential.js';
+import { AuthScheme } from '../../../../auth/auth_schemes.js';
+import { BaseCredentialExchanger, ExchangeResult } from '../../../../auth/exchanger/base_credential_exchanger.js';
+/**
+ * Automatically selects the appropriate credential exchanger based on the auth scheme.
+ * Ported from Python implementation.
+ */
+export declare class AutoAuthCredentialExchanger implements BaseCredentialExchanger {
+    private exchangers;
+    constructor();
+    exchange(params: {
+        authScheme?: AuthScheme;
+        authCredential: AuthCredential;
+    }): Promise<ExchangeResult>;
+}

package/dist/types/tools/openapi_tool/auth/credential_exchangers/service_account_exchanger.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AuthCredential } from '../../../../auth/auth_credential.js';
+import { AuthScheme } from '../../../../auth/auth_schemes.js';
+import { BaseCredentialExchanger, ExchangeResult } from '../../../../auth/exchanger/base_credential_exchanger.js';
+/**
+ * Fetches credentials for Google Service Account.
+ * Ported from Python implementation.
+ */
+export declare class ServiceAccountCredentialExchanger implements BaseCredentialExchanger {
+    exchange(params: {
+        authScheme?: AuthScheme;
+        authCredential: AuthCredential;
+    }): Promise<ExchangeResult>;
+    private exchangeForDefaultCredential;
+    private exchangeForExplicitCredential;
+}

package/dist/types/utils/file_utils.d.ts

@@ -9,3 +9,5 @@ import { File } from '../code_executors/code_execution_utils.js';
  * @param files The files to materialize.
  */
 export declare function materializeFiles(files: File[], dir?: string): Promise<File[]>;
+export declare const EXTENSION_TO_MIME_TYPE: Record<string, string>;
+export declare function guessMimeType(filePath: string): string;

package/dist/types/utils/partial_copy.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Copies a set of keys from one object to another.
+ *
+ * @param source The source object.
+ * @param targetKeys The keys to copy.
+ * @returns A new object with the specified keys copied from source.
+ */
+export declare function partialCopy<TDest extends object>(source: object, targetKeys: (keyof TDest)[]): TDest;

package/dist/types/utils/streaming_utils.d.ts

@@ -3,7 +3,7 @@
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { GenerateContentResponse } from '@google/genai';
+import { GenerateContentResponse, Part } from '@google/genai';
 import { LlmResponse } from '../models/llm_response.js';
 /**
  * Aggregates partial streaming responses.
@@ -17,24 +17,15 @@ export declare class StreamingResponseAggregator {
     private groundingMetadata?;
     private citationMetadata?;
     private response?;
-    private text;
-    private thoughtText;
-    private partsSequence;
-    private currentTextBuffer;
-    private currentTextIsThought?;
     private finishReason?;
-    private currentFcName?;
-    private currentFcArgs;
-    private currentFcId?;
-    private currentThoughtSignature?;
-    private lastThoughtSignature?;
+    private lastThoughtSignature;
+    private sawFunctionCall;
+    private readonly strategy;
     constructor(isProgressiveMode?: boolean);
-    private flushTextBufferToSequence;
-    private getValueFromPartialArg;
-    private setValueByJsonPath;
-    private flushFunctionCallToSequence;
-    private processStreamingFunctionCall;
-    private processFunctionCallPart;
     processResponse(response: GenerateContentResponse): AsyncGenerator<LlmResponse, void, void>;
     close(): LlmResponse | undefined;
 }
+/**
+ * Checks if a response part has no meaningful content (empty text, no tool calls, etc.)
+ */
+export declare function isEmptyContentPart(part: Part): boolean;

package/dist/types/utils/vertex_ai_utils.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Validates and returns the API key for Express Mode.
+ *
+ * @param project The project id.
+ * @param location The location.
+ * @param expressModeApiKey The API key for Express Mode.
+ * @returns The resolved API key or undefined.
+ */
+export declare function getExpressModeApiKey(project?: string, location?: string, expressModeApiKey?: string): string | undefined;

package/dist/types/version.d.ts

@@ -3,4 +3,4 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-export declare const version = "1.1.0";
+export declare const version = "1.2.0";

package/dist/web/agents/functions.js

@@ -177,6 +177,8 @@ function buildResponseEvent(tool, functionResult, toolContext, invocationContext
   let responseResult;
   if (typeof functionResult !== "object" || functionResult == null) {
     responseResult = { result: functionResult };
+  } else if (Array.isArray(functionResult)) {
+    responseResult = { results: functionResult };
   } else {
     responseResult = functionResult;
   }
@@ -411,6 +413,8 @@ async function handleFunctionCallList({
       functionResponse = { error: functionResponseError };
     } else if (typeof functionResponse !== "object" || functionResponse == null) {
       functionResponse = { result: functionResponse };
+    } else if (Array.isArray(functionResponse)) {
+      functionResponse = { results: functionResponse };
     }
     const functionResponseEvent = createEvent({
       invocationId: invocationContext.invocationId,

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

@@ -123,6 +123,18 @@ class OAuth2DiscoveryManager {
     return void 0;
   }
 }
+function normaliseHostname(raw) {
+  const stripped = raw.replace(/^\[|\]$/g, "");
+  const m = stripped.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i);
+  if (m) {
+    const hi = parseInt(m[1], 16);
+    const lo = parseInt(m[2], 16);
+    return [hi >> 8 & 255, hi & 255, lo >> 8 & 255, lo & 255].join(".");
+  }
+  const mDot = stripped.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i);
+  if (mDot) return mDot[1];
+  return raw;
+}
 function validateDiscoveryUrl(urlStr) {
   try {
     const url = new URL(urlStr);
@@ -130,8 +142,8 @@ function validateDiscoveryUrl(urlStr) {
       logger.warn("Unsafe protocol for discovery URL: ".concat(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.")) {
+    const host = normaliseHostname(url.hostname.toLowerCase());
+    if (host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host === "0.0.0.0" || host.startsWith("10.") || host.startsWith("192.168.") || host.startsWith("169.254.")) {
       logger.warn("Unsafe host for discovery URL: ".concat(host));
       return false;
     }
@@ -143,6 +155,18 @@ function validateDiscoveryUrl(urlStr) {
         return false;
       }
     }
+    const cgnatMatch = host.match(/^100\.(\d+)\./);
+    if (cgnatMatch) {
+      const secondOctet = parseInt(cgnatMatch[1], 10);
+      if (secondOctet >= 64 && secondOctet <= 127) {
+        logger.warn("Unsafe host for discovery URL: ".concat(host));
+        return false;
+      }
+    }
+    if (/^\[(f[cd][0-9a-f]{2}|fe[89ab][0-9a-f]):/i.test(url.hostname)) {
+      logger.warn("Unsafe host for discovery URL: ".concat(url.hostname));
+      return false;
+    }
     return true;
   } catch (e) {
     logger.warn("Failed to parse URL for validation ".concat(urlStr, ": ").concat(e));

package/dist/web/code_executors/agent_engine_sandbox_code_executor.js

@@ -0,0 +1,281 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Client } from "@google-cloud/vertexai";
+import { Language } from "@google-cloud/vertexai/build/src/genai/types.js";
+import { experimental } from "../utils/experimental.js";
+import { guessMimeType } from "../utils/file_utils.js";
+const SANDBOX_PATTERN = /^projects\/([a-zA-Z0-9-_]+)\/locations\/([a-zA-Z0-9-_]+)\/reasoningEngines\/(\d+)\/sandboxEnvironments\/(\d+)$/;
+const ENGINE_PATTERN = /^projects\/([a-zA-Z0-9-_]+)\/locations\/([a-zA-Z0-9-_]+)\/reasoningEngines\/(\d+)$/;
+import { logger } from "../utils/logger.js";
+import { BaseCodeExecutor } from "./base_code_executor.js";
+import {
+  CodeExecutionLanguage
+} from "./code_execution_utils.js";
+const DEFAULT_MAX_ATTEMPTS = 180;
+const DEFAULT_SANDBOX_TTL = "31536000s";
+const DEFAULT_SANDBOX_DISPLAY_NAME = "default_sandbox";
+const DEFAULT_ENGINE_DISPLAY_NAME = "default_engine";
+function mapLanguage(lang) {
+  switch (lang) {
+    case CodeExecutionLanguage.PYTHON:
+      return Language.LANGUAGE_PYTHON;
+    case CodeExecutionLanguage.JAVASCRIPT:
+      return Language.LANGUAGE_JAVASCRIPT;
+    default:
+      throw new Error("Unsupported language for Agent Engine Sandbox: ".concat(lang));
+  }
+}
+let AgentEngineSandboxCodeExecutor = class extends BaseCodeExecutor {
+  constructor(options = {}) {
+    super();
+    this.sandboxResourceName = options.sandboxResourceName;
+    this.agentEngineResourceName = options.agentEngineResourceName;
+    this.projectId = options.projectId || process.env.GOOGLE_CLOUD_PROJECT;
+    this.location = options.location || process.env.GOOGLE_CLOUD_LOCATION || "us-central1";
+    if (this.sandboxResourceName) {
+      const match = this.sandboxResourceName.match(SANDBOX_PATTERN);
+      if (match) {
+        this.projectId = match[1];
+        this.location = match[2];
+      } else {
+        throw new Error(
+          "Invalid sandbox resource name: ".concat(this.sandboxResourceName)
+        );
+      }
+    } else if (this.agentEngineResourceName) {
+      const match = this.agentEngineResourceName.match(ENGINE_PATTERN);
+      if (match) {
+        this.projectId = match[1];
+        this.location = match[2];
+      } else {
+        throw new Error(
+          "Invalid agent engine resource name: ".concat(this.agentEngineResourceName)
+        );
+      }
+    }
+    if (options.client) {
+      this.client = options.client;
+    } else {
+      if (!this.projectId) {
+        throw new Error("Project ID is required.");
+      }
+      this.client = new Client({
+        project: this.projectId,
+        location: this.location
+      });
+    }
+  }
+  async executeCode(params) {
+    var _a;
+    const { invocationContext, codeExecutionInput } = params;
+    const language = mapLanguage(codeExecutionInput.language);
+    const agentEngineName = await this.getOrCreateAgentEngine();
+    const sandboxName = await this.getOrCreateSandbox(
+      invocationContext,
+      agentEngineName,
+      language
+    );
+    const inputs = [
+      {
+        mimeType: "application/json",
+        data: Buffer.from(
+          JSON.stringify({ code: codeExecutionInput.code })
+        ).toString("base64")
+      }
+    ];
+    if (codeExecutionInput.inputFiles) {
+      for (const file of codeExecutionInput.inputFiles) {
+        inputs.push({
+          mimeType: file.mimeType,
+          data: file.content,
+          // Assumed to be already base64 encoded based on CodeExecutionInput definition
+          metadata: {
+            attributes: {
+              file_name: Buffer.from(file.name).toString("base64")
+            }
+          }
+        });
+      }
+    }
+    logger.debug("Executing code in sandbox ".concat(sandboxName, "..."));
+    const response = await this.client.agentEnginesInternal.sandboxes.executeCodeInternal({
+      name: sandboxName,
+      inputs
+    });
+    let stdout = "";
+    let stderr = "";
+    const outputFiles = [];
+    if (response.outputs) {
+      for (const output of response.outputs) {
+        const attributes = ((_a = output.metadata) == null ? void 0 : _a.attributes) || {};
+        const encodedFileName = attributes["file_name"];
+        const fileName = encodedFileName ? Buffer.from(encodedFileName, "base64").toString("utf-8") : void 0;
+        if (output.mimeType === "application/json" && !fileName) {
+          if (output.data) {
+            const jsonStr = Buffer.from(output.data, "base64").toString(
+              "utf-8"
+            );
+            try {
+              const jsonData = JSON.parse(jsonStr);
+              if (jsonData.msg_out !== void 0) {
+                stdout = jsonData.msg_out;
+              } else {
+                stdout = "";
+              }
+              if (jsonData.msg_err !== void 0) {
+                stderr = jsonData.msg_err;
+              } else {
+                stderr = "";
+              }
+            } catch (e) {
+              logger.warn("Failed to parse JSON output from sandbox", e);
+              stdout = jsonStr;
+            }
+          }
+        } else {
+          let mimeType = output.mimeType;
+          const name = fileName || "output_file";
+          if (!mimeType) {
+            mimeType = guessMimeType(name);
+          }
+          outputFiles.push({
+            name,
+            content: output.data || "",
+            mimeType
+          });
+        }
+      }
+    }
+    return {
+      stdout,
+      stderr,
+      outputFiles
+    };
+  }
+  async getOrCreateAgentEngine() {
+    if (this.agentEngineResourceName) {
+      return this.agentEngineResourceName;
+    }
+    if (!this.agentEngineCreationPromise) {
+      this.agentEngineCreationPromise = (async () => {
+        logger.debug(
+          "No Agent Engine resource name provided. Creating a new one..."
+        );
+        const operation = await this.client.agentEnginesInternal.createInternal(
+          {
+            config: {
+              displayName: DEFAULT_ENGINE_DISPLAY_NAME
+            }
+          }
+        );
+        let apiResponse = operation;
+        let attempts = 0;
+        while (!apiResponse.done && attempts < DEFAULT_MAX_ATTEMPTS) {
+          await new Promise((resolve) => setTimeout(resolve, 1e3));
+          apiResponse = await this.client.agentEnginesInternal.getAgentOperationInternal({
+            operationName: operation.name
+          });
+          attempts++;
+        }
+        if (!apiResponse.done) {
+          throw new Error(
+            "Agent Engine creation operation ".concat(operation.name, " did not complete in time.")
+          );
+        }
+        const response = apiResponse.response;
+        this.agentEngineResourceName = response.name;
+        logger.debug("Created Agent Engine: ".concat(this.agentEngineResourceName));
+        return this.agentEngineResourceName;
+      })();
+    }
+    return this.agentEngineCreationPromise;
+  }
+  async getOrCreateSandbox(invocationContext, agentEngineName, language) {
+    var _a, _b;
+    if (this.sandboxResourceName) {
+      return this.sandboxResourceName;
+    }
+    const stateKey = "sandbox_name_".concat(language.toLowerCase());
+    let sandboxName = (_b = (_a = invocationContext.session) == null ? void 0 : _a.state) == null ? void 0 : _b[stateKey];
+    let createNewSandbox = false;
+    if (!sandboxName) {
+      createNewSandbox = true;
+    } else {
+      try {
+        const sandbox = await this.client.agentEnginesInternal.sandboxes.getInternal({
+          name: sandboxName
+        });
+        if (!sandbox || sandbox.state !== "STATE_RUNNING") {
+          createNewSandbox = true;
+        }
+      } catch (error) {
+        logger.debug(
+          "Failed to get sandbox ".concat(sandboxName, ", will create a new one"),
+          error
+        );
+        createNewSandbox = true;
+      }
+    }
+    if (createNewSandbox) {
+      logger.debug("Creating a new ".concat(language, " code execution sandbox..."));
+      const operation = await this.client.agentEnginesInternal.sandboxes.createInternal({
+        name: agentEngineName,
+        spec: {
+          codeExecutionEnvironment: {
+            codeLanguage: language
+          }
+        },
+        config: {
+          displayName: DEFAULT_SANDBOX_DISPLAY_NAME,
+          ttl: DEFAULT_SANDBOX_TTL
+        }
+      });
+      let apiResponse = operation;
+      let attempts = 0;
+      while (!apiResponse.done && attempts < DEFAULT_MAX_ATTEMPTS) {
+        await new Promise((resolve) => setTimeout(resolve, 1e3));
+        apiResponse = await this.client.agentEnginesInternal.sandboxes.getSandboxOperationInternal(
+          {
+            operationName: operation.name
+          }
+        );
+        attempts++;
+      }
+      if (!apiResponse.done) {
+        throw new Error(
+          "Sandbox creation operation ".concat(operation.name, " did not complete in time.")
+        );
+      }
+      const response = apiResponse.response;
+      sandboxName = response.name;
+      if (invocationContext.session) {
+        if (!invocationContext.session.state) {
+          invocationContext.session.state = {};
+        }
+        invocationContext.session.state[stateKey] = sandboxName;
+      }
+    }
+    return sandboxName;
+  }
+};
+AgentEngineSandboxCodeExecutor = __decorateClass([
+  experimental
+], AgentEngineSandboxCodeExecutor);
+export {
+  AgentEngineSandboxCodeExecutor
+};

package/dist/web/code_executors/code_execution_utils.js

@@ -47,7 +47,7 @@ function extractCodeAndTruncateContent(content, codeBlockDelimiters) {
   const leadingDelimiterPattern = codeBlockDelimiters.map((d) => d[0]).join("|");
   const trailingDelimiterPattern = codeBlockDelimiters.map((d) => d[1]).join("|");
   const match = new RegExp(
-    "?<prefix>.*?)(".concat(leadingDelimiterPattern, ")(?<codeStr>.*?)(").concat(trailingDelimiterPattern, ")(?<suffix>.*?)$"),
+    "(?<prefix>.*?)(".concat(leadingDelimiterPattern, ")(?<codeStr>.*?)(").concat(trailingDelimiterPattern, ")(?<suffix>.*?)$"),
     "s"
   ).exec(responseText);
   const { prefix, codeStr } = (match == null ? void 0 : match.groups) || {};

package/dist/web/common.js

@@ -64,6 +64,7 @@ import {
   isBaseExampleProvider
 } from "./examples/base_example_provider.js";
 import { InMemoryMemoryService } from "./memory/in_memory_memory_service.js";
+import { VertexAiMemoryBankService } from "./memory/vertex_ai_memory_bank_service.js";
 import { ApigeeLlm } from "./models/apigee_llm.js";
 import { BaseLlm, isBaseLlm } from "./models/base_llm.js";
 import { Gemini, geminiInitParams } from "./models/google_llm.js";
@@ -208,6 +209,7 @@ export {
   TruncatingContextCompactor,
   URL_CONTEXT,
   UrlContextTool,
+  VertexAiMemoryBankService,
   VertexAiSearchTool,
   VertexRagRetrievalTool,
   createEvent,

package/dist/web/events/event.js

@@ -97,6 +97,7 @@ const PRESERVE_KEYS_CAMEL_CASE = [
   "actions.requestedAuthConfigs",
   "actions.requestedToolConfirmations",
   "actions.customMetadata",
+  "customMetadata",
   "content.parts.functionCall.args",
   "content.parts.functionResponse.response"
 ];
@@ -106,6 +107,7 @@ const PRESERVE_KEYS_SNAKE_CASE = [
   "actions.requested_auth_configs",
   "actions.requested_tool_confirmations",
   "actions.custom_metadata",
+  "custom_metadata",
   "content.parts.function_call.args",
   "content.parts.function_response.response"
 ];

package/dist/web/index.js

@@ -9,15 +9,21 @@ import { AGENT_CARD_PATH, RemoteA2AAgent } from "./a2a/a2a_remote_agent.js";
 import { getA2AAgentCard } from "./a2a/agent_card.js";
 import { A2AAgentExecutor } from "./a2a/agent_executor.js";
 import { toA2a } from "./a2a/agent_to_a2a.js";
+import { InvocationContext } from "./agents/invocation_context.js";
 import { FileArtifactService } from "./artifacts/file_artifact_service.js";
 import { GcsArtifactService } from "./artifacts/gcs_artifact_service.js";
 import { getArtifactServiceFromUri } from "./artifacts/registry.js";
+import {
+  AgentEngineSandboxCodeExecutor
+} from "./code_executors/agent_engine_sandbox_code_executor.js";
+import { CodeExecutionLanguage } from "./code_executors/code_execution_utils.js";
 import {
   UnsafeLocalCodeExecutor
 } from "./code_executors/unsafe_local_code_executor.js";
 export * from "./common.js";
 import { DatabaseSessionService } from "./sessions/database_session_service.js";
 import { getSessionServiceFromUri } from "./sessions/registry.js";
+import { VertexAiSessionService } from "./sessions/vertex_ai_session_service.js";
 import {
   loadAllSkillsInDir,
   loadSkillFromDir,
@@ -25,6 +31,7 @@ import {
 } from "./skills/loader.js";
 import { RunSkillInlineScriptTool } from "./tools/skill/run_skill_inline_script_tool.js";
 import { RunSkillScriptTool } from "./tools/skill/run_skill_script_tool.js";
+export * from "./integrations/agent_registry/agent_registry.js";
 export * from "./telemetry/google_cloud.js";
 export * from "./telemetry/setup.js";
 export * from "./tools/mcp/mcp_session_manager.js";
@@ -33,13 +40,17 @@ export * from "./tools/mcp/mcp_toolset.js";
 export {
   A2AAgentExecutor,
   AGENT_CARD_PATH,
+  AgentEngineSandboxCodeExecutor,
+  CodeExecutionLanguage,
   DatabaseSessionService,
   FileArtifactService,
   GcsArtifactService,
+  InvocationContext,
   RemoteA2AAgent,
   RunSkillInlineScriptTool,
   RunSkillScriptTool,
   UnsafeLocalCodeExecutor,
+  VertexAiSessionService,
   getA2AAgentCard,
   getArtifactServiceFromUri,
   getSessionServiceFromUri,