@softactivate/adk 1.1.0

package/dist/web/artifacts/file_artifact_service.js

@@ -0,0 +1,535 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : Symbol.for("Symbol." + name);
+var __await = function(promise, isYieldStar) {
+  this[0] = promise;
+  this[1] = isYieldStar;
+};
+var __asyncGenerator = (__this, __arguments, generator) => {
+  var resume = (k, v, yes, no) => {
+    try {
+      var x = generator[k](v), isAwait = (v = x.value) instanceof __await, done = x.done;
+      Promise.resolve(isAwait ? v[0] : v).then((y) => isAwait ? resume(k === "return" ? k : "next", v[1] ? { done: y.done, value: y.value } : y, yes, no) : yes({ value: y, done })).catch((e) => resume("throw", e, yes, no));
+    } catch (e) {
+      no(e);
+    }
+  }, method = (k) => it[k] = (x) => new Promise((yes, no) => resume(k, x, yes, no)), it = {};
+  return generator = generator.apply(__this, __arguments), it[__knownSymbol("asyncIterator")] = () => it, method("next"), method("throw"), method("return"), it;
+};
+var __forAwait = (obj, it, method) => (it = obj[__knownSymbol("asyncIterator")]) ? it.call(obj) : (obj = obj[__knownSymbol("iterator")](), it = {}, method = (key, fn) => (fn = obj[key]) && (it[key] = (arg) => new Promise((yes, no, done) => (arg = fn.call(obj, arg), done = arg.done, Promise.resolve(arg.value).then((value) => yes({ value, done }), no)))), method("next"), method("return"), it);
+/**
+ * @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: ".concat(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 ".concat(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 ".concat(filename, " version ").concat(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 (e) {
+            logger.warn(
+              "[FileArtifactService] loadArtifact: Artifact ".concat(filename, " missing at ").concat(uriPath, ", falling back to content path ").concat(contentPath)
+            );
+          }
+        }
+      }
+      if (metadata.mimeType) {
+        try {
+          const data = await fs.readFile(contentPath);
+          return {
+            inlineData: {
+              mimeType: metadata.mimeType,
+              data: data.toString("base64")
+            }
+          };
+        } catch (e) {
+          logger.warn(
+            "[FileArtifactService] loadArtifact: Artifact ".concat(filename, " missing at ").concat(contentPath)
+          );
+          return void 0;
+        }
+      }
+      try {
+        const text = await fs.readFile(contentPath, "utf-8");
+        return { text };
+      } catch (e) {
+        logger.warn(
+          "[FileArtifactService] loadArtifact: Text artifact ".concat(filename, " missing at ").concat(contentPath)
+        );
+        return void 0;
+      }
+    } catch (e) {
+      logger.error(
+        "[FileArtifactService] loadArtifact: Error loading artifact ".concat(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);
+    try {
+      for (var iter = __forAwait(iterateArtifactDirs(sessionRoot)), more, temp, error; more = !(temp = await iter.next()).done; more = false) {
+        const artifactDir = temp.value;
+        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));
+        }
+      }
+    } catch (temp) {
+      error = [temp];
+    } finally {
+      try {
+        more && (temp = iter.return) && await temp.call(iter);
+      } finally {
+        if (error)
+          throw error[0];
+      }
+    }
+    const artifactsRoot = getUserArtifactsDir(userRoot);
+    try {
+      for (var iter2 = __forAwait(iterateArtifactDirs(artifactsRoot)), more2, temp2, error2; more2 = !(temp2 = await iter2.next()).done; more2 = false) {
+        const artifactDir = temp2.value;
+        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("".concat(USER_NAMESPACE_PREFIX).concat(asPosixPath(rel)));
+        }
+      }
+    } catch (temp2) {
+      error2 = [temp2];
+    } finally {
+      try {
+        more2 && (temp2 = iter2.return) && await temp2.call(iter2);
+      } finally {
+        if (error2)
+          throw error2[0];
+      }
+    }
+    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 ".concat(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 ".concat(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 ".concat(version, " at ").concat(artifactDir),
+            e
+          );
+        }
+      }
+      return artifactVersions;
+    } catch (e) {
+      logger.warn(
+        "[FileArtifactService] listArtifactVersions: Failed to list artifact versions for userId: ".concat(userId, " sessionId: ").concat(sessionId, " filename: ").concat(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: ".concat(userId, " sessionId: ").concat(sessionId, " filename: ").concat(filename, " version: ").concat(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 ".concat(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] ".concat(label, " escapes storage root. Resolved: ").concat(resolved, ", Root: ").concat(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 ".concat(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 ".concat(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 ".concat(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 ".concat(metadataPath),
+      e
+    );
+    return void 0;
+  }
+}
+function iterateArtifactDirs(dir) {
+  return __asyncGenerator(this, null, function* () {
+    try {
+      const entries = yield new __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);
+          try {
+            for (var iter = __forAwait(iterateArtifactDirs(subdir)), more, temp, error; more = !(temp = yield new __await(iter.next())).done; more = false) {
+              const foundDir = temp.value;
+              yield foundDir;
+            }
+          } catch (temp) {
+            error = [temp];
+          } finally {
+            try {
+              more && (temp = iter.return) && (yield new __await(temp.call(iter)));
+            } finally {
+              if (error)
+                throw error[0];
+            }
+          }
+        }
+      }
+    } catch (_e) {
+    }
+  });
+}
+function fileUriToPath(uri) {
+  try {
+    return fileURLToPath(uri);
+  } catch (e) {
+    logger.warn(
+      "[FileArtifactService] fileUriToPath: Failed to convert file URI to path: ".concat(uri),
+      e
+    );
+    return void 0;
+  }
+}
+function asPosixPath(p) {
+  return p.split(path.sep).join("/");
+}
+export {
+  FileArtifactService,
+  assertInsideRoot,
+  assertSafeSegment,
+  getSessionArtifactsDir,
+  getUserRoot
+};