@paean-ai/adk 0.2.18 → 0.2.20

package/dist/esm/plugins/plugin_manager.js

@@ -0,0 +1,209 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { logger } from "../utils/logger.js";
+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);
+    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) {
+          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}`;
+        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"
+    );
+  }
+}
+export {
+  PluginManager
+};

package/dist/esm/plugins/security_plugin.js

@@ -0,0 +1,119 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BasePlugin } from "../plugins/base_plugin.js";
+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 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;
+}
+export {
+  InMemoryPolicyEngine,
+  PolicyOutcome,
+  REQUEST_CONFIRMATION_FUNCTION_CALL_NAME,
+  SecurityPlugin,
+  getAskUserConfirmationFunctionCalls
+};

package/dist/esm/runner/in_memory_runner.js

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { InMemoryArtifactService } from "../artifacts/in_memory_artifact_service.js";
+import { InMemoryMemoryService } from "../memory/in_memory_memory_service.js";
+import { InMemorySessionService } from "../sessions/in_memory_session_service.js";
+import { Runner } from "./runner.js";
+class InMemoryRunner extends Runner {
+  constructor({
+    agent,
+    appName = "InMemoryRunner",
+    plugins = []
+  }) {
+    super({
+      appName,
+      agent,
+      plugins,
+      artifactService: new InMemoryArtifactService(),
+      sessionService: new InMemorySessionService(),
+      memoryService: new InMemoryMemoryService()
+    });
+  }
+}
+export {
+  InMemoryRunner
+};

package/dist/esm/runner/runner.js

@@ -0,0 +1,247 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { createPartFromText } from "@google/genai";
+import { trace } from "@opentelemetry/api";
+import { InvocationContext, newInvocationContextId } from "../agents/invocation_context.js";
+import { LlmAgent } from "../agents/llm_agent.js";
+import { createRunConfig } from "../agents/run_config.js";
+import { createEvent, getFunctionCalls } from "../events/event.js";
+import { createEventActions } from "../events/event_actions.js";
+import { PluginManager } from "../plugins/plugin_manager.js";
+import { logger } from "../utils/logger.js";
+class Runner {
+  constructor(input) {
+    var _a;
+    this.appName = input.appName;
+    this.agent = input.agent;
+    this.pluginManager = new PluginManager((_a = input.plugins) != null ? _a : []);
+    this.artifactService = input.artifactService;
+    this.sessionService = input.sessionService;
+    this.memoryService = input.memoryService;
+    this.credentialService = input.credentialService;
+  }
+  /**
+   * Runs the agent with the given message, and returns an async generator of
+   * events.
+   *
+   * @param userId The user ID of the session.
+   * @param sessionId The session ID of the session.
+   * @param newMessage A new message to append to the session.
+   * @param stateDelta An optional state delta to apply to the session.
+   * @param runConfig The run config for the agent.
+   * @yields The events generated by the agent.
+   */
+  // TODO - b/425992518: user, sessionId, and runConfig can be internalized.
+  async *runAsync({
+    userId,
+    sessionId,
+    newMessage,
+    stateDelta,
+    runConfig
+  }) {
+    var _a;
+    runConfig = createRunConfig(runConfig);
+    const span = trace.getTracer("gcp.vertex.agent").startSpan("invocation");
+    try {
+      const session = await this.sessionService.getSession({ appName: this.appName, userId, sessionId });
+      if (!session) {
+        throw new Error(`Session not found: ${sessionId}`);
+      }
+      if (runConfig.supportCfc && this.agent instanceof LlmAgent) {
+        const modelName = this.agent.canonicalModel.model;
+        if (!modelName.startsWith("gemini-2")) {
+          throw new Error(`CFC is not supported for model: ${modelName} in agent: ${this.agent.name}`);
+        }
+      }
+      const invocationContext = new InvocationContext({
+        artifactService: this.artifactService,
+        sessionService: this.sessionService,
+        memoryService: this.memoryService,
+        credentialService: this.credentialService,
+        invocationId: newInvocationContextId(),
+        agent: this.agent,
+        session,
+        userContent: newMessage,
+        runConfig,
+        pluginManager: this.pluginManager
+      });
+      const pluginUserMessage = await this.pluginManager.runOnUserMessageCallback({
+        userMessage: newMessage,
+        invocationContext
+      });
+      if (pluginUserMessage) {
+        newMessage = pluginUserMessage;
+      }
+      if (newMessage) {
+        if (!((_a = newMessage.parts) == null ? void 0 : _a.length)) {
+          throw new Error("No parts in the newMessage.");
+        }
+        if (runConfig.saveInputBlobsAsArtifacts) {
+          await this.saveArtifacts(
+            invocationContext.invocationId,
+            session.userId,
+            session.id,
+            newMessage
+          );
+        }
+        await this.sessionService.appendEvent({
+          session,
+          event: createEvent({
+            invocationId: invocationContext.invocationId,
+            author: "user",
+            actions: stateDelta ? createEventActions({ stateDelta }) : void 0,
+            content: newMessage
+          })
+        });
+      }
+      invocationContext.agent = this.determineAgentForResumption(session, this.agent);
+      const beforeRunCallbackResponse = await this.pluginManager.runBeforeRunCallback({ invocationContext });
+      if (beforeRunCallbackResponse) {
+        const earlyExitEvent = createEvent({
+          invocationId: invocationContext.invocationId,
+          author: "model",
+          content: beforeRunCallbackResponse
+        });
+        await this.sessionService.appendEvent({ session, event: earlyExitEvent });
+        yield earlyExitEvent;
+      } else {
+        for await (const event of invocationContext.agent.runAsync(
+          invocationContext
+        )) {
+          if (!event.partial) {
+            await this.sessionService.appendEvent({ session, event });
+          }
+          const modifiedEvent = await this.pluginManager.runOnEventCallback(
+            { invocationContext, event }
+          );
+          if (modifiedEvent) {
+            yield modifiedEvent;
+          } else {
+            yield event;
+          }
+        }
+      }
+      await this.pluginManager.runAfterRunCallback({ invocationContext });
+    } finally {
+      span.end();
+    }
+  }
+  /**
+   * Saves artifacts from the message parts and replaces the inline data with
+   * a file name placeholder.
+   *
+   * @param invocationId The current invocation ID.
+   * @param userId The user ID of the session.
+   * @param sessionId The session ID of the session.
+   * @param message The message containing parts to process.
+   */
+  async saveArtifacts(invocationId, userId, sessionId, message) {
+    var _a;
+    if (!this.artifactService || !((_a = message.parts) == null ? void 0 : _a.length)) {
+      return;
+    }
+    for (let i = 0; i < message.parts.length; i++) {
+      const part = message.parts[i];
+      if (!part.inlineData) {
+        continue;
+      }
+      const fileName = `artifact_${invocationId}_${i}`;
+      await this.artifactService.saveArtifact({
+        appName: this.appName,
+        userId,
+        sessionId,
+        filename: fileName,
+        artifact: part
+      });
+      message.parts[i] = createPartFromText(
+        `Uploaded file: ${fileName}. It is saved into artifacts`
+      );
+    }
+  }
+  /**
+   * Determines the next agent to run to continue the session. This is primarily
+   * used for session resumption.
+   */
+  // TODO - b/425992518: This is where LRO integration should happen.
+  // Needs clean up before we can generalize it.
+  determineAgentForResumption(session, rootAgent) {
+    const event = findEventByLastFunctionResponseId(session.events);
+    if (event && event.author) {
+      return rootAgent.findAgent(event.author) || rootAgent;
+    }
+    for (let i = session.events.length - 1; i >= 0; i--) {
+      logger.debug(`event[${i}]: author=${session.events[i].author}, id=${session.events[i].id}`);
+      const event2 = session.events[i];
+      if (event2.author === "user" || !event2.author) {
+        continue;
+      }
+      if (event2.author === rootAgent.name) {
+        return rootAgent;
+      }
+      const agent = rootAgent.findSubAgent(event2.author);
+      if (!agent) {
+        logger.warn(`Event from an unknown agent: ${event2.author}, event id: ${event2.id}`);
+        continue;
+      }
+      if (this.isRoutableLlmAgent(agent)) {
+        return agent;
+      }
+    }
+    return rootAgent;
+  }
+  /**
+   * Whether the agent to run can transfer to any other agent in the agent tree.
+   *
+   * An agent is transferable if:
+   *  - It is an instance of `LlmAgent`.
+   *  - All its ancestors are also transferable (i.e., they have
+   *    `disallowTransferToParent` set to false).
+   *
+   * @param agentToRun The agent to check for transferability.
+   * @returns True if the agent can transfer, False otherwise.
+   */
+  isRoutableLlmAgent(agentToRun) {
+    let agent = agentToRun;
+    while (agent) {
+      if (!(agent instanceof LlmAgent)) {
+        return false;
+      }
+      if (agent.disallowTransferToParent) {
+        return false;
+      }
+      agent = agent.parentAgent;
+    }
+    return true;
+  }
+  // TODO - b/425992518: Implement runLive and related methods.
+}
+function findEventByLastFunctionResponseId(events) {
+  var _a, _b, _c, _d;
+  if (!events.length) {
+    return null;
+  }
+  const lastEvent = events[events.length - 1];
+  const functionCallId = (_d = (_c = (_b = (_a = lastEvent.content) == null ? void 0 : _a.parts) == null ? void 0 : _b.find((part) => part.functionResponse)) == null ? void 0 : _c.functionResponse) == null ? void 0 : _d.id;
+  if (!functionCallId) {
+    return null;
+  }
+  for (let i = events.length - 2; i >= 0; i--) {
+    const event = events[i];
+    const functionCalls = getFunctionCalls(event);
+    if (!functionCalls) {
+      continue;
+    }
+    for (const functionCall of functionCalls) {
+      if (functionCall.id === functionCallId) {
+        return event;
+      }
+    }
+  }
+  return null;
+}
+export {
+  Runner
+};

package/dist/esm/sessions/base_session_service.js

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { State } from "./state.js";
+class BaseSessionService {
+  /**
+   * Appends an event to a session.
+   *
+   * @param request The request to append an event.
+   * @return A promise that resolves to the event that was appended.
+   */
+  async appendEvent({ session, event }) {
+    if (event.partial) {
+      return event;
+    }
+    this.updateSessionState({ session, event });
+    session.events.push(event);
+    return event;
+  }
+  /**
+   * Updates the session state based on the event.
+   *
+   * @param request The request to update the session state.
+   */
+  updateSessionState({ session, event }) {
+    if (!event.actions || !event.actions.stateDelta) {
+      return;
+    }
+    for (const [key, value] of Object.entries(event.actions.stateDelta)) {
+      if (key.startsWith(State.TEMP_PREFIX)) {
+        continue;
+      }
+      session.state[key] = value;
+    }
+  }
+}
+export {
+  BaseSessionService
+};