@softactivate/adk 1.1.0

package/dist/cjs/artifacts/file_artifact_service.js

@@ -0,0 +1,522 @@
+/**
+  * @license
+  * Copyright 2026 Google LLC
+  * SPDX-License-Identifier: Apache-2.0
+  */
+
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var file_artifact_service_exports = {};
+__export(file_artifact_service_exports, {
+  FileArtifactService: () => FileArtifactService,
+  assertInsideRoot: () => assertInsideRoot,
+  assertSafeSegment: () => assertSafeSegment,
+  getSessionArtifactsDir: () => getSessionArtifactsDir,
+  getUserRoot: () => getUserRoot
+});
+module.exports = __toCommonJS(file_artifact_service_exports);
+var fs = __toESM(require("fs/promises"), 1);
+var path = __toESM(require("path"), 1);
+var import_url = require("url");
+var import_logger = require("../utils/logger.js");
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const USER_NAMESPACE_PREFIX = "user:";
+class FileArtifactService {
+  constructor(rootDirOrUri) {
+    try {
+      const rootDir = rootDirOrUri.startsWith("file://") ? (0, import_url.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) {
+        import_logger.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)) {
+          import_logger.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 {
+            import_logger.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 {
+          import_logger.logger.warn(
+            `[FileArtifactService] loadArtifact: Artifact ${filename} missing at ${contentPath}`
+          );
+          return void 0;
+        }
+      }
+      try {
+        const text = await fs.readFile(contentPath, "utf-8");
+        return { text };
+      } catch {
+        import_logger.logger.warn(
+          `[FileArtifactService] loadArtifact: Text artifact ${filename} missing at ${contentPath}`
+        );
+        return void 0;
+      }
+    } catch (e) {
+      import_logger.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) {
+      import_logger.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) {
+      import_logger.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) {
+          import_logger.logger.warn(
+            `[FileArtifactService] listArtifactVersions: Failed to read artifact version ${version} at ${artifactDir}`,
+            e
+          );
+        }
+      }
+      return artifactVersions;
+    } catch (e) {
+      import_logger.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) {
+      import_logger.logger.warn(
+        `[FileArtifactService] getArtifactVersion: Failed to get artifact version for userId: ${userId} sessionId: ${sessionId} filename: ${filename} version: ${version}`,
+        e
+      );
+      return void 0;
+    }
+  }
+}
+const SAFE_SEGMENT_RE = /^[a-zA-Z0-9_@-][a-zA-Z0-9_.@-]{0,255}$/;
+function assertSafeSegment(value, label) {
+  if (!value || !SAFE_SEGMENT_RE.test(value)) {
+    throw new Error(
+      `[FileArtifactService] Invalid ${label}: value contains disallowed characters.`
+    );
+  }
+}
+function assertInsideRoot(resolvedPath, rootDir, label) {
+  const root = path.resolve(rootDir);
+  const resolved = path.resolve(resolvedPath);
+  if (!resolved.startsWith(root + path.sep) && resolved !== root) {
+    throw new Error(
+      `[FileArtifactService] ${label} escapes storage root. Resolved: ${resolved}, Root: ${root}`
+    );
+  }
+}
+function getUserRoot(rootDir, userId) {
+  assertSafeSegment(userId, "userId");
+  const result = path.join(rootDir, "users", userId);
+  assertInsideRoot(result, rootDir, "userRoot");
+  return result;
+}
+function isUserScoped(sessionId, filename) {
+  return !sessionId || filename.startsWith(USER_NAMESPACE_PREFIX);
+}
+function getUserArtifactsDir(userRoot) {
+  return path.join(userRoot, "artifacts");
+}
+function getSessionArtifactsDir(baseRoot, sessionId) {
+  assertSafeSegment(sessionId, "sessionId");
+  const result = path.join(baseRoot, "sessions", sessionId, "artifacts");
+  assertInsideRoot(result, baseRoot, "sessionArtifactsDir");
+  return result;
+}
+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) {
+    import_logger.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 (0, import_url.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) {
+    import_logger.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 (0, import_url.fileURLToPath)(uri);
+  } catch (e) {
+    import_logger.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("/");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FileArtifactService,
+  assertInsideRoot,
+  assertSafeSegment,
+  getSessionArtifactsDir,
+  getUserRoot
+});