local artifact handler (#15)

### What changes were proposed in this pull request?
Introduces a new `FileArtifact` class for handling file-based storage operations. The class provides methods for saving, loading, deleting, and listing JSON files in a specified directory. Additionally, adds a new `ArtifactUploadResponse` interface to standardize storage operation responses.

### Why are the changes needed?
To provide a local file storage implementation for artifacts, enabling persistent data storage and retrieval through a consistent interface. This allows for local development and testing without requiring external storage services.

### Does this PR introduce _any_ user-facing change?
Yes. This PR introduces new file storage capabilities that developers can use to persist and retrieve data locally. The `FileArtifact` class provides a simple API for file operations with JSON data.

### How was this patch tested?
The implementation includes error handling and directory existence checks. Additional unit tests should be added to verify:
- File creation and deletion
- JSON data persistence and retrieval
- Directory creation
- Error handling for invalid operations
- List functionality for stored files

Author: JerryPan2718

core/artifacts/fileArtifact.ts

@@ -0,0 +1,91 @@
+import fs from "fs";
+import path from "path";
+import { BaseArtifact } from "./baseArtifact";
+import { ArtifactUploadResponse, GameEnvironment } from "../types";
+
+export class FileArtifact extends BaseArtifact {
+  private baseDir: string;
+
+  constructor(baseDir: string = "agent_data") {
+    super("FileArtifact", "Handles file-based storage operations", "storage");
+    this.baseDir = baseDir;
+    this.ensureDirectoryExists(baseDir);
+  }
+
+  private ensureDirectoryExists(dir: string): void {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+  }
+
+  private getFilePath(filename: string): string {
+    return path.join(this.baseDir, filename);
+  }
+
+  async save(
+    data: Record<string, unknown>,
+    filename: string,
+  ): Promise<ArtifactUploadResponse> {
+    try {
+      const filePath = this.getFilePath(filename);
+      const jsonData = JSON.stringify(data, null, 2);
+      fs.writeFileSync(filePath, jsonData, "utf8");
+
+      return {
+        success: true,
+        url: filePath,
+        error: null,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        url: null,
+        error:
+          error instanceof Error ? error.message : "Unknown error occurred",
+      };
+    }
+  }
+
+  async load(filename: string): Promise<Record<string, unknown>> {
+    try {
+      const filePath = this.getFilePath(filename);
+      if (!fs.existsSync(filePath)) {
+        throw new Error(`File not found: ${filePath}`);
+      }
+
+      const data = fs.readFileSync(filePath, "utf8");
+      return JSON.parse(data);
+    } catch (error) {
+      throw new Error(
+        `Failed to load file: ${error instanceof Error ? error.message : "Unknown error"}`,
+      );
+    }
+  }
+
+  async delete(filename: string): Promise<boolean> {
+    try {
+      const filePath = this.getFilePath(filename);
+      if (fs.existsSync(filePath)) {
+        fs.unlinkSync(filePath);
+        return true;
+      }
+      return false;
+    } catch {
+      return false;
+    }
+  }
+
+  async list(): Promise<string[]> {
+    try {
+      return fs.readdirSync(this.baseDir);
+    } catch {
+      return [];
+    }
+  }
+
+  async modifyEnvironment(environment: GameEnvironment): Promise<void> {
+    // Default implementation - no environment modifications needed for file storage
+    console.log("FileArtifact: modifyEnvironment called", environment);
+    return Promise.resolve();
+  }
+}

core/types.ts

@@ -20,3 +20,9 @@ export interface GameEnvironment {
     entities: Record<string, unknown>;
   };
 }
+
+export interface ArtifactUploadResponse {
+  success: boolean;
+  url: string | null;
+  error: string | null;
+}

package.json

@@ -18,7 +18,8 @@
     "typescript": "^5.0.0",
     "@google-ai/generativelanguage": "^1.1.0",
     "google-auth-library": "^9.0.0",
-    "mongodb": "^6.3.0"
+    "mongodb": "^6.3.0",
+    "@types/node": "^latest_version"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",