@google/adk 2.2.0 → 2.3.0

package/dist/esm/plugins/debug_logging_plugin.js

@@ -0,0 +1,615 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+var _a, _b;
+import * as yaml from "js-yaml";
+import * as fs from "node:fs";
+import { AuthCredentialTypes } from "../auth/auth_credential.js";
+import { isFinalResponse } from "../events/event.js";
+import { State } from "../sessions/state.js";
+import { logger } from "../utils/logger.js";
+import { toSnakeCaseKey } from "../utils/object_notation_utils.js";
+import { BasePlugin } from "./base_plugin.js";
+const DEBUG_LOGGING_PLUGIN_SYMBOL = /* @__PURE__ */ Symbol.for("google.adk.debugLoggingPlugin");
+const REDACTED = "[REDACTED]";
+const AUTH_CREDENTIAL_TYPES = /* @__PURE__ */ new Set([
+  AuthCredentialTypes.API_KEY,
+  AuthCredentialTypes.HTTP,
+  AuthCredentialTypes.OAUTH2,
+  AuthCredentialTypes.OPEN_ID_CONNECT,
+  AuthCredentialTypes.SERVICE_ACCOUNT
+]);
+const SENSITIVE_KEYS = /* @__PURE__ */ new Set([
+  "access_token",
+  "api_key",
+  "auth_code",
+  "auth_response_uri",
+  "authorization",
+  "client_secret",
+  "code_verifier",
+  "google_access_id",
+  "id_token",
+  "password",
+  "private_key",
+  "private_key_id",
+  "proxy_authorization",
+  "refresh_token",
+  "secret",
+  "sig",
+  "signature",
+  "token",
+  "x_amz_credential",
+  "x_amz_signature",
+  "x_api_key",
+  "x_goog_credential",
+  "x_goog_security_token",
+  "x_goog_signature"
+]);
+const SENSITIVE_SUBSTRINGS = [
+  "api_key",
+  "credentials",
+  "passwd",
+  "password",
+  "private_key",
+  "secret"
+];
+const SENSITIVE_SUFFIXES = ["_token"];
+const STATE_PREFIXES = [State.APP_PREFIX, State.USER_PREFIX];
+const PRIVATE_KEY_BLOCK = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----[\s\S]*?(?:-----END [A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----|$)/g;
+const OUTPUT_FILE_MODE = 384;
+const MAX_WALK_DEPTH = 20;
+function isSensitiveKey(key) {
+  if (typeof key !== "string") {
+    return false;
+  }
+  let normalized = toSnakeCaseKey(key);
+  if (normalized.startsWith(State.TEMP_PREFIX)) {
+    return true;
+  }
+  for (const prefix of STATE_PREFIXES) {
+    if (normalized.startsWith(prefix)) {
+      normalized = normalized.slice(prefix.length);
+      break;
+    }
+  }
+  if (SENSITIVE_KEYS.has(normalized) || SENSITIVE_SUFFIXES.some((suffix) => normalized.endsWith(suffix))) {
+    return true;
+  }
+  return SENSITIVE_SUBSTRINGS.some((marker) => normalized.includes(marker));
+}
+__name(isSensitiveKey, "isSensitiveKey");
+function redactPrivateKeys(value) {
+  return String(value).replace(PRIVATE_KEY_BLOCK, REDACTED);
+}
+__name(redactPrivateKeys, "redactPrivateKeys");
+function isCredentialObject(obj) {
+  var _a2;
+  if (typeof obj !== "object" || obj === null) {
+    return false;
+  }
+  const record = obj;
+  const authType = (_a2 = record["authType"]) != null ? _a2 : record["auth_type"];
+  return typeof authType === "string" && AUTH_CREDENTIAL_TYPES.has(authType);
+}
+__name(isCredentialObject, "isCredentialObject");
+function isDebugLoggingPlugin(obj) {
+  return typeof obj === "object" && obj !== null && DEBUG_LOGGING_PLUGIN_SYMBOL in obj && obj[DEBUG_LOGGING_PLUGIN_SYMBOL] === true;
+}
+__name(isDebugLoggingPlugin, "isDebugLoggingPlugin");
+const _DebugLoggingPlugin = class _DebugLoggingPlugin extends (_b = BasePlugin, _a = DEBUG_LOGGING_PLUGIN_SYMBOL, _b) {
+  constructor(options = {}) {
+    var _a2, _b2, _c, _d;
+    super((_a2 = options.name) != null ? _a2 : "debug_logging_plugin");
+    this[_a] = true;
+    this.invocationStates = /* @__PURE__ */ new Map();
+    this.warnedAboutOutputMode = false;
+    this.outputPath = (_b2 = options.outputPath) != null ? _b2 : "adk_debug.yaml";
+    this.includeSessionState = (_c = options.includeSessionState) != null ? _c : true;
+    this.includeSystemInstruction = (_d = options.includeSystemInstruction) != null ? _d : true;
+  }
+  /**
+   * Exposes active invocation states for testing and inspection.
+   */
+  getInvocationState(invocationId) {
+    return this.invocationStates.get(invocationId);
+  }
+  getTimestamp() {
+    return (/* @__PURE__ */ new Date()).toISOString();
+  }
+  /**
+   * Serializes a Gemini `Content` object to a dictionary for YAML output.
+   */
+  serializeContent(content) {
+    var _a2, _b2, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m;
+    if (!content) {
+      return null;
+    }
+    const parts = [];
+    if (content.parts) {
+      for (const part of content.parts) {
+        const partData = {};
+        if (part.text) {
+          partData["text"] = part.text;
+        }
+        if (part.functionCall) {
+          partData["function_call"] = {
+            id: (_a2 = part.functionCall.id) != null ? _a2 : null,
+            name: (_b2 = part.functionCall.name) != null ? _b2 : null,
+            args: this.safeSerialize(part.functionCall.args)
+          };
+        }
+        if (part.functionResponse) {
+          partData["function_response"] = {
+            id: (_c = part.functionResponse.id) != null ? _c : null,
+            name: (_d = part.functionResponse.name) != null ? _d : null,
+            response: this.safeSerialize(part.functionResponse.response)
+          };
+        }
+        if (part.inlineData) {
+          partData["inline_data"] = {
+            mime_type: (_e = part.inlineData.mimeType) != null ? _e : null,
+            display_name: (_f = part.inlineData.displayName) != null ? _f : null,
+            _data_omitted: true
+          };
+        }
+        if (part.fileData) {
+          partData["file_data"] = {
+            file_uri: (_g = part.fileData.fileUri) != null ? _g : null,
+            mime_type: (_h = part.fileData.mimeType) != null ? _h : null
+          };
+        }
+        if (part.codeExecutionResult) {
+          partData["code_execution_result"] = {
+            outcome: String((_i = part.codeExecutionResult.outcome) != null ? _i : ""),
+            output: (_j = part.codeExecutionResult.output) != null ? _j : null
+          };
+        }
+        if (part.executableCode) {
+          partData["executable_code"] = {
+            language: String((_k = part.executableCode.language) != null ? _k : ""),
+            code: (_l = part.executableCode.code) != null ? _l : null
+          };
+        }
+        if (Object.keys(partData).length > 0) {
+          parts.push(partData);
+        }
+      }
+    }
+    return {
+      role: (_m = content.role) != null ? _m : null,
+      parts
+    };
+  }
+  /**
+   * Safely serializes an arbitrary value to a YAML/JSON-compatible format with
+   * credential, sensitive key, and private key redaction.
+   */
+  safeSerialize(obj, depth = 0) {
+    if (obj === null || obj === void 0) {
+      return null;
+    }
+    if (isCredentialObject(obj)) {
+      return REDACTED;
+    }
+    if (depth > MAX_WALK_DEPTH) {
+      return Array.isArray(obj) ? "<list ...>" : "<dict ...>";
+    }
+    const childDepth = depth + 1;
+    if (typeof obj === "string") {
+      return redactPrivateKeys(obj);
+    }
+    if (typeof obj === "number" || typeof obj === "boolean") {
+      return obj;
+    }
+    if (obj instanceof Date) {
+      return obj.toISOString();
+    }
+    if (Buffer.isBuffer(obj) || obj instanceof Uint8Array) {
+      return `<bytes: ${obj.byteLength} bytes>`;
+    }
+    if (Array.isArray(obj)) {
+      return obj.map((item) => this.safeSerialize(item, childDepth));
+    }
+    if (obj instanceof Set) {
+      return Array.from(obj).map(
+        (item) => this.safeSerialize(item, childDepth)
+      );
+    }
+    if (obj instanceof Map) {
+      const result = {};
+      for (const [k, v] of obj.entries()) {
+        const keyStr = String(k);
+        result[keyStr] = isSensitiveKey(keyStr) ? REDACTED : this.safeSerialize(v, childDepth);
+      }
+      return result;
+    }
+    if (typeof obj === "object") {
+      const result = {};
+      for (const [k, v] of Object.entries(obj)) {
+        if (v === void 0) {
+          continue;
+        }
+        result[k] = isSensitiveKey(k) ? REDACTED : this.safeSerialize(v, childDepth);
+      }
+      return result;
+    }
+    try {
+      return String(obj);
+    } catch {
+      return "<unserializable>";
+    }
+  }
+  addEntry(invocationId, entryType, agentName, data = {}) {
+    var _a2;
+    const state = this.invocationStates.get(invocationId);
+    if (!state) {
+      logger.warn(
+        `No debug state for invocation ${invocationId}, skipping entry`
+      );
+      return;
+    }
+    const entry = {
+      timestamp: this.getTimestamp(),
+      entry_type: entryType,
+      invocation_id: invocationId,
+      ...agentName !== void 0 ? { agent_name: agentName } : {},
+      data: (_a2 = this.safeSerialize(data)) != null ? _a2 : {}
+    };
+    state.entries.push(entry);
+  }
+  async onUserMessageCallback({
+    invocationContext,
+    userMessage
+  }) {
+    this.addEntry(invocationContext.invocationId, "user_message", void 0, {
+      content: this.serializeContent(userMessage)
+    });
+    return void 0;
+  }
+  async beforeRunCallback({
+    invocationContext
+  }) {
+    var _a2, _b2;
+    const invocationId = invocationContext.invocationId;
+    const session = invocationContext.session;
+    const state = {
+      invocation_id: invocationId,
+      session_id: session.id,
+      app_name: session.appName,
+      ...invocationContext.userId ? { user_id: invocationContext.userId } : {},
+      start_time: this.getTimestamp(),
+      entries: []
+    };
+    this.invocationStates.set(invocationId, state);
+    this.addEntry(
+      invocationId,
+      "invocation_start",
+      (_a2 = invocationContext.agent) == null ? void 0 : _a2.name,
+      {
+        branch: (_b2 = invocationContext.branch) != null ? _b2 : null
+      }
+    );
+    return void 0;
+  }
+  async onEventCallback({
+    invocationContext,
+    event
+  }) {
+    var _a2, _b2, _c, _d, _e, _f, _g, _h;
+    const invocationId = invocationContext.invocationId;
+    const eventData = {
+      event_id: event.id,
+      author: (_a2 = event.author) != null ? _a2 : null,
+      content: this.serializeContent(event.content),
+      is_final_response: isFinalResponse(event),
+      partial: (_b2 = event.partial) != null ? _b2 : null,
+      turn_complete: (_c = event.turnComplete) != null ? _c : null,
+      branch: (_d = event.branch) != null ? _d : null
+    };
+    if (event.actions) {
+      const actionsData = {};
+      if (event.actions.stateDelta && Object.keys(event.actions.stateDelta).length > 0) {
+        actionsData["state_delta"] = this.safeSerialize(
+          event.actions.stateDelta
+        );
+      }
+      if (event.actions.artifactDelta && Object.keys(event.actions.artifactDelta).length > 0) {
+        actionsData["artifact_delta"] = { ...event.actions.artifactDelta };
+      }
+      if (event.actions.transferToAgent) {
+        actionsData["transfer_to_agent"] = event.actions.transferToAgent;
+      }
+      if (event.actions.escalate) {
+        actionsData["escalate"] = event.actions.escalate;
+      }
+      if (event.actions.requestedAuthConfigs && Object.keys(event.actions.requestedAuthConfigs).length > 0) {
+        actionsData["requested_auth_configs"] = Object.keys(
+          event.actions.requestedAuthConfigs
+        ).length;
+      }
+      if (Object.keys(actionsData).length > 0) {
+        eventData["actions"] = actionsData;
+      }
+    }
+    if (event.groundingMetadata) {
+      eventData["has_grounding_metadata"] = true;
+    }
+    if (event.usageMetadata) {
+      eventData["usage_metadata"] = {
+        prompt_token_count: (_e = event.usageMetadata.promptTokenCount) != null ? _e : null,
+        candidates_token_count: (_f = event.usageMetadata.candidatesTokenCount) != null ? _f : null,
+        total_token_count: (_g = event.usageMetadata.totalTokenCount) != null ? _g : null
+      };
+    }
+    if (event.errorCode) {
+      eventData["error_code"] = event.errorCode;
+      eventData["error_message"] = (_h = event.errorMessage) != null ? _h : null;
+    }
+    if (event.longRunningToolIds && event.longRunningToolIds.length > 0) {
+      eventData["long_running_tool_ids"] = [...event.longRunningToolIds];
+    }
+    this.addEntry(invocationId, "event", event.author, eventData);
+    return void 0;
+  }
+  async afterRunCallback({
+    invocationContext
+  }) {
+    var _a2, _b2;
+    const invocationId = invocationContext.invocationId;
+    const state = this.invocationStates.get(invocationId);
+    if (!state) {
+      logger.warn(
+        `No debug state for invocation ${invocationId}, skipping write`
+      );
+      return;
+    }
+    if (this.includeSessionState) {
+      const session = invocationContext.session;
+      this.addEntry(invocationId, "session_state_snapshot", void 0, {
+        state: this.safeSerialize(session.state),
+        event_count: (_b2 = (_a2 = session.events) == null ? void 0 : _a2.length) != null ? _b2 : 0
+      });
+    }
+    this.addEntry(invocationId, "invocation_end");
+    let fd;
+    try {
+      fd = fs.openSync(
+        this.outputPath,
+        fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_APPEND,
+        OUTPUT_FILE_MODE
+      );
+      if (process.platform !== "win32" && !this.warnedAboutOutputMode && (fs.fstatSync(fd).mode & 63) !== 0) {
+        this.warnedAboutOutputMode = true;
+        logger.warn(
+          `Debug output file ${this.outputPath} is readable beyond its owner and holds whole prompts and responses; restrict it to mode 600.`
+        );
+      }
+      const yamlDoc = "---\n" + yaml.dump(state, {
+        noRefs: true,
+        lineWidth: 120,
+        sortKeys: false
+      });
+      fs.writeFileSync(fd, yamlDoc, { encoding: "utf-8" });
+      logger.debug(
+        `Wrote debug data for invocation ${invocationId} to ${this.outputPath}`
+      );
+    } catch (e) {
+      logger.error(`Failed to write debug data: ${e}`);
+    } finally {
+      if (fd !== void 0) {
+        try {
+          fs.closeSync(fd);
+        } catch {
+        }
+      }
+      this.invocationStates.delete(invocationId);
+    }
+  }
+  async beforeAgentCallback({
+    callbackContext
+  }) {
+    var _a2, _b2;
+    this.addEntry(
+      callbackContext.invocationId,
+      "agent_start",
+      callbackContext.agentName,
+      {
+        branch: (_b2 = (_a2 = callbackContext.invocationContext) == null ? void 0 : _a2.branch) != null ? _b2 : null
+      }
+    );
+    return void 0;
+  }
+  async afterAgentCallback({
+    callbackContext
+  }) {
+    this.addEntry(
+      callbackContext.invocationId,
+      "agent_end",
+      callbackContext.agentName
+    );
+    return void 0;
+  }
+  async beforeModelCallback({
+    callbackContext,
+    llmRequest
+  }) {
+    var _a2, _b2, _c, _d;
+    const requestData = {
+      model: (_a2 = llmRequest.model) != null ? _a2 : null,
+      content_count: (_c = (_b2 = llmRequest.contents) == null ? void 0 : _b2.length) != null ? _c : 0,
+      contents: ((_d = llmRequest.contents) != null ? _d : []).map(
+        (c) => this.serializeContent(c)
+      )
+    };
+    if (llmRequest.toolsDict && Object.keys(llmRequest.toolsDict).length > 0) {
+      requestData["tools"] = Object.keys(llmRequest.toolsDict);
+    }
+    if (llmRequest.config) {
+      const config = llmRequest.config;
+      const configData = {};
+      if (this.includeSystemInstruction && config.systemInstruction) {
+        configData["system_instruction"] = config.systemInstruction;
+      } else if (config.systemInstruction) {
+        if (typeof config.systemInstruction === "string") {
+          configData["system_instruction_length"] = config.systemInstruction.length;
+        } else {
+          configData["has_system_instruction"] = true;
+        }
+      }
+      if (config.temperature !== void 0 && config.temperature !== null) {
+        configData["temperature"] = config.temperature;
+      }
+      if (config.topP !== void 0 && config.topP !== null) {
+        configData["top_p"] = config.topP;
+      }
+      if (config.topK !== void 0 && config.topK !== null) {
+        configData["top_k"] = config.topK;
+      }
+      if (config.maxOutputTokens !== void 0 && config.maxOutputTokens !== null) {
+        configData["max_output_tokens"] = config.maxOutputTokens;
+      }
+      if (config.responseMimeType) {
+        configData["response_mime_type"] = config.responseMimeType;
+      }
+      if (config.responseSchema) {
+        configData["has_response_schema"] = true;
+      }
+      if (Object.keys(configData).length > 0) {
+        requestData["config"] = configData;
+      }
+    }
+    this.addEntry(
+      callbackContext.invocationId,
+      "llm_request",
+      callbackContext.agentName,
+      requestData
+    );
+    return void 0;
+  }
+  async afterModelCallback({
+    callbackContext,
+    llmResponse
+  }) {
+    var _a2, _b2, _c, _d, _e, _f, _g;
+    const responseData = {
+      content: this.serializeContent(llmResponse.content),
+      partial: (_a2 = llmResponse.partial) != null ? _a2 : null,
+      turn_complete: (_b2 = llmResponse.turnComplete) != null ? _b2 : null
+    };
+    if (llmResponse.errorCode) {
+      responseData["error_code"] = llmResponse.errorCode;
+      responseData["error_message"] = (_c = llmResponse.errorMessage) != null ? _c : null;
+    }
+    if (llmResponse.usageMetadata) {
+      responseData["usage_metadata"] = {
+        prompt_token_count: (_d = llmResponse.usageMetadata.promptTokenCount) != null ? _d : null,
+        candidates_token_count: (_e = llmResponse.usageMetadata.candidatesTokenCount) != null ? _e : null,
+        total_token_count: (_f = llmResponse.usageMetadata.totalTokenCount) != null ? _f : null,
+        cached_content_token_count: (_g = llmResponse.usageMetadata.cachedContentTokenCount) != null ? _g : null
+      };
+    }
+    if (llmResponse.groundingMetadata) {
+      responseData["has_grounding_metadata"] = true;
+    }
+    if (llmResponse.finishReason) {
+      responseData["finish_reason"] = String(llmResponse.finishReason);
+    }
+    if (llmResponse.modelVersion) {
+      responseData["model_version"] = llmResponse.modelVersion;
+    }
+    this.addEntry(
+      callbackContext.invocationId,
+      "llm_response",
+      callbackContext.agentName,
+      responseData
+    );
+    return void 0;
+  }
+  async onModelErrorCallback({
+    callbackContext,
+    llmRequest,
+    error
+  }) {
+    var _a2;
+    this.addEntry(
+      callbackContext.invocationId,
+      "llm_error",
+      callbackContext.agentName,
+      {
+        error_type: error.name || "Error",
+        error_message: error.message || String(error),
+        model: (_a2 = llmRequest.model) != null ? _a2 : null
+      }
+    );
+    return void 0;
+  }
+  async beforeToolCallback({
+    tool,
+    toolArgs,
+    toolContext
+  }) {
+    var _a2;
+    this.addEntry(
+      toolContext.invocationId,
+      "tool_call",
+      toolContext.agentName,
+      {
+        tool_name: tool.name,
+        function_call_id: (_a2 = toolContext.functionCallId) != null ? _a2 : null,
+        args: this.safeSerialize(toolArgs)
+      }
+    );
+    return void 0;
+  }
+  async afterToolCallback({
+    tool,
+    toolContext,
+    result
+  }) {
+    var _a2;
+    this.addEntry(
+      toolContext.invocationId,
+      "tool_response",
+      toolContext.agentName,
+      {
+        tool_name: tool.name,
+        function_call_id: (_a2 = toolContext.functionCallId) != null ? _a2 : null,
+        result: this.safeSerialize(result)
+      }
+    );
+    return void 0;
+  }
+  async onToolErrorCallback({
+    tool,
+    toolArgs,
+    toolContext,
+    error
+  }) {
+    var _a2;
+    this.addEntry(
+      toolContext.invocationId,
+      "tool_error",
+      toolContext.agentName,
+      {
+        tool_name: tool.name,
+        function_call_id: (_a2 = toolContext.functionCallId) != null ? _a2 : null,
+        args: this.safeSerialize(toolArgs),
+        error_type: error.name || "Error",
+        error_message: error.message || String(error)
+      }
+    );
+    return void 0;
+  }
+};
+__name(_DebugLoggingPlugin, "DebugLoggingPlugin");
+let DebugLoggingPlugin = _DebugLoggingPlugin;
+export {
+  DebugLoggingPlugin,
+  isDebugLoggingPlugin
+};

package/dist/esm/plugins/plugin_manager.js

@@ -78,7 +78,7 @@ const _PluginManager = class _PluginManager {
       } catch (e) {
         const errorMessage = `Error in plugin '${plugin.name}' during '${callbackName}' callback: ${e}`;
         logger.error(errorMessage);
-        throw new Error(errorMessage);
+        throw new Error(errorMessage, { cause: e });
       }
     }
     return void 0;