@paean-ai/adk 0.2.16 → 0.2.17

package/dist/cjs/agents/functions.js

@@ -0,0 +1,424 @@
+/**
+  * @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 functions_exports = {};
+__export(functions_exports, {
+  REQUEST_CONFIRMATION_FUNCTION_CALL_NAME: () => REQUEST_CONFIRMATION_FUNCTION_CALL_NAME,
+  REQUEST_EUC_FUNCTION_CALL_NAME: () => REQUEST_EUC_FUNCTION_CALL_NAME,
+  functionsExportedForTestingOnly: () => functionsExportedForTestingOnly,
+  generateAuthEvent: () => generateAuthEvent,
+  generateClientFunctionCallId: () => generateClientFunctionCallId,
+  generateRequestConfirmationEvent: () => generateRequestConfirmationEvent,
+  getLongRunningFunctionCalls: () => getLongRunningFunctionCalls,
+  handleFunctionCallList: () => handleFunctionCallList,
+  handleFunctionCallsAsync: () => handleFunctionCallsAsync,
+  mergeParallelFunctionResponseEvents: () => mergeParallelFunctionResponseEvents,
+  populateClientFunctionCallId: () => populateClientFunctionCallId,
+  removeClientFunctionCallId: () => removeClientFunctionCallId
+});
+module.exports = __toCommonJS(functions_exports);
+var import_genai = require("@google/genai");
+var import_event = require("../events/event.js");
+var import_event_actions = require("../events/event_actions.js");
+var import_tool_context = require("../tools/tool_context.js");
+var import_env_aware_utils = require("../utils/env_aware_utils.js");
+var import_logger = require("../utils/logger.js");
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const AF_FUNCTION_CALL_ID_PREFIX = "adk-";
+const REQUEST_EUC_FUNCTION_CALL_NAME = "adk_request_credential";
+const REQUEST_CONFIRMATION_FUNCTION_CALL_NAME = "adk_request_confirmation";
+const functionsExportedForTestingOnly = {
+  handleFunctionCallList
+};
+function generateClientFunctionCallId() {
+  return `${AF_FUNCTION_CALL_ID_PREFIX}${(0, import_env_aware_utils.randomUUID)()}`;
+}
+function populateClientFunctionCallId(modelResponseEvent) {
+  const functionCalls = (0, import_event.getFunctionCalls)(modelResponseEvent);
+  if (!functionCalls) {
+    return;
+  }
+  for (const functionCall of functionCalls) {
+    if (!functionCall.id) {
+      functionCall.id = generateClientFunctionCallId();
+    }
+  }
+}
+function removeClientFunctionCallId(content) {
+  if (content && content.parts) {
+    for (const part of content.parts) {
+      if (part.functionCall && part.functionCall.id && part.functionCall.id.startsWith(AF_FUNCTION_CALL_ID_PREFIX)) {
+        part.functionCall.id = void 0;
+      }
+      if (part.functionResponse && part.functionResponse.id && part.functionResponse.id.startsWith(AF_FUNCTION_CALL_ID_PREFIX)) {
+        part.functionResponse.id = void 0;
+      }
+    }
+  }
+}
+function resolveToolName(name, toolsDict) {
+  if (name in toolsDict) {
+    return name;
+  }
+  const colonIndex = name.indexOf(":");
+  if (colonIndex > 0) {
+    const baseName = name.substring(0, colonIndex);
+    if (baseName in toolsDict) {
+      import_logger.logger.info(
+        `Resolved Gemini 3 function name "${name}" to tool "${baseName}"`
+      );
+      return baseName;
+    }
+  }
+  return void 0;
+}
+function getLongRunningFunctionCalls(functionCalls, toolsDict) {
+  const longRunningToolIds = /* @__PURE__ */ new Set();
+  for (const functionCall of functionCalls) {
+    if (!functionCall.name || !functionCall.id) continue;
+    const resolvedName = resolveToolName(functionCall.name, toolsDict);
+    if (resolvedName && toolsDict[resolvedName].isLongRunning) {
+      longRunningToolIds.add(functionCall.id);
+    }
+  }
+  return longRunningToolIds;
+}
+function generateAuthEvent(invocationContext, functionResponseEvent) {
+  var _a;
+  if (!((_a = functionResponseEvent.actions) == null ? void 0 : _a.requestedAuthConfigs)) {
+    return void 0;
+  }
+  const parts = [];
+  const longRunningToolIds = /* @__PURE__ */ new Set();
+  for (const [functionCallId, authConfig] of Object.entries(
+    functionResponseEvent.actions.requestedAuthConfigs
+  )) {
+    const requestEucFunctionCall = {
+      name: REQUEST_EUC_FUNCTION_CALL_NAME,
+      args: {
+        "function_call_id": functionCallId,
+        "auth_config": authConfig
+      },
+      id: generateClientFunctionCallId()
+    };
+    longRunningToolIds.add(requestEucFunctionCall.id);
+    parts.push({ functionCall: requestEucFunctionCall });
+  }
+  return (0, import_event.createEvent)({
+    invocationId: invocationContext.invocationId,
+    author: invocationContext.agent.name,
+    branch: invocationContext.branch,
+    content: {
+      parts,
+      role: functionResponseEvent.content.role
+    },
+    longRunningToolIds: Array.from(longRunningToolIds)
+  });
+}
+function generateRequestConfirmationEvent({
+  invocationContext,
+  functionCallEvent,
+  functionResponseEvent
+}) {
+  var _a, _b;
+  if (!((_a = functionResponseEvent.actions) == null ? void 0 : _a.requestedToolConfirmations)) {
+    return;
+  }
+  const parts = [];
+  const longRunningToolIds = /* @__PURE__ */ new Set();
+  const functionCalls = (0, import_event.getFunctionCalls)(functionCallEvent);
+  for (const [functionCallId, toolConfirmation] of Object.entries(
+    functionResponseEvent.actions.requestedToolConfirmations
+  )) {
+    const originalFunctionCall = (_b = functionCalls.find((call) => call.id === functionCallId)) != null ? _b : void 0;
+    if (!originalFunctionCall) {
+      continue;
+    }
+    const requestConfirmationFunctionCall = {
+      name: REQUEST_CONFIRMATION_FUNCTION_CALL_NAME,
+      args: {
+        "originalFunctionCall": originalFunctionCall,
+        "toolConfirmation": toolConfirmation
+      },
+      id: generateClientFunctionCallId()
+    };
+    longRunningToolIds.add(requestConfirmationFunctionCall.id);
+    parts.push({ functionCall: requestConfirmationFunctionCall });
+  }
+  return (0, import_event.createEvent)({
+    invocationId: invocationContext.invocationId,
+    author: invocationContext.agent.name,
+    branch: invocationContext.branch,
+    content: {
+      parts,
+      role: functionResponseEvent.content.role
+    },
+    longRunningToolIds: Array.from(longRunningToolIds)
+  });
+}
+async function callToolAsync(tool, args, toolContext) {
+  import_logger.logger.debug(`callToolAsync ${tool.name}`);
+  return await tool.runAsync({ args, toolContext });
+}
+async function handleFunctionCallsAsync({
+  invocationContext,
+  functionCallEvent,
+  toolsDict,
+  beforeToolCallbacks,
+  afterToolCallbacks,
+  filters,
+  toolConfirmationDict
+}) {
+  const functionCalls = (0, import_event.getFunctionCalls)(functionCallEvent);
+  return await handleFunctionCallList({
+    invocationContext,
+    functionCalls,
+    toolsDict,
+    beforeToolCallbacks,
+    afterToolCallbacks,
+    filters,
+    toolConfirmationDict
+  });
+}
+async function handleFunctionCallList({
+  invocationContext,
+  functionCalls,
+  toolsDict,
+  beforeToolCallbacks,
+  afterToolCallbacks,
+  filters,
+  toolConfirmationDict
+}) {
+  var _a, _b, _c;
+  const functionResponseEvents = [];
+  const filteredFunctionCalls = functionCalls.filter((functionCall) => {
+    return !filters || functionCall.id && filters.has(functionCall.id);
+  });
+  for (const functionCall of filteredFunctionCalls) {
+    let toolConfirmation = void 0;
+    if (toolConfirmationDict && functionCall.id) {
+      toolConfirmation = toolConfirmationDict[functionCall.id];
+    }
+    const toolAndContext = getToolAndContext(
+      {
+        invocationContext,
+        functionCall,
+        toolsDict,
+        toolConfirmation
+      }
+    );
+    if (!toolAndContext) {
+      import_logger.logger.warn(
+        `Function ${functionCall.name} is not found in the toolsDict. Returning error response to LLM.`
+      );
+      const errorResponseEvent = (0, import_event.createEvent)({
+        invocationId: invocationContext.invocationId,
+        author: invocationContext.agent.name,
+        content: (0, import_genai.createUserContent)({
+          functionResponse: {
+            id: functionCall.id || void 0,
+            name: (_a = functionCall.name) != null ? _a : "unknown",
+            response: {
+              error: `Function ${functionCall.name} is not available. If this tool belongs to a lazy-loaded group, call loadToolGroup first in a SEPARATE step, then retry.`
+            }
+          }
+        }),
+        branch: invocationContext.branch
+      });
+      functionResponseEvents.push(errorResponseEvent);
+      continue;
+    }
+    const { tool, toolContext } = toolAndContext;
+    import_logger.logger.debug(`execute_tool ${tool.name}`);
+    const functionArgs = (_b = functionCall.args) != null ? _b : {};
+    let functionResponse = null;
+    let functionResponseError;
+    functionResponse = await invocationContext.pluginManager.runBeforeToolCallback({
+      tool,
+      toolArgs: functionArgs,
+      toolContext
+    });
+    if (functionResponse == null) {
+      for (const callback of beforeToolCallbacks) {
+        functionResponse = await callback({
+          tool,
+          args: functionArgs,
+          context: toolContext
+        });
+        if (functionResponse) {
+          break;
+        }
+      }
+    }
+    if (functionResponse == null) {
+      try {
+        functionResponse = await callToolAsync(
+          tool,
+          functionArgs,
+          toolContext
+        );
+      } catch (e) {
+        if (e instanceof Error) {
+          const onToolErrorResponse = await invocationContext.pluginManager.runOnToolErrorCallback(
+            {
+              tool,
+              toolArgs: functionArgs,
+              toolContext,
+              error: e
+            }
+          );
+          if (onToolErrorResponse) {
+            functionResponse = onToolErrorResponse;
+          } else {
+            functionResponseError = e.message;
+          }
+        } else {
+          functionResponseError = e;
+        }
+      }
+    }
+    let alteredFunctionResponse = await invocationContext.pluginManager.runAfterToolCallback({
+      tool,
+      toolArgs: functionArgs,
+      toolContext,
+      result: functionResponse
+    });
+    if (alteredFunctionResponse == null) {
+      for (const callback of afterToolCallbacks) {
+        alteredFunctionResponse = await callback({
+          tool,
+          args: functionArgs,
+          context: toolContext,
+          response: functionResponse
+        });
+        if (alteredFunctionResponse) {
+          break;
+        }
+      }
+    }
+    if (alteredFunctionResponse != null) {
+      functionResponse = alteredFunctionResponse;
+    }
+    if (tool.isLongRunning && !functionResponse) {
+      continue;
+    }
+    if (functionResponseError) {
+      functionResponse = { error: functionResponseError };
+    } else if (typeof functionResponse !== "object" || functionResponse == null) {
+      functionResponse = { result: functionResponse };
+    }
+    const functionResponseEvent = (0, import_event.createEvent)({
+      invocationId: invocationContext.invocationId,
+      author: invocationContext.agent.name,
+      content: (0, import_genai.createUserContent)({
+        functionResponse: {
+          id: toolContext.functionCallId,
+          name: (_c = functionCall.name) != null ? _c : tool.name,
+          response: functionResponse
+        }
+      }),
+      actions: toolContext.actions,
+      branch: invocationContext.branch
+    });
+    import_logger.logger.debug("traceToolCall", {
+      tool: tool.name,
+      args: functionArgs,
+      functionResponseEvent: functionResponseEvent.id
+    });
+    functionResponseEvents.push(functionResponseEvent);
+  }
+  if (!functionResponseEvents.length) {
+    return null;
+  }
+  const mergedEvent = mergeParallelFunctionResponseEvents(functionResponseEvents);
+  if (functionResponseEvents.length > 1) {
+    import_logger.logger.debug("execute_tool (merged)");
+    import_logger.logger.debug("traceMergedToolCalls", {
+      responseEventId: mergedEvent.id,
+      functionResponseEvent: mergedEvent.id
+    });
+  }
+  return mergedEvent;
+}
+function getToolAndContext({
+  invocationContext,
+  functionCall,
+  toolsDict,
+  toolConfirmation
+}) {
+  const resolvedName = functionCall.name ? resolveToolName(functionCall.name, toolsDict) : void 0;
+  if (!resolvedName) {
+    return null;
+  }
+  const toolContext = new import_tool_context.ToolContext({
+    invocationContext,
+    functionCallId: functionCall.id || void 0,
+    toolConfirmation
+  });
+  const tool = toolsDict[resolvedName];
+  return { tool, toolContext };
+}
+function mergeParallelFunctionResponseEvents(functionResponseEvents) {
+  if (!functionResponseEvents.length) {
+    throw new Error("No function response events provided.");
+  }
+  if (functionResponseEvents.length === 1) {
+    return functionResponseEvents[0];
+  }
+  const mergedParts = [];
+  for (const event of functionResponseEvents) {
+    if (event.content && event.content.parts) {
+      mergedParts.push(...event.content.parts);
+    }
+  }
+  const baseEvent = functionResponseEvents[0];
+  const actionsList = functionResponseEvents.map((event) => event.actions || {});
+  const mergedActions = (0, import_event_actions.mergeEventActions)(actionsList);
+  return (0, import_event.createEvent)({
+    author: baseEvent.author,
+    branch: baseEvent.branch,
+    content: { role: "user", parts: mergedParts },
+    actions: mergedActions,
+    timestamp: baseEvent.timestamp
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  REQUEST_CONFIRMATION_FUNCTION_CALL_NAME,
+  REQUEST_EUC_FUNCTION_CALL_NAME,
+  functionsExportedForTestingOnly,
+  generateAuthEvent,
+  generateClientFunctionCallId,
+  generateRequestConfirmationEvent,
+  getLongRunningFunctionCalls,
+  handleFunctionCallList,
+  handleFunctionCallsAsync,
+  mergeParallelFunctionResponseEvents,
+  populateClientFunctionCallId,
+  removeClientFunctionCallId
+});

package/dist/cjs/agents/instructions.js

@@ -0,0 +1,110 @@
+/**
+  * @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 instructions_exports = {};
+__export(instructions_exports, {
+  injectSessionState: () => injectSessionState
+});
+module.exports = __toCommonJS(instructions_exports);
+var import_state = require("../sessions/state.js");
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+async function injectSessionState(template, readonlyContext) {
+  const invocationContext = readonlyContext.invocationContext;
+  async function replaceMatchedKeyWithItsValue(match) {
+    let key = match[0].replace(/^\{+/, "").replace(/\}+$/, "").trim();
+    const isOptional = key.endsWith("?");
+    if (isOptional) {
+      key = key.slice(0, -1);
+    }
+    if (key.startsWith("artifact.")) {
+      const fileName = key.substring("artifact.".length);
+      if (invocationContext.artifactService === void 0) {
+        throw new Error("Artifact service is not initialized.");
+      }
+      const artifact = await invocationContext.artifactService.loadArtifact({
+        appName: invocationContext.session.appName,
+        userId: invocationContext.session.userId,
+        sessionId: invocationContext.session.id,
+        filename: fileName
+      });
+      if (!artifact) {
+        throw new Error(`Artifact ${fileName} not found.`);
+      }
+      return String(artifact);
+    }
+    if (!isValidStateName(key)) {
+      return match[0];
+    }
+    if (key in invocationContext.session.state) {
+      return String(invocationContext.session.state[key]);
+    }
+    if (isOptional) {
+      return "";
+    }
+    throw new Error(`Context variable not found: \`${key}\`.`);
+  }
+  const pattern = /\{+[^{}]*}+/g;
+  const result = [];
+  let lastEnd = 0;
+  const matches = template.matchAll(pattern);
+  for (const match of matches) {
+    result.push(template.slice(lastEnd, match.index));
+    const replacement = await replaceMatchedKeyWithItsValue(match);
+    result.push(replacement);
+    lastEnd = match.index + match[0].length;
+  }
+  result.push(template.slice(lastEnd));
+  return result.join("");
+}
+const isIdentifierPattern = /* @__PURE__ */ (() => {
+  return /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+})();
+function isIdentifier(s) {
+  if (s === "" || s === void 0) {
+    return false;
+  }
+  return isIdentifierPattern.test(s);
+}
+const VALID_PREFIXES = [import_state.State.APP_PREFIX, import_state.State.USER_PREFIX, import_state.State.TEMP_PREFIX];
+function isValidStateName(variableName) {
+  const parts = variableName.split(":");
+  if (parts.length === 0 || parts.length > 2) {
+    return false;
+  }
+  if (parts.length === 1) {
+    return isIdentifier(variableName);
+  }
+  if (VALID_PREFIXES.includes(parts[0] + ":")) {
+    return isIdentifier(parts[1]);
+  }
+  return false;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  injectSessionState
+});

package/dist/cjs/agents/invocation_context.js

@@ -0,0 +1,107 @@
+/**
+  * @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 invocation_context_exports = {};
+__export(invocation_context_exports, {
+  InvocationContext: () => InvocationContext,
+  newInvocationContextId: () => newInvocationContextId
+});
+module.exports = __toCommonJS(invocation_context_exports);
+var import_env_aware_utils = require("../utils/env_aware_utils.js");
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+class InvocationCostManager {
+  constructor() {
+    this.numberOfLlmCalls = 0;
+  }
+  /**
+   * Increments the number of llm calls and enforces the limit.
+   *
+   * @param runConfig the run config of the invocation.
+   * @throws If number of llm calls made exceed the set threshold.
+   */
+  incrementAndEnforceLlmCallsLimit(runConfig) {
+    this.numberOfLlmCalls++;
+    if (runConfig && runConfig.maxLlmCalls > 0 && this.numberOfLlmCalls > runConfig.maxLlmCalls) {
+      throw new Error(`Max number of llm calls limit of ${runConfig.maxLlmCalls} exceeded`);
+    }
+  }
+}
+class InvocationContext {
+  /**
+   * @param params The parameters for creating an invocation context.
+   */
+  constructor(params) {
+    /**
+     * A container to keep track of different kinds of costs incurred as a part of
+     * this invocation.
+     */
+    this.invocationCostManager = new InvocationCostManager();
+    this.artifactService = params.artifactService;
+    this.sessionService = params.sessionService;
+    this.memoryService = params.memoryService;
+    this.invocationId = params.invocationId;
+    this.branch = params.branch;
+    this.agent = params.agent;
+    this.userContent = params.userContent;
+    this.session = params.session;
+    this.endInvocation = params.endInvocation || false;
+    this.transcriptionCache = params.transcriptionCache;
+    this.runConfig = params.runConfig;
+    this.liveRequestQueue = params.liveRequestQueue;
+    this.activeStreamingTools = params.activeStreamingTools;
+    this.pluginManager = params.pluginManager;
+  }
+  /**
+   * The app name of the current session.
+   */
+  get appName() {
+    return this.session.appName;
+  }
+  /**
+   * The user ID of the current session.
+   */
+  get userId() {
+    return this.session.userId;
+  }
+  /**
+   * Tracks number of llm calls made.
+   *
+   * @throws If number of llm calls made exceed the set threshold.
+   */
+  incrementLlmCallCount() {
+    this.invocationCostManager.incrementAndEnforceLlmCallsLimit(this.runConfig);
+  }
+}
+function newInvocationContextId() {
+  return `e-${(0, import_env_aware_utils.randomUUID)()}`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  InvocationContext,
+  newInvocationContextId
+});