@google/adk 0.3.0 → 0.4.0

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
+};

package/dist/esm/artifacts/gcs_artifact_service.js

@@ -5,11 +5,15 @@
  */
 import { Storage } from "@google-cloud/storage";
 import { createPartFromBase64, createPartFromText } from "@google/genai";
+import { logger } from "../utils/logger.js";
 class GcsArtifactService {
   constructor(bucket) {
     this.bucket = new Storage().bucket(bucket);
   }
   async saveArtifact(request) {
+    if (!request.artifact.inlineData && !request.artifact.text) {
+      throw new Error("Artifact must have either inlineData or text content.");
+    }
     const versions = await this.listVersions(request);
     const version = versions.length > 0 ? Math.max(...versions) + 1 : 0;
     const file = this.bucket.file(
@@ -18,62 +22,69 @@ class GcsArtifactService {
         version
       })
     );
+    const metadata = request.customMetadata || {};
     if (request.artifact.inlineData) {
-      await file.save(JSON.stringify(request.artifact.inlineData.data), {
-        contentType: request.artifact.inlineData.mimeType
-      });
-      return version;
-    }
-    if (request.artifact.text) {
-      await file.save(request.artifact.text, {
-        contentType: "text/plain"
-      });
+      await file.save(
+        Buffer.from(request.artifact.inlineData.data || "", "base64"),
+        {
+          contentType: request.artifact.inlineData.mimeType,
+          metadata
+        }
+      );
       return version;
     }
-    throw new Error("Artifact must have either inlineData or text.");
+    await file.save(request.artifact.text, {
+      contentType: "text/plain",
+      metadata
+    });
+    return version;
   }
   async loadArtifact(request) {
-    let version = request.version;
-    if (version === void 0) {
-      const versions = await this.listVersions(request);
-      if (versions.length === 0) {
-        return void 0;
+    try {
+      let version = request.version;
+      if (version === void 0) {
+        const versions = await this.listVersions(request);
+        if (versions.length === 0) {
+          return void 0;
+        }
+        version = Math.max(...versions);
       }
-      version = Math.max(...versions);
-    }
-    const file = this.bucket.file(
-      getFileName({
-        ...request,
-        version
-      })
-    );
-    const [[metadata], [rawDataBuffer]] = await Promise.all([
-      file.getMetadata(),
-      file.download()
-    ]);
-    if (metadata.contentType === "text/plain") {
-      return createPartFromText(rawDataBuffer.toString("utf-8"));
+      const file = this.bucket.file(
+        getFileName({
+          ...request,
+          version
+        })
+      );
+      const [[metadata], [rawDataBuffer]] = await Promise.all([
+        file.getMetadata(),
+        file.download()
+      ]);
+      if (metadata.contentType === "text/plain") {
+        return createPartFromText(rawDataBuffer.toString("utf-8"));
+      }
+      return createPartFromBase64(
+        rawDataBuffer.toString("base64"),
+        metadata.contentType
+      );
+    } catch (e) {
+      logger.warn(
+        `[GcsArtifactService] loadArtifact: Failed to load artifact ${request.filename}`,
+        e
+      );
+      return void 0;
     }
-    return createPartFromBase64(
-      rawDataBuffer.toString("base64"),
-      metadata.contentType
-    );
   }
   async listArtifactKeys(request) {
-    const fileNames = [];
     const sessionPrefix = `${request.appName}/${request.userId}/${request.sessionId}/`;
     const usernamePrefix = `${request.appName}/${request.userId}/user/`;
     const [[sessionFiles], [userSessionFiles]] = await Promise.all([
       this.bucket.getFiles({ prefix: sessionPrefix }),
       this.bucket.getFiles({ prefix: usernamePrefix })
     ]);
-    for (const file of sessionFiles) {
-      fileNames.push(file.name.split("/").pop());
-    }
-    for (const file of userSessionFiles) {
-      fileNames.push(file.name.split("/").pop());
-    }
-    return fileNames.sort((a, b) => a.localeCompare(b));
+    return [
+      ...extractArtifactKeys(sessionFiles, sessionPrefix),
+      ...extractArtifactKeys(userSessionFiles, usernamePrefix, "user:")
+    ].sort((a, b) => a.localeCompare(b));
   }
   async deleteArtifact(request) {
     const versions = await this.listVersions(request);
@@ -92,13 +103,62 @@ class GcsArtifactService {
   }
   async listVersions(request) {
     const prefix = getFileName(request);
-    const [files] = await this.bucket.getFiles({ prefix });
+    const searchPrefix = prefix + "/";
+    const [files] = await this.bucket.getFiles({ prefix: searchPrefix });
     const versions = [];
     for (const file of files) {
       const version = file.name.split("/").pop();
-      versions.push(parseInt(version, 10));
+      const v = parseInt(version, 10);
+      if (!isNaN(v)) {
+        versions.push(v);
+      }
+    }
+    return versions.sort((a, b) => a - b);
+  }
+  async listArtifactVersions(request) {
+    const versions = await this.listVersions(request);
+    const artifactVersions = [];
+    for (const version of versions) {
+      const artifactVersion = await this.getArtifactVersion({
+        ...request,
+        version
+      });
+      if (artifactVersion) {
+        artifactVersions.push(artifactVersion);
+      }
+    }
+    return artifactVersions;
+  }
+  async getArtifactVersion(request) {
+    try {
+      let version = request.version;
+      if (version === void 0) {
+        const versions = await this.listVersions(request);
+        if (versions.length === 0) {
+          return void 0;
+        }
+        version = Math.max(...versions);
+      }
+      const file = this.bucket.file(
+        getFileName({
+          ...request,
+          version
+        })
+      );
+      const [metadata] = await file.getMetadata();
+      return {
+        version,
+        mimeType: metadata.contentType,
+        customMetadata: metadata.metadata,
+        canonicalUri: file.publicUrl()
+      };
+    } catch (e) {
+      logger.warn(
+        `[GcsArtifactService] getArtifactVersion: Failed to get artifact version for userId: ${request.userId} sessionId: ${request.sessionId} filename: ${request.filename} version: ${request.version}`,
+        e
+      );
+      return void 0;
     }
-    return versions;
   }
 }
 function getFileName({
@@ -108,10 +168,29 @@ function getFileName({
   filename,
   version
 }) {
-  if (filename.startsWith("user:")) {
-    return `${appName}/${userId}/user/${filename}/${version}`;
+  const isUser = filename.startsWith("user:");
+  const cleanFilename = isUser ? filename.substring(5) : filename;
+  const prefix = isUser ? `${appName}/${userId}/user/${cleanFilename}` : `${appName}/${userId}/${sessionId}/${cleanFilename}`;
+  return version !== void 0 ? `${prefix}/${version}` : prefix;
+}
+function extractArtifactKeys(files, fileNamePrefix, keyPrefix = "") {
+  const keys = /* @__PURE__ */ new Set();
+  for (const file of files) {
+    if (!file.name.startsWith(fileNamePrefix)) {
+      continue;
+    }
+    const relative = file.name.substring(fileNamePrefix.length);
+    const name = getFileNameFromPath(relative);
+    keys.add(`${keyPrefix}${name}`);
+  }
+  return [...keys];
+}
+function getFileNameFromPath(filePath) {
+  const parts = filePath.split("/");
+  if (parts.length < 2) {
+    return filePath;
   }
-  return `${appName}/${userId}/${sessionId}/${filename}/${version}`;
+  return parts.slice(0, -1).join("/");
 }
 export {
   GcsArtifactService