@google/adk 0.3.0 → 0.5.0

package/dist/esm/agents/processors/request_confirmation_llm_request_processor.js

@@ -0,0 +1,140 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import {
+  getFunctionCalls,
+  getFunctionResponses
+} from "../../events/event.js";
+import { ToolConfirmation } from "../../tools/tool_confirmation.js";
+import {
+  REQUEST_CONFIRMATION_FUNCTION_CALL_NAME,
+  handleFunctionCallList
+} from "../functions.js";
+import { isLlmAgent } from "../llm_agent.js";
+import { ReadonlyContext } from "../readonly_context.js";
+import { BaseLlmRequestProcessor } from "./base_llm_processor.js";
+class RequestConfirmationLlmRequestProcessor extends BaseLlmRequestProcessor {
+  /** Handles tool confirmation information to build the LLM request. */
+  async *runAsync(invocationContext) {
+    const agent = invocationContext.agent;
+    if (!isLlmAgent(agent)) {
+      return;
+    }
+    const events = invocationContext.session.events;
+    if (!events || events.length === 0) {
+      return;
+    }
+    const requestConfirmationFunctionResponses = {};
+    let confirmationEventIndex = -1;
+    for (let i = events.length - 1; i >= 0; i--) {
+      const event = events[i];
+      if (event.author !== "user") {
+        continue;
+      }
+      const responses = getFunctionResponses(event);
+      if (!responses) {
+        continue;
+      }
+      let foundConfirmation = false;
+      for (const functionResponse of responses) {
+        if (functionResponse.name !== REQUEST_CONFIRMATION_FUNCTION_CALL_NAME) {
+          continue;
+        }
+        foundConfirmation = true;
+        let toolConfirmation = null;
+        if (functionResponse.response && Object.keys(functionResponse.response).length === 1 && "response" in functionResponse.response) {
+          toolConfirmation = JSON.parse(
+            functionResponse.response["response"]
+          );
+        } else if (functionResponse.response) {
+          toolConfirmation = new ToolConfirmation({
+            hint: functionResponse.response["hint"],
+            payload: functionResponse.response["payload"],
+            confirmed: functionResponse.response["confirmed"]
+          });
+        }
+        if (functionResponse.id && toolConfirmation) {
+          requestConfirmationFunctionResponses[functionResponse.id] = toolConfirmation;
+        }
+      }
+      if (foundConfirmation) {
+        confirmationEventIndex = i;
+        break;
+      }
+    }
+    if (Object.keys(requestConfirmationFunctionResponses).length === 0) {
+      return;
+    }
+    for (let i = confirmationEventIndex - 1; i >= 0; i--) {
+      const event = events[i];
+      const functionCalls = getFunctionCalls(event);
+      if (!functionCalls) {
+        continue;
+      }
+      const toolsToResumeWithConfirmation = {};
+      const toolsToResumeWithArgs = {};
+      for (const functionCall of functionCalls) {
+        if (!functionCall.id || !(functionCall.id in requestConfirmationFunctionResponses)) {
+          continue;
+        }
+        const args = functionCall.args;
+        if (!args || !("originalFunctionCall" in args)) {
+          continue;
+        }
+        const originalFunctionCall = args["originalFunctionCall"];
+        if (originalFunctionCall.id) {
+          toolsToResumeWithConfirmation[originalFunctionCall.id] = requestConfirmationFunctionResponses[functionCall.id];
+          toolsToResumeWithArgs[originalFunctionCall.id] = originalFunctionCall;
+        }
+      }
+      if (Object.keys(toolsToResumeWithConfirmation).length === 0) {
+        continue;
+      }
+      for (let j = events.length - 1; j > confirmationEventIndex; j--) {
+        const eventToCheck = events[j];
+        const functionResponses = getFunctionResponses(eventToCheck);
+        if (!functionResponses) {
+          continue;
+        }
+        for (const fr of functionResponses) {
+          if (fr.id && fr.id in toolsToResumeWithConfirmation) {
+            delete toolsToResumeWithConfirmation[fr.id];
+            delete toolsToResumeWithArgs[fr.id];
+          }
+        }
+        if (Object.keys(toolsToResumeWithConfirmation).length === 0) {
+          break;
+        }
+      }
+      if (Object.keys(toolsToResumeWithConfirmation).length === 0) {
+        continue;
+      }
+      const toolsList = await agent.canonicalTools(
+        new ReadonlyContext(invocationContext)
+      );
+      const toolsDict = Object.fromEntries(
+        toolsList.map((tool) => [tool.name, tool])
+      );
+      const functionResponseEvent = await handleFunctionCallList({
+        invocationContext,
+        functionCalls: Object.values(toolsToResumeWithArgs),
+        toolsDict,
+        beforeToolCallbacks: agent.canonicalBeforeToolCallbacks,
+        afterToolCallbacks: agent.canonicalAfterToolCallbacks,
+        filters: new Set(Object.keys(toolsToResumeWithConfirmation)),
+        toolConfirmationDict: toolsToResumeWithConfirmation
+      });
+      if (functionResponseEvent) {
+        yield functionResponseEvent;
+      }
+      return;
+    }
+  }
+}
+const REQUEST_CONFIRMATION_LLM_REQUEST_PROCESSOR = new RequestConfirmationLlmRequestProcessor();
+export {
+  REQUEST_CONFIRMATION_LLM_REQUEST_PROCESSOR,
+  RequestConfirmationLlmRequestProcessor
+};

package/dist/esm/agents/readonly_context.js

@@ -20,6 +20,18 @@ class ReadonlyContext {
   get invocationId() {
     return this.invocationContext.invocationId;
   }
+  /**
+   * The user ID of the current session.
+   */
+  get userId() {
+    return this.invocationContext.userId;
+  }
+  /**
+   * The ID of the current session.
+   */
+  get sessionId() {
+    return this.invocationContext.session.id;
+  }
   /**
    * The current agent name.
    */

package/dist/esm/agents/run_config.js

@@ -17,6 +17,7 @@ function createRunConfig(params = {}) {
     enableAffectiveDialog: false,
     streamingMode: "none" /* NONE */,
     maxLlmCalls: validateMaxLlmCalls(params.maxLlmCalls || 500),
+    pauseOnToolCalls: false,
     ...params
   };
 }

package/dist/esm/artifacts/file_artifact_service.js

@@ -0,0 +1,451 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as fs from "fs/promises";
+import * as path from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+import { logger } from "../utils/logger.js";
+const USER_NAMESPACE_PREFIX = "user:";
+class FileArtifactService {
+  constructor(rootDirOrUri) {
+    try {
+      const rootDir = rootDirOrUri.startsWith("file://") ? fileURLToPath(rootDirOrUri) : rootDirOrUri;
+      this.rootDir = path.resolve(rootDir);
+    } catch (e) {
+      throw new Error(`Invalid root directory: ${rootDirOrUri}`, { cause: e });
+    }
+  }
+  async saveArtifact({
+    userId,
+    sessionId,
+    filename,
+    artifact,
+    customMetadata
+  }) {
+    if (!artifact.inlineData && !artifact.text) {
+      throw new Error("Artifact must have either inlineData or text content.");
+    }
+    const artifactDir = getArtifactDir(
+      this.rootDir,
+      userId,
+      sessionId,
+      filename
+    );
+    await fs.mkdir(artifactDir, { recursive: true });
+    const versions = await getArtifactVersionsFromDir(artifactDir);
+    const nextVersion = versions.length > 0 ? versions[versions.length - 1] + 1 : 0;
+    const versionsDir = getVersionsDir(artifactDir);
+    const versionDir = path.join(versionsDir, nextVersion.toString());
+    await fs.mkdir(versionDir, { recursive: true });
+    const storedFilename = path.basename(artifactDir);
+    const contentPath = path.join(versionDir, storedFilename);
+    let mimeType;
+    if (artifact.inlineData) {
+      const data = artifact.inlineData.data || "";
+      await fs.writeFile(contentPath, Buffer.from(data, "base64"));
+      mimeType = artifact.inlineData.mimeType || "application/octet-stream";
+    } else if (artifact.text !== void 0) {
+      await fs.writeFile(contentPath, artifact.text, "utf-8");
+    }
+    const canonicalUri = await getCanonicalUri(
+      this.rootDir,
+      userId,
+      sessionId,
+      filename,
+      nextVersion
+    );
+    const metadata = {
+      fileName: filename,
+      mimeType,
+      version: nextVersion,
+      canonicalUri,
+      customMetadata
+    };
+    await writeMetadata(path.join(versionDir, "metadata.json"), metadata);
+    return nextVersion;
+  }
+  async loadArtifact({
+    userId,
+    sessionId,
+    filename,
+    version
+  }) {
+    try {
+      const artifactDir = getArtifactDir(
+        this.rootDir,
+        userId,
+        sessionId,
+        filename
+      );
+      try {
+        await fs.access(artifactDir);
+      } catch (e) {
+        logger.warn(
+          `[FileArtifactService] loadArtifact: Artifact ${filename} not found`,
+          e
+        );
+        return void 0;
+      }
+      const versions = await getArtifactVersionsFromDir(artifactDir);
+      if (versions.length === 0) {
+        return void 0;
+      }
+      let versionToLoad;
+      if (version === void 0) {
+        versionToLoad = versions[versions.length - 1];
+      } else {
+        if (!versions.includes(version)) {
+          logger.warn(
+            `[FileArtifactService] loadArtifact: Artifact ${filename} version ${version} not found`
+          );
+          return void 0;
+        }
+        versionToLoad = version;
+      }
+      const versionDir = path.join(
+        getVersionsDir(artifactDir),
+        versionToLoad.toString()
+      );
+      const metadataPath = path.join(versionDir, "metadata.json");
+      const metadata = await readMetadata(metadataPath);
+      const storedFilename = path.basename(artifactDir);
+      let contentPath = path.join(versionDir, storedFilename);
+      if (metadata.canonicalUri) {
+        const uriPath = fileUriToPath(metadata.canonicalUri);
+        if (uriPath) {
+          try {
+            await fs.access(uriPath);
+            contentPath = uriPath;
+          } catch {
+            logger.warn(
+              `[FileArtifactService] loadArtifact: Artifact ${filename} missing at ${uriPath}, falling back to content path ${contentPath}`
+            );
+          }
+        }
+      }
+      if (metadata.mimeType) {
+        try {
+          const data = await fs.readFile(contentPath);
+          return {
+            inlineData: {
+              mimeType: metadata.mimeType,
+              data: data.toString("base64")
+            }
+          };
+        } catch {
+          logger.warn(
+            `[FileArtifactService] loadArtifact: Artifact ${filename} missing at ${contentPath}`
+          );
+          return void 0;
+        }
+      }
+      try {
+        const text = await fs.readFile(contentPath, "utf-8");
+        return { text };
+      } catch {
+        logger.warn(
+          `[FileArtifactService] loadArtifact: Text artifact ${filename} missing at ${contentPath}`
+        );
+        return void 0;
+      }
+    } catch (e) {
+      logger.error(
+        `[FileArtifactService] loadArtifact: Error loading artifact ${filename}`,
+        e
+      );
+      return void 0;
+    }
+  }
+  async listArtifactKeys({
+    userId,
+    sessionId
+  }) {
+    const filenames = /* @__PURE__ */ new Set();
+    const userRoot = getUserRoot(this.rootDir, userId);
+    const sessionRoot = getSessionArtifactsDir(userRoot, sessionId);
+    for await (const artifactDir of iterateArtifactDirs(sessionRoot)) {
+      const metadata = await getLatestMetadata(artifactDir);
+      if (metadata == null ? void 0 : metadata.fileName) {
+        filenames.add(metadata.fileName);
+      } else {
+        const rel = path.relative(sessionRoot, artifactDir);
+        filenames.add(asPosixPath(rel));
+      }
+    }
+    const artifactsRoot = getUserArtifactsDir(userRoot);
+    for await (const artifactDir of iterateArtifactDirs(artifactsRoot)) {
+      const metadata = await getLatestMetadata(artifactDir);
+      if (metadata == null ? void 0 : metadata.fileName) {
+        filenames.add(metadata.fileName);
+      } else {
+        const rel = path.relative(artifactsRoot, artifactDir);
+        filenames.add(`${USER_NAMESPACE_PREFIX}${asPosixPath(rel)}`);
+      }
+    }
+    return Array.from(filenames).sort();
+  }
+  async deleteArtifact({
+    userId,
+    sessionId,
+    filename
+  }) {
+    try {
+      const artifactDir = getArtifactDir(
+        this.rootDir,
+        userId,
+        sessionId,
+        filename
+      );
+      await fs.rm(artifactDir, { recursive: true, force: true });
+    } catch (e) {
+      logger.warn(
+        `[FileArtifactService] deleteArtifact: Failed to delete artifact ${filename}`,
+        e
+      );
+    }
+  }
+  async listVersions({
+    userId,
+    sessionId,
+    filename
+  }) {
+    try {
+      const artifactDir = getArtifactDir(
+        this.rootDir,
+        userId,
+        sessionId,
+        filename
+      );
+      return await getArtifactVersionsFromDir(artifactDir);
+    } catch (e) {
+      logger.warn(
+        `[FileArtifactService] listVersions: Failed to list versions for artifact ${filename}`,
+        e
+      );
+      return [];
+    }
+  }
+  async listArtifactVersions({
+    userId,
+    sessionId,
+    filename
+  }) {
+    try {
+      const artifactDir = getArtifactDir(
+        this.rootDir,
+        userId,
+        sessionId,
+        filename
+      );
+      const versions = await getArtifactVersionsFromDir(artifactDir);
+      const artifactVersions = [];
+      for (const version of versions) {
+        const metadataPath = path.join(
+          getVersionsDir(artifactDir),
+          version.toString(),
+          "metadata.json"
+        );
+        try {
+          const metadata = await readMetadata(metadataPath);
+          artifactVersions.push(metadata);
+        } catch (e) {
+          logger.warn(
+            `[FileArtifactService] listArtifactVersions: Failed to read artifact version ${version} at ${artifactDir}`,
+            e
+          );
+        }
+      }
+      return artifactVersions;
+    } catch (e) {
+      logger.warn(
+        `[FileArtifactService] listArtifactVersions: Failed to list artifact versions for userId: ${userId} sessionId: ${sessionId} filename: ${filename}`,
+        e
+      );
+      return [];
+    }
+  }
+  async getArtifactVersion({
+    userId,
+    sessionId,
+    filename,
+    version
+  }) {
+    try {
+      const artifactDir = getArtifactDir(
+        this.rootDir,
+        userId,
+        sessionId,
+        filename
+      );
+      const versions = await getArtifactVersionsFromDir(artifactDir);
+      if (versions.length === 0) {
+        return void 0;
+      }
+      let versionToRead;
+      if (version === void 0) {
+        versionToRead = versions[versions.length - 1];
+      } else {
+        if (!versions.includes(version)) {
+          return void 0;
+        }
+        versionToRead = version;
+      }
+      const metadataPath = path.join(
+        getVersionsDir(artifactDir),
+        versionToRead.toString(),
+        "metadata.json"
+      );
+      return await readMetadata(metadataPath);
+    } catch (e) {
+      logger.warn(
+        `[FileArtifactService] getArtifactVersion: Failed to get artifact version for userId: ${userId} sessionId: ${sessionId} filename: ${filename} version: ${version}`,
+        e
+      );
+      return void 0;
+    }
+  }
+}
+function getUserRoot(rootDir, userId) {
+  return path.join(rootDir, "users", userId);
+}
+function isUserScoped(sessionId, filename) {
+  return !sessionId || filename.startsWith(USER_NAMESPACE_PREFIX);
+}
+function getUserArtifactsDir(userRoot) {
+  return path.join(userRoot, "artifacts");
+}
+function getSessionArtifactsDir(baseRoot, sessionId) {
+  return path.join(baseRoot, "sessions", sessionId, "artifacts");
+}
+function getVersionsDir(artifactDir) {
+  return path.join(artifactDir, "versions");
+}
+function getArtifactDir(rootDir, userId, sessionId, filename) {
+  const userRoot = getUserRoot(rootDir, userId);
+  let scopeRoot;
+  if (isUserScoped(sessionId, filename)) {
+    scopeRoot = getUserArtifactsDir(userRoot);
+  } else {
+    if (!sessionId) {
+      throw new Error(
+        "Session ID must be provided for session-scoped artifacts."
+      );
+    }
+    scopeRoot = getSessionArtifactsDir(userRoot, sessionId);
+  }
+  let cleanFilename = filename;
+  if (cleanFilename.startsWith(USER_NAMESPACE_PREFIX)) {
+    cleanFilename = cleanFilename.substring(USER_NAMESPACE_PREFIX.length);
+  }
+  cleanFilename = cleanFilename.trim();
+  if (path.isAbsolute(cleanFilename)) {
+    throw new Error(`Absolute artifact filename ${filename} is not permitted.`);
+  }
+  const artifactDir = path.resolve(scopeRoot, cleanFilename);
+  const relative = path.relative(scopeRoot, artifactDir);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`Artifact filename ${filename} escapes storage directory.`);
+  }
+  if (relative === "" || relative === ".") {
+    return path.join(scopeRoot, "artifact");
+  }
+  return artifactDir;
+}
+async function getArtifactVersionsFromDir(artifactDir) {
+  const versionsDir = getVersionsDir(artifactDir);
+  try {
+    const files = await fs.readdir(versionsDir, { withFileTypes: true });
+    const versions = files.filter((dirent) => dirent.isDirectory()).map((dirent) => parseInt(dirent.name, 10)).filter((v) => !isNaN(v));
+    return versions.sort((a, b) => a - b);
+  } catch (e) {
+    logger.warn(
+      `[FileArtifactService] getArtifactVersionsFromDir: Failed to list artifact versions from ${artifactDir}`,
+      e
+    );
+    return [];
+  }
+}
+async function getCanonicalUri(rootDir, userId, sessionId, filename, version) {
+  const artifactDir = await getArtifactDir(
+    rootDir,
+    userId,
+    sessionId,
+    filename
+  );
+  const storedFilename = path.basename(artifactDir);
+  const versionsDir = getVersionsDir(artifactDir);
+  const payloadPath = path.join(
+    versionsDir,
+    version.toString(),
+    storedFilename
+  );
+  return pathToFileURL(payloadPath).toString();
+}
+async function writeMetadata(metadataPath, metadata) {
+  await fs.writeFile(metadataPath, JSON.stringify(metadata, null, 2), "utf-8");
+}
+async function readMetadata(metadataPath) {
+  const content = await fs.readFile(metadataPath, "utf-8");
+  return JSON.parse(content);
+}
+async function getLatestMetadata(artifactDir) {
+  const versions = await getArtifactVersionsFromDir(artifactDir);
+  if (versions.length === 0) {
+    return void 0;
+  }
+  const latestVersion = versions[versions.length - 1];
+  const metadataPath = path.join(
+    getVersionsDir(artifactDir),
+    latestVersion.toString(),
+    "metadata.json"
+  );
+  try {
+    return await readMetadata(metadataPath);
+  } catch (e) {
+    logger.warn(
+      `[FileArtifactService] getLatestMetadata: Failed to read metadata from ${metadataPath}`,
+      e
+    );
+    return void 0;
+  }
+}
+async function* iterateArtifactDirs(dir) {
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    const hasVersions = entries.some(
+      (e) => e.isDirectory() && e.name === "versions"
+    );
+    if (hasVersions) {
+      yield dir;
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const subdir = path.join(dir, entry.name);
+        for await (const foundDir of iterateArtifactDirs(subdir)) {
+          yield foundDir;
+        }
+      }
+    }
+  } catch (_e) {
+  }
+}
+function fileUriToPath(uri) {
+  try {
+    return fileURLToPath(uri);
+  } catch (e) {
+    logger.warn(
+      `[FileArtifactService] fileUriToPath: Failed to convert file URI to path: ${uri}`,
+      e
+    );
+    return void 0;
+  }
+}
+function asPosixPath(p) {
+  return p.split(path.sep).join("/");
+}
+export {
+  FileArtifactService
+};