@paean-ai/adk 0.2.16 → 0.2.17

package/dist/web/tools/forwarding_artifact_service.js

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+class ForwardingArtifactService {
+  constructor(toolContext) {
+    this.toolContext = toolContext;
+    this.invocationContext = toolContext.invocationContext;
+  }
+  // TODO - b/425992518: Remove unnecessary parameters. We should rethink the
+  // abstraction layer to make it more clear.
+  async saveArtifact(request) {
+    return this.toolContext.saveArtifact(request.filename, request.artifact);
+  }
+  async loadArtifact(request) {
+    return this.toolContext.loadArtifact(request.filename, request.version);
+  }
+  async listArtifactKeys(request) {
+    return this.toolContext.listArtifacts();
+  }
+  async deleteArtifact(request) {
+    if (!this.toolContext.invocationContext.artifactService) {
+      throw new Error("Artifact service is not initialized.");
+    }
+    return this.toolContext.invocationContext.artifactService.deleteArtifact(
+      request
+    );
+  }
+  async listVersions(request) {
+    if (!this.toolContext.invocationContext.artifactService) {
+      throw new Error("Artifact service is not initialized.");
+    }
+    return this.toolContext.invocationContext.artifactService.listVersions(
+      request
+    );
+  }
+}
+export {
+  ForwardingArtifactService
+};

package/dist/web/tools/function_tool.js

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Type } from "@google/genai";
+import { ZodObject } from "zod";
+import { isZodObject, zodObjectToSchema } from "../utils/simple_zod_to_json.js";
+import { BaseTool } from "./base_tool.js";
+function toSchema(parameters) {
+  if (parameters === void 0) {
+    return { type: Type.OBJECT, properties: {} };
+  }
+  if (isZodObject(parameters)) {
+    return zodObjectToSchema(parameters);
+  }
+  return parameters;
+}
+class FunctionTool extends BaseTool {
+  /**
+   * The constructor acts as the user-friendly factory.
+   * @param options The configuration for the tool.
+   */
+  constructor(options) {
+    var _a;
+    const name = (_a = options.name) != null ? _a : options.execute.name;
+    if (!name) {
+      throw new Error(
+        "Tool name cannot be empty. Either name the `execute` function or provide a `name`."
+      );
+    }
+    super({
+      name,
+      description: options.description,
+      isLongRunning: options.isLongRunning
+    });
+    this.execute = options.execute;
+    this.parameters = options.parameters;
+  }
+  /**
+   * Provide a schema for the function.
+   */
+  _getDeclaration() {
+    return {
+      name: this.name,
+      description: this.description,
+      parameters: toSchema(this.parameters)
+    };
+  }
+  /**
+   * Logic for running the tool.
+   */
+  async runAsync(req) {
+    try {
+      let validatedArgs = req.args;
+      if (this.parameters instanceof ZodObject) {
+        validatedArgs = this.parameters.parse(req.args);
+      }
+      return await this.execute(
+        validatedArgs,
+        req.toolContext
+      );
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new Error("Error in tool '".concat(this.name, "': ").concat(errorMessage));
+    }
+  }
+}
+export {
+  FunctionTool
+};

package/dist/web/tools/google_search_tool.js

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { isGemini1Model, isGeminiModel } from "../utils/model_name.js";
+import { BaseTool } from "./base_tool.js";
+class GoogleSearchTool extends BaseTool {
+  constructor() {
+    super({ name: "google_search", description: "Google Search Tool" });
+  }
+  runAsync(request) {
+    return Promise.resolve();
+  }
+  async processLlmRequest({ toolContext, llmRequest }) {
+    if (!llmRequest.model) {
+      return;
+    }
+    llmRequest.toolsDict[this.name] = this;
+    llmRequest.config = llmRequest.config || {};
+    llmRequest.config.tools = llmRequest.config.tools || [];
+    if (isGemini1Model(llmRequest.model)) {
+      if (llmRequest.config.tools.length > 0) {
+        throw new Error(
+          "Google search tool can not be used with other tools in Gemini 1.x."
+        );
+      }
+      llmRequest.config.tools.push({
+        googleSearchRetrieval: {}
+      });
+      return;
+    }
+    if (isGeminiModel(llmRequest.model)) {
+      llmRequest.config.tools.push({
+        googleSearch: {}
+      });
+      return;
+    }
+    throw new Error(
+      "Google search tool is not supported for model ".concat(llmRequest.model)
+    );
+  }
+}
+const GOOGLE_SEARCH = new GoogleSearchTool();
+export {
+  GOOGLE_SEARCH
+};

package/dist/web/tools/long_running_tool.js

@@ -0,0 +1,50 @@
+var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { FunctionTool } from "./function_tool.js";
+const LONG_RUNNING_INSTRUCTION = "\n\nNOTE: This is a long-running operation. Do not call this tool again if it has already returned some intermediate or pending status.";
+class LongRunningFunctionTool extends FunctionTool {
+  /**
+   * The constructor acts as the user-friendly factory.
+   * @param options The configuration for the tool.
+   */
+  constructor(options) {
+    super(__spreadProps(__spreadValues({}, options), { isLongRunning: true }));
+  }
+  /**
+   * Provide a schema for the function.
+   */
+  _getDeclaration() {
+    const declaration = super._getDeclaration();
+    if (declaration.description) {
+      declaration.description += LONG_RUNNING_INSTRUCTION;
+    } else {
+      declaration.description = LONG_RUNNING_INSTRUCTION.trimStart();
+    }
+    return declaration;
+  }
+}
+export {
+  LongRunningFunctionTool
+};

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

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+class MCPSessionManager {
+  constructor(connectionParams) {
+    this.connectionParams = connectionParams;
+  }
+  async createSession() {
+    const client = new Client({ name: "MCPClient", version: "1.0.0" });
+    switch (this.connectionParams.type) {
+      case "StdioConnectionParams":
+        await client.connect(
+          new StdioClientTransport(this.connectionParams.serverParams)
+        );
+        break;
+      case "StreamableHTTPConnectionParams":
+        await client.connect(new StreamableHTTPClientTransport(
+          new URL(this.connectionParams.url)
+        ));
+        break;
+      default:
+        const _exhaustiveCheck = this.connectionParams;
+        break;
+    }
+    return client;
+  }
+}
+export {
+  MCPSessionManager
+};

package/dist/web/tools/mcp/mcp_tool.js

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { toGeminiSchema } from "../../utils/gemini_schema_util.js";
+import { BaseTool } from "../base_tool.js";
+class MCPTool extends BaseTool {
+  constructor(mcpTool, mcpSessionManager) {
+    super({ name: mcpTool.name, description: mcpTool.description || "" });
+    this.mcpTool = mcpTool;
+    this.mcpSessionManager = mcpSessionManager;
+  }
+  _getDeclaration() {
+    let declaration;
+    declaration = {
+      name: this.mcpTool.name,
+      description: this.mcpTool.description,
+      parameters: toGeminiSchema(this.mcpTool.inputSchema),
+      // TODO: need revisit, refer to this
+      // https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-result
+      response: toGeminiSchema(this.mcpTool.outputSchema)
+    };
+    return declaration;
+  }
+  async runAsync(request) {
+    const session = await this.mcpSessionManager.createSession();
+    const callRequest = {};
+    callRequest.params = { name: this.mcpTool.name, arguments: request.args };
+    return await session.callTool(callRequest.params);
+  }
+}
+export {
+  MCPTool
+};

package/dist/web/tools/mcp/mcp_toolset.js

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { logger } from "../../utils/logger.js";
+import { BaseToolset } from "../base_toolset.js";
+import { MCPSessionManager } from "./mcp_session_manager.js";
+import { MCPTool } from "./mcp_tool.js";
+class MCPToolset extends BaseToolset {
+  constructor(connectionParams, toolFilter = []) {
+    super(toolFilter);
+    this.mcpSessionManager = new MCPSessionManager(connectionParams);
+  }
+  async getTools(context) {
+    const session = await this.mcpSessionManager.createSession();
+    const listResult = await session.listTools();
+    logger.debug("number of tools: ".concat(listResult.tools.length));
+    for (const tool of listResult.tools) {
+      logger.debug("tool: ".concat(tool.name));
+    }
+    return listResult.tools.map(
+      (tool) => new MCPTool(tool, this.mcpSessionManager)
+    );
+  }
+  async close() {
+  }
+}
+export {
+  MCPToolset
+};

package/dist/web/tools/tool_confirmation.js

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+class ToolConfirmation {
+  constructor({
+    hint,
+    confirmed,
+    payload
+  }) {
+    this.hint = hint != null ? hint : "";
+    this.confirmed = confirmed;
+    this.payload = payload;
+  }
+}
+export {
+  ToolConfirmation
+};

package/dist/web/tools/tool_context.js

@@ -0,0 +1,99 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { CallbackContext } from "../agents/callback_context.js";
+import { AuthHandler } from "../auth/auth_handler.js";
+import { ToolConfirmation } from "../tools/tool_confirmation.js";
+class ToolContext extends CallbackContext {
+  /**
+   * @param params.invocationContext The invocation context of the tool.
+   * @param params.eventActions The event actions of the current tool call.
+   * @param params.functionCallId The function call id of the current tool call.
+   *     This id was returned in the function call event from LLM to identify a
+   *     function call. If LLM didn't return this id, ADK will assign one to it.
+   *     This id is used to map function call response to the original function
+   *     call.
+   * @param params.toolConfirmation The tool confirmation of the current tool
+   *     call.
+   */
+  constructor({
+    invocationContext,
+    eventActions,
+    functionCallId,
+    toolConfirmation
+  }) {
+    super({ invocationContext, eventActions });
+    this.functionCallId = functionCallId;
+    this.toolConfirmation = toolConfirmation;
+  }
+  get actions() {
+    return this.eventActions;
+  }
+  requestCredential(authConfig) {
+    if (!this.functionCallId) {
+      throw new Error("functionCallId is not set.");
+    }
+    const authHandler = new AuthHandler(authConfig);
+    this.eventActions.requestedAuthConfigs[this.functionCallId] = authHandler.generateAuthRequest();
+  }
+  /**
+   * Gets the auth credential for the given auth config.
+   *
+   * @param authConfig The auth config to get the auth credential for.
+   * @return The auth credential for the given auth config.
+   */
+  getAuthResponse(authConfig) {
+    const authHandler = new AuthHandler(authConfig);
+    return authHandler.getAuthResponse(this.state);
+  }
+  /**
+   * Lists the filenames of the artifacts attached to the current session.
+   *
+   * @return A promise that resolves to a list of artifact filenames.
+   */
+  listArtifacts() {
+    if (!this.invocationContext.artifactService) {
+      throw new Error("Artifact service is not initialized.");
+    }
+    return this.invocationContext.artifactService.listArtifactKeys({
+      appName: this.invocationContext.session.appName,
+      userId: this.invocationContext.session.userId,
+      sessionId: this.invocationContext.session.id
+    });
+  }
+  /**
+   * Searches the memory of the current user.
+   *
+   * @param query The query to search memory for.
+   * @return A promise that resolves to SearchMemoryResponse containing the
+   *     matching memories.
+   */
+  searchMemory(query) {
+    if (!this.invocationContext.memoryService) {
+      throw new Error("Memory service is not initialized.");
+    }
+    return this.invocationContext.memoryService.searchMemory({
+      appName: this.invocationContext.session.appName,
+      userId: this.invocationContext.session.userId,
+      query
+    });
+  }
+  /**
+   * Requests confirmation for the current tool call.
+   */
+  requestConfirmation({ hint, payload }) {
+    if (!this.functionCallId) {
+      throw new Error("functionCallId is not set.");
+    }
+    this.eventActions.requestedToolConfirmations[this.functionCallId] = new ToolConfirmation({
+      hint,
+      confirmed: false,
+      payload
+    });
+  }
+}
+export {
+  ToolContext
+};

package/dist/web/utils/client_labels.js

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { version } from "../version.js";
+import { isBrowser } from "./env_aware_utils.js";
+const ADK_LABEL = "google-adk";
+const LANGUAGE_LABEL = "gl-typescript";
+const AGENT_ENGINE_TELEMETRY_TAG = "remote_reasoning_engine";
+const AGENT_ENGINE_TELEMETRY_ENV_VARIABLE_NAME = "GOOGLE_CLOUD_AGENT_ENGINE_ID";
+function _getDefaultLabels() {
+  let frameworkLabel = "".concat(ADK_LABEL, "/").concat(version);
+  if (!isBrowser() && process.env[AGENT_ENGINE_TELEMETRY_ENV_VARIABLE_NAME]) {
+    frameworkLabel = "".concat(frameworkLabel, "+").concat(AGENT_ENGINE_TELEMETRY_TAG);
+  }
+  const languageLabel = "".concat(LANGUAGE_LABEL, "/").concat(isBrowser() ? window.navigator.userAgent : process.version);
+  return [frameworkLabel, languageLabel];
+}
+function getClientLabels() {
+  const labels = _getDefaultLabels();
+  return labels;
+}
+export {
+  getClientLabels
+};

package/dist/web/utils/deep_clone.js

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+function deepClone(obj) {
+  if (obj === void 0) {
+    return void 0;
+  }
+  return JSON.parse(JSON.stringify(obj));
+}
+export {
+  deepClone
+};

package/dist/web/utils/env_aware_utils.js

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+function isBrowser() {
+  return typeof window !== "undefined";
+}
+const UUID_MASK = "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx";
+function randomUUID() {
+  let uuid = "";
+  for (let i = 0; i < UUID_MASK.length; i++) {
+    const randomValue = Math.random() * 16 | 0;
+    if (UUID_MASK[i] === "x") {
+      uuid += randomValue.toString(16);
+    } else if (UUID_MASK[i] === "y") {
+      uuid += (randomValue & 3 | 8).toString(16);
+    } else {
+      uuid += UUID_MASK[i];
+    }
+  }
+  return uuid;
+}
+function base64Encode(data) {
+  if (isBrowser()) {
+    return window.btoa(data);
+  }
+  return Buffer.from(data).toString("base64");
+}
+function base64Decode(data) {
+  if (isBrowser()) {
+    return window.atob(data);
+  }
+  return Buffer.from(data, "base64").toString();
+}
+function isBase64Encoded(data) {
+  try {
+    return base64Encode(base64Decode(data)) === data;
+  } catch (e) {
+    return false;
+  }
+}
+export {
+  base64Decode,
+  base64Encode,
+  isBase64Encoded,
+  isBrowser,
+  randomUUID
+};

package/dist/web/utils/gemini_schema_util.js

@@ -0,0 +1,58 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Type } from "@google/genai";
+import { z } from "zod";
+const MCPToolSchema = z.object({
+  type: z.literal("object"),
+  properties: z.record(z.unknown()).optional(),
+  required: z.string().array().optional()
+});
+function toGeminiType(mcpType) {
+  switch (mcpType.toLowerCase()) {
+    case "text":
+    case "string":
+      return Type.STRING;
+    case "number":
+      return Type.NUMBER;
+    case "boolean":
+      return Type.BOOLEAN;
+    case "integer":
+      return Type.INTEGER;
+    case "array":
+      return Type.ARRAY;
+    case "object":
+      return Type.OBJECT;
+    default:
+      return Type.TYPE_UNSPECIFIED;
+  }
+}
+function toGeminiSchema(mcpSchema) {
+  if (!mcpSchema) {
+    return void 0;
+  }
+  function recursiveConvert(mcp) {
+    const geminiType = toGeminiType(mcp.type);
+    const geminiSchema = { type: geminiType, description: mcp.description };
+    if (geminiType === Type.OBJECT) {
+      geminiSchema.properties = {};
+      if (mcp.properties) {
+        for (const name in mcp.properties) {
+          geminiSchema.properties[name] = recursiveConvert(mcp.properties[name]);
+        }
+      }
+      geminiSchema.required = mcp.required;
+    } else if (geminiType === Type.ARRAY) {
+      if (mcp.items) {
+        geminiSchema.items = recursiveConvert(mcp.items);
+      }
+    }
+    return geminiSchema;
+  }
+  return recursiveConvert(mcpSchema);
+}
+export {
+  toGeminiSchema
+};

package/dist/web/utils/logger.js

@@ -0,0 +1,89 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+var LogLevel = /* @__PURE__ */ ((LogLevel2) => {
+  LogLevel2[LogLevel2["DEBUG"] = 0] = "DEBUG";
+  LogLevel2[LogLevel2["INFO"] = 1] = "INFO";
+  LogLevel2[LogLevel2["WARN"] = 2] = "WARN";
+  LogLevel2[LogLevel2["ERROR"] = 3] = "ERROR";
+  return LogLevel2;
+})(LogLevel || {});
+let logLevel = 1 /* INFO */;
+function setLogLevel(level) {
+  logLevel = level;
+}
+class SimpleLogger {
+  log(level, ...args) {
+    if (level < logLevel) {
+      return;
+    }
+    switch (level) {
+      case 0 /* DEBUG */:
+        this.debug(...args);
+        break;
+      case 1 /* INFO */:
+        this.info(...args);
+        break;
+      case 2 /* WARN */:
+        this.warn(...args);
+        break;
+      case 3 /* ERROR */:
+        this.error(...args);
+        break;
+      default:
+        throw new Error("Unsupported log level: ".concat(level));
+    }
+  }
+  debug(...args) {
+    if (logLevel > 0 /* DEBUG */) {
+      return;
+    }
+    console.debug(getColoredPrefix(0 /* DEBUG */), ...args);
+  }
+  info(...args) {
+    if (logLevel > 1 /* INFO */) {
+      return;
+    }
+    console.info(getColoredPrefix(1 /* INFO */), ...args);
+  }
+  warn(...args) {
+    if (logLevel > 2 /* WARN */) {
+      return;
+    }
+    console.warn(getColoredPrefix(2 /* WARN */), ...args);
+  }
+  error(...args) {
+    if (logLevel > 3 /* ERROR */) {
+      return;
+    }
+    console.error(getColoredPrefix(3 /* ERROR */), ...args);
+  }
+}
+const LOG_LEVEL_STR = {
+  [0 /* DEBUG */]: "DEBUG",
+  [1 /* INFO */]: "INFO",
+  [2 /* WARN */]: "WARN",
+  [3 /* ERROR */]: "ERROR"
+};
+const CONSOLE_COLOR_MAP = {
+  [0 /* DEBUG */]: "\x1B[34m",
+  // Blue
+  [1 /* INFO */]: "\x1B[32m",
+  // Green
+  [2 /* WARN */]: "\x1B[33m",
+  // Yellow
+  [3 /* ERROR */]: "\x1B[31m"
+  // Red
+};
+const RESET_COLOR = "\x1B[0m";
+function getColoredPrefix(level) {
+  return "".concat(CONSOLE_COLOR_MAP[level], "[ADK ").concat(LOG_LEVEL_STR[level], "]:").concat(RESET_COLOR);
+}
+const logger = new SimpleLogger();
+export {
+  LogLevel,
+  logger,
+  setLogLevel
+};