@softactivate/adk 1.1.0

package/dist/esm/plugins/base_plugin.js

@@ -0,0 +1,268 @@
+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 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { experimental } from "../utils/experimental.js";
+var ContextCompactionTrigger = /* @__PURE__ */ ((ContextCompactionTrigger2) => {
+  ContextCompactionTrigger2["Manual"] = "Manual";
+  ContextCompactionTrigger2["Auto"] = "Auto";
+  return ContextCompactionTrigger2;
+})(ContextCompactionTrigger || {});
+class BasePlugin {
+  /**
+   * Initializes the plugin.
+   *
+   * @param name A unique identifier for this plugin instance.
+   */
+  constructor(name) {
+    this.name = name;
+  }
+  /**
+   * Callback executed when a user message is received before an invocation
+   * starts.
+   *
+   * This callback helps logging and modifying the user message before the
+   * runner starts the invocation.
+   *
+   * @param params.invocationContext The context for the entire invocation.
+   * @param params.userMessage The message content input by user.
+   * @returns An optional `Content` to be returned to the ADK. Returning a
+   *     value to replace the user message. Returning `undefined` to proceed
+   *     normally.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async onUserMessageCallback(params) {
+    return;
+  }
+  /**
+   * Callback executed before the ADK runner runs.
+   *
+   * This is the first callback to be called in the lifecycle, ideal for global
+   * setup or initialization tasks.
+   *
+   * @param params.invocationContext The context for the entire invocation, containing
+   *     session information, the root agent, etc.
+   * @returns An optional `Event` to be returned to the ADK. Returning a value
+   *     to halt execution of the runner and ends the runner with that event.
+   *     Return `undefined` to proceed normally.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async beforeRunCallback(params) {
+    return;
+  }
+  /**
+   * Callback executed after an event is yielded from runner.
+   *
+   * This is the ideal place to make modification to the event before the event
+   * is handled by the underlying agent app.
+   *
+   * @param params.invocationContext The context for the entire invocation.
+   * @param params.event The event raised by the runner.
+   * @returns An optional value. A non-`undefined` return may be used by the
+   *     framework to modify or replace the response. Returning `undefined`
+   *     allows the original response to be used.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async onEventCallback(params) {
+    return;
+  }
+  /**
+   * Callback executed after an ADK runner run has completed.
+   *
+   * This is the final callback in the ADK lifecycle, suitable for cleanup,
+   * final logging, or reporting tasks.
+   *
+   * @param params.invocationContext The context for the entire invocation.
+   * @returns undefined
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async afterRunCallback(params) {
+    return;
+  }
+  /**
+   * Callback executed before an agent's primary logic is invoked.
+   *
+   * This callback can be used for logging, setup, or to short-circuit the
+   * agent's execution by returning a value.
+   *
+   * @param params.agent The agent that is about to run.
+   * @param params.callbackContext The context for the agent invocation.
+   * @returns An optional `Content` object. If a value is returned, it will
+   *     bypass the agent's callbacks and its execution, and return this value
+   *     directly. Returning `undefined` allows the agent to proceed normally.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async beforeAgentCallback(params) {
+    return;
+  }
+  /**
+   * Callback executed after an agent's primary logic has completed.
+   *
+   * This callback can be used to inspect, log, or modify the agent's final
+   * result before it is returned.
+   *
+   * @param params.agent The agent that has just run.
+   * @param params.callbackContext The context for the agent invocation.
+   * @returns An optional `Content` object. If a value is returned, it will
+   *     replace the agent's original result. Returning `undefined` uses the
+   *     original, unmodified result.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async afterAgentCallback(params) {
+    return;
+  }
+  /**
+   * Callback executed before a request is sent to the model.
+   *
+   * This provides an opportunity to inspect, log, or modify the `LlmRequest`
+   * object. It can also be used to implement caching by returning a cached
+   * `LlmResponse`, which would skip the actual model call.
+   *
+   * @param params.callbackContext The context for the current agent call.
+   * @param params.llmRequest The prepared request object to be sent to the model.
+   * @returns An optional value. The interpretation of a non-`undefined`
+   *     trigger an early exit and returns the response immediately. Returning
+   *     `undefined` allows the LLM request to proceed normally.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async beforeModelCallback(params) {
+    return;
+  }
+  /**
+   * Callback executed after a response is received from the model.
+   *
+   * This is the ideal place to log model responses, collect metrics on token
+   * usage, or perform post-processing on the raw `LlmResponse`.
+   *
+   * @param params.callbackContext The context for the current agent call.
+   * @param params.llmResponse The response object received from the model.
+   * @returns An optional value. A non-`undefined` return may be used by the
+   *     framework to modify or replace the response. Returning `undefined`
+   *     allows the original response to be used.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async afterModelCallback(params) {
+    return;
+  }
+  /**
+   * Callback executed when a model call encounters an error.
+   *
+   * This callback provides an opportunity to handle model errors gracefully,
+   * potentially providing alternative responses or recovery mechanisms.
+   *
+   * @param params.callbackContext The context for the current agent call.
+   * @param params.llmRequest The request that was sent to the model when the error
+   *     occurred.
+   * @param params.error The exception that was raised during model execution.
+   * @returns An optional LlmResponse. If an LlmResponse is returned, it will be
+   *     used instead of propagating the error. Returning `undefined` allows
+   *     the original error to be raised.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async onModelErrorCallback(params) {
+    return;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async beforeToolSelection(params) {
+    return;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async beforeContextCompaction(params) {
+    return;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async afterContextCompaction(params) {
+    return;
+  }
+  /**
+   * Callback executed before a tool is called.
+   *
+   * This callback is useful for logging tool usage, input validation, or
+   * modifying the arguments before they are passed to the tool.
+   *
+   * @param params.tool The tool instance that is about to be executed.
+   * @param params.toolArgs The dictionary of arguments to be used for invoking the
+   *     tool.
+   * @param params.toolContext The context specific to the tool execution.
+   * @returns An optional dictionary. If a dictionary is returned, it will stop
+   *     the tool execution and return this response immediately. Returning
+   *     `undefined` uses the original, unmodified arguments.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async beforeToolCallback(params) {
+    return;
+  }
+  /**
+   * Callback executed after a tool has been called.
+   *
+   * This callback allows for inspecting, logging, or modifying the result
+   * returned by a tool.
+   *
+   * @param params.tool The tool instance that has just been executed.
+   * @param params.toolArgs The original arguments that were passed to the tool.
+   * @param params.toolContext The context specific to the tool execution.
+   * @param params.result The dictionary returned by the tool invocation.
+   * @returns An optional dictionary. If a dictionary is returned, it will
+   *     **replace** the original result from the tool. This allows for
+   *     post-processing or altering tool outputs. Returning `undefined` uses
+   *     the original, unmodified result.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async afterToolCallback(params) {
+    return;
+  }
+  /**
+     * Callback executed when a tool call encounters an error.
+      tool: BaseTool;
+      toolArgs: Record<string, unknown>;
+      toolContext: Context;
+      result: Record<string, unknown>;
+    }): Promise<Record<string, unknown> | undefined> {
+      return;
+    }
+  
+    /**
+     * Callback executed when a tool call encounters an error.
+     *
+     * This callback provides an opportunity to handle tool errors gracefully,
+     * potentially providing alternative responses or recovery mechanisms.
+     *
+     * @param params.tool The tool instance that encountered an error.
+     * @param params.toolArgs The arguments that were passed to the tool.
+     * @param params.toolContext The context specific to the tool execution.
+     * @param params.error The exception that was raised during tool execution.
+     * @returns An optional dictionary. If a dictionary is returned, it will be
+     *     used as the tool response instead of propagating the error. Returning
+     *     `undefined` allows the original error to be raised.
+     */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async onToolErrorCallback(params) {
+    return;
+  }
+}
+__decorateClass([
+  experimental
+], BasePlugin.prototype, "beforeToolSelection", 1);
+__decorateClass([
+  experimental
+], BasePlugin.prototype, "beforeContextCompaction", 1);
+__decorateClass([
+  experimental
+], BasePlugin.prototype, "afterContextCompaction", 1);
+export {
+  BasePlugin,
+  ContextCompactionTrigger
+};

package/dist/esm/plugins/logging_plugin.js

@@ -0,0 +1,235 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import {
+  getFunctionCalls,
+  getFunctionResponses,
+  isFinalResponse
+} from "../events/event.js";
+import { logger } from "../utils/logger.js";
+import { BasePlugin } from "./base_plugin.js";
+class LoggingPlugin extends BasePlugin {
+  /**
+   * Initialize the logging plugin.
+   *
+   * @param name The name of the plugin instance.
+   */
+  constructor(name = "logging_plugin") {
+    super(name);
+  }
+  async onUserMessageCallback({
+    invocationContext,
+    userMessage
+  }) {
+    var _a;
+    this.log("\u{1F680} USER MESSAGE RECEIVED");
+    this.log(`   Invocation ID: ${invocationContext.invocationId}`);
+    this.log(`   Session ID: ${invocationContext.session.id}`);
+    this.log(`   User ID: ${invocationContext.userId}`);
+    this.log(`   App Name: ${invocationContext.appName}`);
+    this.log(`   Root Agent: ${(_a = invocationContext.agent.name) != null ? _a : "Unknown"}`);
+    this.log(`   User Content: ${this.formatContent(userMessage)}`);
+    if (invocationContext.branch) {
+      this.log(`   Branch: ${invocationContext.branch}`);
+    }
+    return void 0;
+  }
+  async beforeRunCallback({
+    invocationContext
+  }) {
+    var _a;
+    this.log("\u{1F3C3} INVOCATION STARTING");
+    this.log(`   Invocation ID: ${invocationContext.invocationId}`);
+    this.log(`   Starting Agent: ${(_a = invocationContext.agent.name) != null ? _a : "Unknown"}`);
+    return void 0;
+  }
+  async onEventCallback({
+    event
+  }) {
+    this.log("\u{1F4E2} EVENT YIELDED");
+    this.log(`   Event ID: ${event.id}`);
+    this.log(`   Author: ${event.author}`);
+    this.log(`   Content: ${this.formatContent(event.content)}`);
+    this.log(`   Final Response: ${isFinalResponse(event)}`);
+    const functionCalls = getFunctionCalls(event);
+    if (functionCalls.length > 0) {
+      const funcCalls = functionCalls.map((fc) => fc.name);
+      this.log(`   Function Calls: ${funcCalls}`);
+    }
+    const functionResponses = getFunctionResponses(event);
+    if (functionResponses.length > 0) {
+      const funcResponses = functionResponses.map((fr) => fr.name);
+      this.log(`   Function Responses: ${funcResponses}`);
+    }
+    if (event.longRunningToolIds && event.longRunningToolIds.length > 0) {
+      this.log(`   Long Running Tools: ${[...event.longRunningToolIds]}`);
+    }
+    return void 0;
+  }
+  async afterRunCallback({
+    invocationContext
+  }) {
+    var _a;
+    this.log("\u2705 INVOCATION COMPLETED");
+    this.log(`   Invocation ID: ${invocationContext.invocationId}`);
+    this.log(`   Final Agent: ${(_a = invocationContext.agent.name) != null ? _a : "Unknown"}`);
+    return void 0;
+  }
+  async beforeAgentCallback({
+    callbackContext
+  }) {
+    this.log("\u{1F916} AGENT STARTING");
+    this.log(`   Agent Name: ${callbackContext.agentName}`);
+    this.log(`   Invocation ID: ${callbackContext.invocationId}`);
+    if (callbackContext.invocationContext.branch) {
+      this.log(`   Branch: ${callbackContext.invocationContext.branch}`);
+    }
+    return void 0;
+  }
+  async afterAgentCallback({
+    callbackContext
+  }) {
+    this.log("\u{1F916} AGENT COMPLETED");
+    this.log(`   Agent Name: ${callbackContext.agentName}`);
+    this.log(`   Invocation ID: ${callbackContext.invocationId}`);
+    return void 0;
+  }
+  async beforeModelCallback({
+    callbackContext,
+    llmRequest
+  }) {
+    var _a;
+    this.log("\u{1F9E0} LLM REQUEST");
+    this.log(`   Model: ${(_a = llmRequest.model) != null ? _a : "default"}`);
+    this.log(`   Agent: ${callbackContext.agentName}`);
+    if (llmRequest.config && llmRequest.config.systemInstruction) {
+      let sysInstruction = llmRequest.config.systemInstruction;
+      if (sysInstruction.length > 200) {
+        sysInstruction = sysInstruction.substring(0, 200) + "...";
+      }
+      this.log(`   System Instruction: '${sysInstruction}'`);
+    }
+    if (llmRequest.toolsDict) {
+      const toolNames = Object.keys(llmRequest.toolsDict);
+      this.log(`   Available Tools: ${toolNames}`);
+    }
+    return void 0;
+  }
+  async afterModelCallback({
+    callbackContext,
+    llmResponse
+  }) {
+    this.log("\u{1F9E0} LLM RESPONSE");
+    this.log(`   Agent: ${callbackContext.agentName}`);
+    if (llmResponse.errorCode) {
+      this.log(`   \u274C ERROR - Code: ${llmResponse.errorCode}`);
+      this.log(`   Error Message: ${llmResponse.errorMessage}`);
+    } else {
+      this.log(`   Content: ${this.formatContent(llmResponse.content)}`);
+      if (llmResponse.partial) {
+        this.log(`   Partial: ${llmResponse.partial}`);
+      }
+      if (llmResponse.turnComplete !== void 0) {
+        this.log(`   Turn Complete: ${llmResponse.turnComplete}`);
+      }
+    }
+    if (llmResponse.usageMetadata) {
+      this.log(
+        `   Token Usage - Input: ${llmResponse.usageMetadata.promptTokenCount}, Output: ${llmResponse.usageMetadata.candidatesTokenCount}`
+      );
+    }
+    return void 0;
+  }
+  async beforeToolCallback({
+    tool,
+    toolArgs,
+    toolContext
+  }) {
+    this.log("\u{1F527} TOOL STARTING");
+    this.log(`   Tool Name: ${tool.name}`);
+    this.log(`   Agent: ${toolContext.agentName}`);
+    this.log(`   Function Call ID: ${toolContext.functionCallId}`);
+    this.log(`   Arguments: ${this.formatArgs(toolArgs)}`);
+    return void 0;
+  }
+  async afterToolCallback({
+    tool,
+    toolContext,
+    result
+  }) {
+    this.log("\u{1F527} TOOL COMPLETED");
+    this.log(`   Tool Name: ${tool.name}`);
+    this.log(`   Agent: ${toolContext.agentName}`);
+    this.log(`   Function Call ID: ${toolContext.functionCallId}`);
+    this.log(`   Result: ${this.formatArgs(result)}`);
+    return void 0;
+  }
+  async onModelErrorCallback({
+    callbackContext,
+    error
+  }) {
+    this.log("\u{1F9E0} LLM ERROR");
+    this.log(`   Agent: ${callbackContext.agentName}`);
+    this.log(`   Error: ${error}`);
+    return void 0;
+  }
+  async onToolErrorCallback({
+    tool,
+    toolArgs,
+    toolContext,
+    error
+  }) {
+    this.log("\u{1F527} TOOL ERROR");
+    this.log(`   Tool Name: ${tool.name}`);
+    this.log(`   Agent: ${toolContext.agentName}`);
+    this.log(`   Function Call ID: ${toolContext.functionCallId}`);
+    this.log(`   Arguments: ${this.formatArgs(toolArgs)}`);
+    this.log(`   Error: ${error}`);
+    return void 0;
+  }
+  log(message) {
+    const formattedMessage = `\x1B[90m[${this.name}] ${message}\x1B[0m`;
+    logger.info(formattedMessage);
+  }
+  formatContent(content, maxLength = 200) {
+    if (!content || !content.parts) {
+      return "None";
+    }
+    const parts = [];
+    for (const part of content.parts) {
+      if (part.text) {
+        let text = part.text.trim();
+        if (text.length > maxLength) {
+          text = text.substring(0, maxLength) + "...";
+        }
+        parts.push(`text: '${text}'`);
+      } else if (part.functionCall) {
+        parts.push(`function_call: ${part.functionCall.name}`);
+      } else if (part.functionResponse) {
+        parts.push(`function_response: ${part.functionResponse.name}`);
+      } else if (part.codeExecutionResult) {
+        parts.push("code_execution_result");
+      } else {
+        parts.push("other_part");
+      }
+    }
+    return parts.join(" | ");
+  }
+  formatArgs(args, maxLength = 300) {
+    if (!args) {
+      return "{}";
+    }
+    let formatted = JSON.stringify(args);
+    if (formatted.length > maxLength) {
+      formatted = formatted.substring(0, maxLength) + "...}";
+    }
+    return formatted;
+  }
+}
+export {
+  LoggingPlugin
+};