@paean-ai/adk 0.2.19 → 0.2.20

package/dist/cjs/plugins/plugin_manager.js

@@ -0,0 +1,239 @@
+/**
+  * @license
+  * Copyright 2025 Google LLC
+  * SPDX-License-Identifier: Apache-2.0
+  */
+
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var plugin_manager_exports = {};
+__export(plugin_manager_exports, {
+  PluginManager: () => PluginManager
+});
+module.exports = __toCommonJS(plugin_manager_exports);
+var import_logger = require("../utils/logger.js");
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+class PluginManager {
+  /**
+   * Initializes the plugin service.
+   *
+   * @param plugins An optional list of plugins to register upon
+   *     initialization.
+   */
+  constructor(plugins) {
+    this.plugins = /* @__PURE__ */ new Set();
+    if (plugins) {
+      for (const plugin of plugins) {
+        this.registerPlugin(plugin);
+      }
+    }
+  }
+  /**
+   * Registers a new plugin.
+   *
+   * @param plugin The plugin instance to register.
+   * @throws If the same exact plugin or a plugin with the same name is already
+   *     registered.
+   */
+  registerPlugin(plugin) {
+    if (this.plugins.has(plugin)) {
+      throw new Error(`Plugin '${plugin.name}' already registered.`);
+    }
+    if (Array.from(this.plugins).some((p) => p.name === plugin.name)) {
+      throw new Error(`Plugin with name '${plugin.name}' already registered.`);
+    }
+    this.plugins.add(plugin);
+    import_logger.logger.info(`Plugin '${plugin.name}' registered.`);
+  }
+  /**
+   * Retrieves a registered plugin by its name.
+   *
+   * @param pluginName The name of the plugin to retrieve.
+   * @returns The plugin instance if found, otherwise `undefined`.
+   */
+  getPlugin(pluginName) {
+    return Array.from(this.plugins).find((p) => p.name === pluginName);
+  }
+  /**
+   * Runs the same callback for all plugins. This is a utility method to reduce
+   * duplication below.
+   *
+   * @param plugins The set of plugins to run
+   * @param callback A closure containing the callback method to run on each
+   *     plugin
+   * @param callbackName The name of the function being called in the closure
+   *     above. Used for logging purposes.
+   * @returns A promise containing the plugin method result. Must be casted to
+   *     the proper type for the plugin method.
+   */
+  async runCallbacks(plugins, callback, callbackName) {
+    for (const plugin of plugins) {
+      try {
+        const result = await callback(plugin);
+        if (result !== void 0) {
+          import_logger.logger.debug(
+            `Plugin '${plugin.name}' returned a value for callback '${callbackName}', exiting early.`
+          );
+          return result;
+        }
+      } catch (e) {
+        const errorMessage = `Error in plugin '${plugin.name}' during '${callbackName}' callback: ${e}`;
+        import_logger.logger.error(errorMessage);
+        throw new Error(errorMessage);
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Runs the `onUserMessageCallback` for all plugins.
+   */
+  async runOnUserMessageCallback({ userMessage, invocationContext }) {
+    return await this.runCallbacks(
+      this.plugins,
+      (plugin) => plugin.onUserMessageCallback(
+        { userMessage, invocationContext }
+      ),
+      "onUserMessageCallback"
+    );
+  }
+  /**
+   * Runs the `beforeRunCallback` for all plugins.
+   */
+  async runBeforeRunCallback({ invocationContext }) {
+    return await this.runCallbacks(
+      this.plugins,
+      (plugin) => plugin.beforeRunCallback({ invocationContext }),
+      "beforeRunCallback"
+    );
+  }
+  /**
+   * Runs the `afterRunCallback` for all plugins.
+   */
+  async runAfterRunCallback({ invocationContext }) {
+    await this.runCallbacks(
+      this.plugins,
+      (plugin) => plugin.afterRunCallback({ invocationContext }),
+      "afterRunCallback"
+    );
+  }
+  /**
+   * Runs the `onEventCallback` for all plugins.
+   */
+  async runOnEventCallback({ invocationContext, event }) {
+    return await this.runCallbacks(
+      this.plugins,
+      (plugin) => plugin.onEventCallback({ invocationContext, event }),
+      "onEventCallback"
+    );
+  }
+  /**
+   * Runs the `beforeAgentCallback` for all plugins.
+   */
+  async runBeforeAgentCallback({ agent, callbackContext }) {
+    return await this.runCallbacks(
+      this.plugins,
+      (plugin) => plugin.beforeAgentCallback({ agent, callbackContext }),
+      "beforeAgentCallback"
+    );
+  }
+  /**
+   * Runs the `afterAgentCallback` for all plugins.
+   */
+  async runAfterAgentCallback({ agent, callbackContext }) {
+    return await this.runCallbacks(
+      this.plugins,
+      (plugin) => plugin.afterAgentCallback({ agent, callbackContext }),
+      "afterAgentCallback"
+    );
+  }
+  /**
+   * Runs the `beforeToolCallback` for all plugins.
+   */
+  async runBeforeToolCallback({ tool, toolArgs, toolContext }) {
+    return await this.runCallbacks(
+      this.plugins,
+      (plugin) => plugin.beforeToolCallback({ tool, toolArgs, toolContext }),
+      "beforeToolCallback"
+    );
+  }
+  /**
+   * Runs the `afterToolCallback` for all plugins.
+   */
+  async runAfterToolCallback({ tool, toolArgs, toolContext, result }) {
+    return await this.runCallbacks(
+      this.plugins,
+      (plugin) => plugin.afterToolCallback(
+        { tool, toolArgs, toolContext, result }
+      ),
+      "afterToolCallback"
+    );
+  }
+  /**
+   * Runs the `onModelErrorCallback` for all plugins.
+   */
+  async runOnModelErrorCallback({ callbackContext, llmRequest, error }) {
+    return await this.runCallbacks(
+      this.plugins,
+      (plugin) => plugin.onModelErrorCallback(
+        { callbackContext, llmRequest, error }
+      ),
+      "onModelErrorCallback"
+    );
+  }
+  /**
+   * Runs the `beforeModelCallback` for all plugins.
+   */
+  async runBeforeModelCallback({ callbackContext, llmRequest }) {
+    return await this.runCallbacks(
+      this.plugins,
+      (plugin) => plugin.beforeModelCallback({ callbackContext, llmRequest }),
+      "beforeModelCallback"
+    );
+  }
+  /**
+   * Runs the `afterModelCallback` for all plugins.
+   */
+  async runAfterModelCallback({ callbackContext, llmResponse }) {
+    return await this.runCallbacks(
+      this.plugins,
+      (plugin) => plugin.afterModelCallback({ callbackContext, llmResponse }),
+      "afterModelCallback"
+    );
+  }
+  /**
+   * Runs the `onToolErrorCallback` for all plugins.
+   */
+  async runOnToolErrorCallback({ tool, toolArgs, toolContext, error }) {
+    return await this.runCallbacks(
+      this.plugins,
+      (plugin) => plugin.onToolErrorCallback(
+        { tool, toolArgs, toolContext, error }
+      ),
+      "onToolErrorCallback"
+    );
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PluginManager
+});

package/dist/cjs/plugins/security_plugin.js

@@ -0,0 +1,153 @@
+/**
+  * @license
+  * Copyright 2025 Google LLC
+  * SPDX-License-Identifier: Apache-2.0
+  */
+
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var security_plugin_exports = {};
+__export(security_plugin_exports, {
+  InMemoryPolicyEngine: () => InMemoryPolicyEngine,
+  PolicyOutcome: () => PolicyOutcome,
+  REQUEST_CONFIRMATION_FUNCTION_CALL_NAME: () => REQUEST_CONFIRMATION_FUNCTION_CALL_NAME,
+  SecurityPlugin: () => SecurityPlugin,
+  getAskUserConfirmationFunctionCalls: () => getAskUserConfirmationFunctionCalls
+});
+module.exports = __toCommonJS(security_plugin_exports);
+var import_base_plugin = require("../plugins/base_plugin.js");
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const REQUEST_CONFIRMATION_FUNCTION_CALL_NAME = "adk_request_confirmation";
+const TOOL_CALL_SECURITY_CHECK_STATES = "orcas_tool_call_security_check_states";
+const INTERMEDIATE_REQUIRE_TOOL_CALL_CONFIRMATION_ERROR = "This tool call needs external confirmation before completion.";
+var PolicyOutcome = /* @__PURE__ */ ((PolicyOutcome2) => {
+  PolicyOutcome2["DENY"] = "DENY";
+  PolicyOutcome2["CONFIRM"] = "CONFIRM";
+  PolicyOutcome2["ALLOW"] = "ALLOW";
+  return PolicyOutcome2;
+})(PolicyOutcome || {});
+class InMemoryPolicyEngine {
+  async evaluate(context) {
+    return Promise.resolve({
+      outcome: "ALLOW" /* ALLOW */,
+      reason: "For prototyping purpose, all tool calls are allowed."
+    });
+  }
+}
+class SecurityPlugin extends import_base_plugin.BasePlugin {
+  constructor(params) {
+    var _a;
+    super("security_plugin");
+    this.policyEngine = (_a = params == null ? void 0 : params.policyEngine) != null ? _a : new InMemoryPolicyEngine();
+  }
+  async beforeToolCallback({
+    tool,
+    toolArgs,
+    toolContext
+  }) {
+    const toolCallCheckState = this.getToolCallCheckState(toolContext);
+    if (!toolCallCheckState) {
+      return this.checkToolCallPolicy({
+        tool,
+        toolArgs,
+        toolContext
+      });
+    }
+    if (toolCallCheckState !== "CONFIRM" /* CONFIRM */) {
+      return;
+    }
+    if (!toolContext.toolConfirmation) {
+      return { partial: INTERMEDIATE_REQUIRE_TOOL_CALL_CONFIRMATION_ERROR };
+    }
+    this.setToolCallCheckState(toolContext, toolContext.toolConfirmation);
+    if (!toolContext.toolConfirmation.confirmed) {
+      return {
+        error: "Tool call rejected from confirmation flow."
+      };
+    }
+    toolContext.toolConfirmation = void 0;
+    return;
+  }
+  getToolCallCheckState(toolContext) {
+    var _a;
+    const { functionCallId } = toolContext;
+    if (!functionCallId) {
+      return;
+    }
+    const toolCallStates = (_a = toolContext.state.get(TOOL_CALL_SECURITY_CHECK_STATES)) != null ? _a : {};
+    return toolCallStates[functionCallId];
+  }
+  setToolCallCheckState(toolContext, state) {
+    var _a;
+    const { functionCallId } = toolContext;
+    if (!functionCallId) {
+      return;
+    }
+    const toolCallStates = (_a = toolContext.state.get(TOOL_CALL_SECURITY_CHECK_STATES)) != null ? _a : {};
+    toolCallStates[functionCallId] = state;
+    toolContext.state.set(TOOL_CALL_SECURITY_CHECK_STATES, toolCallStates);
+  }
+  async checkToolCallPolicy({
+    tool,
+    toolArgs,
+    toolContext
+  }) {
+    const policyCheckResult = await this.policyEngine.evaluate({ tool, toolArgs });
+    this.setToolCallCheckState(toolContext, policyCheckResult.outcome);
+    switch (policyCheckResult.outcome) {
+      case "DENY" /* DENY */:
+        return {
+          error: `This tool call is rejected by policy engine. Reason: ${policyCheckResult.reason}`
+        };
+      case "CONFIRM" /* CONFIRM */:
+        toolContext.requestConfirmation({
+          hint: `Policy engine requires confirmation calling tool: ${tool.name}. Reason: ${policyCheckResult.reason}`
+        });
+        return { partial: INTERMEDIATE_REQUIRE_TOOL_CALL_CONFIRMATION_ERROR };
+      case "ALLOW" /* ALLOW */:
+        return;
+      default:
+        return;
+    }
+  }
+}
+function getAskUserConfirmationFunctionCalls(event) {
+  if (!event.content || !event.content.parts) {
+    return [];
+  }
+  const results = [];
+  for (const part of event.content.parts) {
+    if (part && part.functionCall && part.functionCall.name === REQUEST_CONFIRMATION_FUNCTION_CALL_NAME) {
+      results.push(part.functionCall);
+    }
+  }
+  return results;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  InMemoryPolicyEngine,
+  PolicyOutcome,
+  REQUEST_CONFIRMATION_FUNCTION_CALL_NAME,
+  SecurityPlugin,
+  getAskUserConfirmationFunctionCalls
+});

package/dist/cjs/runner/in_memory_runner.js

@@ -0,0 +1,58 @@
+/**
+  * @license
+  * Copyright 2025 Google LLC
+  * SPDX-License-Identifier: Apache-2.0
+  */
+
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var in_memory_runner_exports = {};
+__export(in_memory_runner_exports, {
+  InMemoryRunner: () => InMemoryRunner
+});
+module.exports = __toCommonJS(in_memory_runner_exports);
+var import_in_memory_artifact_service = require("../artifacts/in_memory_artifact_service.js");
+var import_in_memory_memory_service = require("../memory/in_memory_memory_service.js");
+var import_in_memory_session_service = require("../sessions/in_memory_session_service.js");
+var import_runner = require("./runner.js");
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+class InMemoryRunner extends import_runner.Runner {
+  constructor({
+    agent,
+    appName = "InMemoryRunner",
+    plugins = []
+  }) {
+    super({
+      appName,
+      agent,
+      plugins,
+      artifactService: new import_in_memory_artifact_service.InMemoryArtifactService(),
+      sessionService: new import_in_memory_session_service.InMemorySessionService(),
+      memoryService: new import_in_memory_memory_service.InMemoryMemoryService()
+    });
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  InMemoryRunner
+});