@elizaos/plugin-local-storage 2.0.0-beta.1

package/README.md

@@ -0,0 +1,44 @@
+# @elizaos/plugin-local-storage
+
+Local filesystem attachment storage for Eliza agents. This is the default
+fallback storage backend used when Eliza Cloud storage is not connected.
+
+The plugin registers a `Service` under `ServiceType.REMOTE_FILES` so consumers
+that previously read from `runtime.getService(ServiceType.REMOTE_FILES)` keep
+working without code changes after the deprecated `@elizaos/plugin-s3-storage`
+package was removed.
+
+## Storage root
+
+The root directory is resolved in this order:
+
+1. `runtime.getSetting("LOCAL_STORAGE_PATH")`
+2. `process.env.LOCAL_STORAGE_PATH`
+3. `${ELIZA_STATE_DIR ?? `${os.homedir()}/.eliza`}/attachments`
+
+The directory is created on `start()` if missing.
+
+## Surface
+
+`LocalFileStorageService` exposes the same method names as the removed
+`AwsS3Service` so call sites can be retargeted with no refactor:
+
+- `uploadFile(filePath, subDirectory?)`
+- `uploadBytes(data, fileName, contentType, subDirectory?)`
+- `uploadJson(jsonData, fileName?, subDirectory?)`
+- `downloadBytes(_unusedBucket, key)`
+- `downloadFile(_unusedBucket, key, localPath)`
+- `delete(_unusedBucket, key)`
+- `exists(_unusedBucket, key)`
+- `generateSignedUrl(fileName, _expiresIn?)` — returns a `file://` absolute path
+
+`_unusedBucket` parameters exist purely for drop-in API compatibility with
+the previous S3 service. They are ignored — keys always resolve under the
+configured storage root.
+
+## Migration from `@elizaos/plugin-s3-storage`
+
+To migrate from a self-hosted S3 bucket:
+
+- Point Eliza Cloud at it via the R2-compatible bucket UI, or
+- Copy attachments to the local storage root and run with this plugin.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./src/index.js";
+export { default } from "./src/index.js";

package/dist/index.js

@@ -0,0 +1,162 @@
+// src/services/local-storage.ts
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { Storage } from "@brighter/storage-adapter-local";
+import {
+  logger,
+  resolveStateDir,
+  Service,
+  ServiceType
+} from "@elizaos/core";
+function resolveStorageRoot(runtime) {
+  const fromRuntime = runtime.getSetting("LOCAL_STORAGE_PATH");
+  if (typeof fromRuntime === "string" && fromRuntime.length > 0) {
+    return path.resolve(fromRuntime);
+  }
+  const fromEnv = process.env.LOCAL_STORAGE_PATH;
+  if (typeof fromEnv === "string" && fromEnv.length > 0) {
+    return path.resolve(fromEnv);
+  }
+  return path.join(resolveStateDir(), "attachments");
+}
+function joinKey(...segments) {
+  const joined = segments.filter((s) => typeof s === "string" && s.length > 0).join("/");
+  return joined.replace(/\/+/g, "/").replace(/^\/+/, "");
+}
+
+class LocalFileStorageService extends Service {
+  static serviceType = ServiceType.REMOTE_FILES;
+  capabilityDescription = "Local filesystem attachment storage";
+  storage = null;
+  storageRoot = "";
+  static async start(runtime) {
+    logger.log("Initializing LocalFileStorageService");
+    const service = new LocalFileStorageService(runtime);
+    await service.initialize(runtime);
+    return service;
+  }
+  static async stop(runtime) {
+    const service = runtime.getService(ServiceType.REMOTE_FILES);
+    if (service) {
+      await service.stop();
+    }
+  }
+  async stop() {
+    this.storage = null;
+  }
+  get root() {
+    return this.storageRoot;
+  }
+  async initialize(runtime) {
+    this.storageRoot = resolveStorageRoot(runtime);
+    await fsp.mkdir(this.storageRoot, { recursive: true });
+    this.storage = Storage({ path: this.storageRoot });
+  }
+  getStorage() {
+    if (!this.storage) {
+      throw new Error("LocalFileStorageService not initialized");
+    }
+    return this.storage;
+  }
+  absolutePath(key) {
+    return path.join(this.storageRoot, key);
+  }
+  fileUrl(key) {
+    return `file://${this.absolutePath(key)}`;
+  }
+  async uploadFile(filePath, subDirectory) {
+    const storage = this.getStorage();
+    const baseFileName = `${Date.now()}-${path.basename(filePath)}`;
+    const key = joinKey(subDirectory, baseFileName);
+    const buffer = await fsp.readFile(filePath);
+    await storage.write(key, buffer, { encoding: "binary" });
+    return { success: true, url: this.fileUrl(key) };
+  }
+  async uploadBytes(data, fileName, contentType, subDirectory) {
+    const storage = this.getStorage();
+    const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data);
+    const key = joinKey(subDirectory, fileName);
+    await storage.write(key, buffer, { encoding: "binary" });
+    return { success: true, url: this.fileUrl(key) };
+  }
+  async uploadJson(jsonData, fileName, subDirectory) {
+    if (!jsonData) {
+      return { success: false, error: "JSON data is required" };
+    }
+    const storage = this.getStorage();
+    const actualFileName = fileName ?? `${Date.now()}.json`;
+    const key = joinKey(subDirectory, actualFileName);
+    const body = JSON.stringify(jsonData, null, 2);
+    await storage.write(key, body, { encoding: "utf8" });
+    return { success: true, key, url: this.fileUrl(key) };
+  }
+  async downloadBytes(_unusedBucket, key) {
+    const storage = this.getStorage();
+    const result = await storage.read(key, { encoding: "binary" });
+    if (result === undefined) {
+      throw new Error(`Object not found: ${key}`);
+    }
+    if (typeof result === "string") {
+      return Buffer.from(result, "binary");
+    }
+    return result;
+  }
+  async downloadFile(_unusedBucket, key, localPath) {
+    const buffer = await this.downloadBytes(_unusedBucket, key);
+    await fsp.writeFile(localPath, buffer);
+  }
+  async delete(_unusedBucket, key) {
+    const storage = this.getStorage();
+    await storage.remove(key);
+  }
+  async exists(_unusedBucket, key) {
+    const storage = this.getStorage();
+    return storage.exists(key);
+  }
+  async generateSignedUrl(fileName, _expiresIn) {
+    return this.fileUrl(fileName);
+  }
+}
+
+// src/types.ts
+var CONTENT_TYPES = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".pdf": "application/pdf",
+  ".json": "application/json",
+  ".txt": "text/plain",
+  ".html": "text/html",
+  ".css": "text/css",
+  ".js": "application/javascript",
+  ".mp3": "audio/mpeg",
+  ".mp4": "video/mp4",
+  ".wav": "audio/wav",
+  ".webm": "video/webm"
+};
+function getContentType(filePath) {
+  const dot = filePath.lastIndexOf(".");
+  if (dot === -1)
+    return "application/octet-stream";
+  const ext = filePath.substring(dot).toLowerCase();
+  return CONTENT_TYPES[ext] ?? "application/octet-stream";
+}
+// src/index.ts
+var localStoragePlugin = {
+  name: "local-storage",
+  description: "Local filesystem attachment storage (default fallback when Eliza Cloud storage is not connected)",
+  services: [LocalFileStorageService],
+  actions: []
+};
+var src_default = localStoragePlugin;
+export {
+  localStoragePlugin,
+  getContentType,
+  src_default as default,
+  LocalFileStorageService,
+  CONTENT_TYPES
+};
+
+//# debugId=B7B5210279BE486A64756E2164756E21

package/dist/index.js.map

@@ -0,0 +1,12 @@
+{
+  "version": 3,
+  "sources": ["../src/services/local-storage.ts", "../src/types.ts", "../src/index.ts"],
+  "sourcesContent": [
+    "import { promises as fsp } from \"node:fs\";\nimport path from \"node:path\";\nimport { Storage } from \"@brighter/storage-adapter-local\";\nimport {\n  type IAgentRuntime,\n  logger,\n  resolveStateDir,\n  Service,\n  ServiceType,\n} from \"@elizaos/core\";\n\nimport type { JsonUploadResult, JsonValue, UploadResult } from \"../types\";\n\n/**\n * Subset of the @brighter/storage-adapter-local interface that this service\n * actually exercises. Typed locally to avoid leaking the upstream package's\n * loose `string | Buffer` return types into our public API.\n */\ninterface LocalStorage {\n  write(path: string, data: Buffer | string, opts?: { encoding?: string }): Promise<void>;\n  read(path: string, opts?: { encoding?: string }): Promise<Buffer | string | undefined>;\n  exists(path: string): Promise<boolean>;\n  remove(path: string, opts?: { recursive?: boolean }): Promise<void>;\n}\n\n/**\n * Resolves the storage root directory. Order of precedence:\n *\n *   1. `runtime.getSetting(\"LOCAL_STORAGE_PATH\")`\n *   2. `process.env.LOCAL_STORAGE_PATH`\n *   3. `<resolveStateDir()>/attachments`\n */\nfunction resolveStorageRoot(runtime: IAgentRuntime): string {\n  const fromRuntime = runtime.getSetting(\"LOCAL_STORAGE_PATH\");\n  if (typeof fromRuntime === \"string\" && fromRuntime.length > 0) {\n    return path.resolve(fromRuntime);\n  }\n  const fromEnv = process.env.LOCAL_STORAGE_PATH;\n  if (typeof fromEnv === \"string\" && fromEnv.length > 0) {\n    return path.resolve(fromEnv);\n  }\n  return path.join(resolveStateDir(), \"attachments\");\n}\n\nfunction joinKey(...segments: Array<string | undefined>): string {\n  const joined = segments\n    .filter((s): s is string => typeof s === \"string\" && s.length > 0)\n    .join(\"/\");\n  return joined.replace(/\\/+/g, \"/\").replace(/^\\/+/, \"\");\n}\n\n/**\n * Local filesystem implementation of `ServiceType.REMOTE_FILES`. Backed by\n * `@brighter/storage-adapter-local`. Method names mirror the surface that\n * the removed `@elizaos/plugin-s3-storage` `AwsS3Service` exposed so call\n * sites can be retargeted with no refactor.\n */\nexport class LocalFileStorageService extends Service {\n  static override serviceType = ServiceType.REMOTE_FILES;\n  capabilityDescription = \"Local filesystem attachment storage\";\n\n  private storage: LocalStorage | null = null;\n  private storageRoot = \"\";\n\n  static override async start(runtime: IAgentRuntime): Promise<LocalFileStorageService> {\n    logger.log(\"Initializing LocalFileStorageService\");\n    const service = new LocalFileStorageService(runtime);\n    await service.initialize(runtime);\n    return service;\n  }\n\n  static async stop(runtime: IAgentRuntime): Promise<void> {\n    const service = runtime.getService(ServiceType.REMOTE_FILES);\n    if (service) {\n      await service.stop();\n    }\n  }\n\n  async stop(): Promise<void> {\n    this.storage = null;\n  }\n\n  /**\n   * Filesystem path to the storage root. Useful for tests and tooling.\n   */\n  get root(): string {\n    return this.storageRoot;\n  }\n\n  private async initialize(runtime: IAgentRuntime): Promise<void> {\n    this.storageRoot = resolveStorageRoot(runtime);\n    await fsp.mkdir(this.storageRoot, { recursive: true });\n    this.storage = Storage({ path: this.storageRoot });\n  }\n\n  private getStorage(): LocalStorage {\n    if (!this.storage) {\n      throw new Error(\"LocalFileStorageService not initialized\");\n    }\n    return this.storage;\n  }\n\n  private absolutePath(key: string): string {\n    return path.join(this.storageRoot, key);\n  }\n\n  private fileUrl(key: string): string {\n    return `file://${this.absolutePath(key)}`;\n  }\n\n  /**\n   * Copy a file from the filesystem into the storage root.\n   *\n   * @param filePath Source path on the local filesystem.\n   * @param subDirectory Optional subdirectory under the storage root.\n   */\n  async uploadFile(filePath: string, subDirectory?: string): Promise<UploadResult> {\n    const storage = this.getStorage();\n    const baseFileName = `${Date.now()}-${path.basename(filePath)}`;\n    const key = joinKey(subDirectory, baseFileName);\n    const buffer = await fsp.readFile(filePath);\n    await storage.write(key, buffer, { encoding: \"binary\" });\n    return { success: true, url: this.fileUrl(key) };\n  }\n\n  /**\n   * Write raw bytes under a fixed key.\n   *\n   * @param data         Bytes to write.\n   * @param fileName     Final segment of the storage key.\n   * @param contentType  Reserved for API parity with the previous S3\n   *                     service. Local storage does not record per-object\n   *                     content types beyond what the OS infers, so this\n   *                     value is currently unused.\n   * @param subDirectory Optional subdirectory under the storage root.\n   */\n  async uploadBytes(\n    data: Buffer | Uint8Array,\n    fileName: string,\n    contentType: string,\n    subDirectory?: string\n  ): Promise<UploadResult> {\n    const storage = this.getStorage();\n    const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data);\n    const key = joinKey(subDirectory, fileName);\n    await storage.write(key, buffer, { encoding: \"binary\" });\n    void contentType;\n    return { success: true, url: this.fileUrl(key) };\n  }\n\n  /**\n   * Serialize a JSON-shaped value and write it under a fixed key.\n   *\n   * @param jsonData     The object to serialize.\n   * @param fileName     Optional filename. Defaults to `${Date.now()}.json`.\n   * @param subDirectory Optional subdirectory under the storage root.\n   */\n  async uploadJson(\n    jsonData: Record<string, JsonValue>,\n    fileName?: string,\n    subDirectory?: string\n  ): Promise<JsonUploadResult> {\n    if (!jsonData) {\n      return { success: false, error: \"JSON data is required\" };\n    }\n    const storage = this.getStorage();\n    const actualFileName = fileName ?? `${Date.now()}.json`;\n    const key = joinKey(subDirectory, actualFileName);\n    const body = JSON.stringify(jsonData, null, 2);\n    await storage.write(key, body, { encoding: \"utf8\" });\n    return { success: true, key, url: this.fileUrl(key) };\n  }\n\n  /**\n   * Read bytes for a previously-stored key.\n   *\n   * @param _unusedBucket Kept for API parity with the previous S3 service.\n   *                      Local storage has no bucket concept; the value is\n   *                      ignored and the key resolves under the storage\n   *                      root.\n   * @param key           Storage key (relative path under the root).\n   */\n  async downloadBytes(_unusedBucket: string, key: string): Promise<Buffer> {\n    const storage = this.getStorage();\n    const result = await storage.read(key, { encoding: \"binary\" });\n    if (result === undefined) {\n      throw new Error(`Object not found: ${key}`);\n    }\n    if (typeof result === \"string\") {\n      // Defensive: brighter local always returns Buffer when encoding is\n      // 'binary', but the upstream type signature allows string. Keep the\n      // public API a strict Buffer.\n      return Buffer.from(result, \"binary\");\n    }\n    return result;\n  }\n\n  /**\n   * Read bytes and write them to a local filesystem path.\n   */\n  async downloadFile(_unusedBucket: string, key: string, localPath: string): Promise<void> {\n    const buffer = await this.downloadBytes(_unusedBucket, key);\n    await fsp.writeFile(localPath, buffer);\n  }\n\n  /**\n   * Remove a stored object. Idempotent: removing a missing key throws.\n   */\n  async delete(_unusedBucket: string, key: string): Promise<void> {\n    const storage = this.getStorage();\n    await storage.remove(key);\n  }\n\n  /**\n   * Whether a stored object exists.\n   */\n  async exists(_unusedBucket: string, key: string): Promise<boolean> {\n    const storage = this.getStorage();\n    return storage.exists(key);\n  }\n\n  /**\n   * Returns a `file://` absolute URL for the stored object.\n   *\n   * Local storage cannot mint short-lived signed URLs the way S3 can — the\n   * URL is permanent and exposes the absolute filesystem path. Callers that\n   * need a public, expiring URL should route attachment storage through\n   * Eliza Cloud instead.\n   *\n   * @param fileName    Storage key (relative path under the root).\n   * @param _expiresIn  Reserved for API parity with the previous S3 service.\n   */\n  async generateSignedUrl(fileName: string, _expiresIn?: number): Promise<string> {\n    return this.fileUrl(fileName);\n  }\n}\n\nexport default LocalFileStorageService;\n",
+    "/**\n * JSON-serializable primitive values.\n */\nexport type JsonPrimitive = string | number | boolean | null;\n\n/**\n * JSON-serializable object type.\n */\nexport interface JsonObject {\n  [key: string]: JsonPrimitive | JsonObject | JsonArray;\n}\n\n/**\n * JSON-serializable array type.\n */\nexport type JsonArray = Array<JsonPrimitive | JsonObject | JsonArray>;\n\n/**\n * JSON-serializable value type.\n */\nexport type JsonValue = JsonPrimitive | JsonObject | JsonArray;\n\n/**\n * Result of a binary upload operation.\n *\n * Mirrors the shape returned by the removed `@elizaos/plugin-s3-storage`\n * `AwsS3Service` so callers can be retargeted without refactoring.\n */\nexport interface UploadResult {\n  success: boolean;\n  /** Absolute `file://` URL for the stored object on success. */\n  url?: string;\n  /** Human-readable error message on failure. */\n  error?: string;\n}\n\n/**\n * Result of a JSON upload operation. Same as `UploadResult` plus the\n * resolved storage key.\n */\nexport interface JsonUploadResult extends UploadResult {\n  /** Storage key (relative path under the storage root). */\n  key?: string;\n}\n\n/**\n * Mapping from filename extension to MIME type. Mirrors the table that\n * shipped with the deprecated S3 plugin so behavior matches for callers\n * that depended on the original content-type inference.\n */\nexport const CONTENT_TYPES: Readonly<Record<string, string>> = {\n  \".png\": \"image/png\",\n  \".jpg\": \"image/jpeg\",\n  \".jpeg\": \"image/jpeg\",\n  \".gif\": \"image/gif\",\n  \".webp\": \"image/webp\",\n  \".pdf\": \"application/pdf\",\n  \".json\": \"application/json\",\n  \".txt\": \"text/plain\",\n  \".html\": \"text/html\",\n  \".css\": \"text/css\",\n  \".js\": \"application/javascript\",\n  \".mp3\": \"audio/mpeg\",\n  \".mp4\": \"video/mp4\",\n  \".wav\": \"audio/wav\",\n  \".webm\": \"video/webm\",\n};\n\n/**\n * Resolve a Content-Type by extension. Falls back to\n * `application/octet-stream` when the extension is unknown.\n */\nexport function getContentType(filePath: string): string {\n  const dot = filePath.lastIndexOf(\".\");\n  if (dot === -1) return \"application/octet-stream\";\n  const ext = filePath.substring(dot).toLowerCase();\n  return CONTENT_TYPES[ext] ?? \"application/octet-stream\";\n}\n",
+    "import type { Plugin } from \"@elizaos/core\";\n\nimport { LocalFileStorageService } from \"./services/local-storage\";\n\nexport * from \"./types\";\nexport { LocalFileStorageService };\n\nexport const localStoragePlugin: Plugin = {\n  name: \"local-storage\",\n  description:\n    \"Local filesystem attachment storage (default fallback when Eliza Cloud storage is not connected)\",\n  services: [LocalFileStorageService],\n  actions: [],\n};\n\nexport default localStoragePlugin;\n"
+  ],
+  "mappings": "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",
+  "debugId": "B7B5210279BE486A64756E2164756E21",
+  "names": []
+}

package/dist/services/local-storage.d.ts

@@ -0,0 +1,87 @@
+import { type IAgentRuntime, Service } from "@elizaos/core";
+import type { JsonUploadResult, JsonValue, UploadResult } from "../types";
+/**
+ * Local filesystem implementation of `ServiceType.REMOTE_FILES`. Backed by
+ * `@brighter/storage-adapter-local`. Method names mirror the surface that
+ * the removed `@elizaos/plugin-s3-storage` `AwsS3Service` exposed so call
+ * sites can be retargeted with no refactor.
+ */
+export declare class LocalFileStorageService extends Service {
+    static serviceType: "aws_s3";
+    capabilityDescription: string;
+    private storage;
+    private storageRoot;
+    static start(runtime: IAgentRuntime): Promise<LocalFileStorageService>;
+    static stop(runtime: IAgentRuntime): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Filesystem path to the storage root. Useful for tests and tooling.
+     */
+    get root(): string;
+    private initialize;
+    private getStorage;
+    private absolutePath;
+    private fileUrl;
+    /**
+     * Copy a file from the filesystem into the storage root.
+     *
+     * @param filePath Source path on the local filesystem.
+     * @param subDirectory Optional subdirectory under the storage root.
+     */
+    uploadFile(filePath: string, subDirectory?: string): Promise<UploadResult>;
+    /**
+     * Write raw bytes under a fixed key.
+     *
+     * @param data         Bytes to write.
+     * @param fileName     Final segment of the storage key.
+     * @param contentType  Reserved for API parity with the previous S3
+     *                     service. Local storage does not record per-object
+     *                     content types beyond what the OS infers, so this
+     *                     value is currently unused.
+     * @param subDirectory Optional subdirectory under the storage root.
+     */
+    uploadBytes(data: Buffer | Uint8Array, fileName: string, contentType: string, subDirectory?: string): Promise<UploadResult>;
+    /**
+     * Serialize a JSON-shaped value and write it under a fixed key.
+     *
+     * @param jsonData     The object to serialize.
+     * @param fileName     Optional filename. Defaults to `${Date.now()}.json`.
+     * @param subDirectory Optional subdirectory under the storage root.
+     */
+    uploadJson(jsonData: Record<string, JsonValue>, fileName?: string, subDirectory?: string): Promise<JsonUploadResult>;
+    /**
+     * Read bytes for a previously-stored key.
+     *
+     * @param _unusedBucket Kept for API parity with the previous S3 service.
+     *                      Local storage has no bucket concept; the value is
+     *                      ignored and the key resolves under the storage
+     *                      root.
+     * @param key           Storage key (relative path under the root).
+     */
+    downloadBytes(_unusedBucket: string, key: string): Promise<Buffer>;
+    /**
+     * Read bytes and write them to a local filesystem path.
+     */
+    downloadFile(_unusedBucket: string, key: string, localPath: string): Promise<void>;
+    /**
+     * Remove a stored object. Idempotent: removing a missing key throws.
+     */
+    delete(_unusedBucket: string, key: string): Promise<void>;
+    /**
+     * Whether a stored object exists.
+     */
+    exists(_unusedBucket: string, key: string): Promise<boolean>;
+    /**
+     * Returns a `file://` absolute URL for the stored object.
+     *
+     * Local storage cannot mint short-lived signed URLs the way S3 can — the
+     * URL is permanent and exposes the absolute filesystem path. Callers that
+     * need a public, expiring URL should route attachment storage through
+     * Eliza Cloud instead.
+     *
+     * @param fileName    Storage key (relative path under the root).
+     * @param _expiresIn  Reserved for API parity with the previous S3 service.
+     */
+    generateSignedUrl(fileName: string, _expiresIn?: number): Promise<string>;
+}
+export default LocalFileStorageService;

package/dist/types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * JSON-serializable primitive values.
+ */
+export type JsonPrimitive = string | number | boolean | null;
+/**
+ * JSON-serializable object type.
+ */
+export interface JsonObject {
+    [key: string]: JsonPrimitive | JsonObject | JsonArray;
+}
+/**
+ * JSON-serializable array type.
+ */
+export type JsonArray = Array<JsonPrimitive | JsonObject | JsonArray>;
+/**
+ * JSON-serializable value type.
+ */
+export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+/**
+ * Result of a binary upload operation.
+ *
+ * Mirrors the shape returned by the removed `@elizaos/plugin-s3-storage`
+ * `AwsS3Service` so callers can be retargeted without refactoring.
+ */
+export interface UploadResult {
+    success: boolean;
+    /** Absolute `file://` URL for the stored object on success. */
+    url?: string;
+    /** Human-readable error message on failure. */
+    error?: string;
+}
+/**
+ * Result of a JSON upload operation. Same as `UploadResult` plus the
+ * resolved storage key.
+ */
+export interface JsonUploadResult extends UploadResult {
+    /** Storage key (relative path under the storage root). */
+    key?: string;
+}
+/**
+ * Mapping from filename extension to MIME type. Mirrors the table that
+ * shipped with the deprecated S3 plugin so behavior matches for callers
+ * that depended on the original content-type inference.
+ */
+export declare const CONTENT_TYPES: Readonly<Record<string, string>>;
+/**
+ * Resolve a Content-Type by extension. Falls back to
+ * `application/octet-stream` when the extension is unknown.
+ */
+export declare function getContentType(filePath: string): string;

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@elizaos/plugin-local-storage",
+  "version": "2.0.0-beta.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "description": "Local filesystem attachment storage backed by @brighter/storage-adapter-local. Default fallback when Eliza Cloud storage is not connected.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/elizaos/eliza.git"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@brighter/storage": "^1.6.3",
+    "@brighter/storage-adapter-local": "^1.6.3",
+    "@elizaos/core": "2.0.0-beta.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.14",
+    "@types/bun": "^1.3.5",
+    "@types/node": "^25.0.3",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "build": "bun run build.ts",
+    "dev": "bun --hot build.ts",
+    "test": "vitest run --config ./vitest.config.ts",
+    "clean": "rm -rf dist .turbo .turbo-tsconfig.json tsconfig.tsbuildinfo",
+    "format": "bunx @biomejs/biome format --write .",
+    "format:check": "bunx @biomejs/biome format .",
+    "lint": "bunx @biomejs/biome check --write --unsafe .",
+    "lint:check": "bunx @biomejs/biome check .",
+    "typecheck": "tsc --noEmit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "agentConfig": {
+    "pluginType": "elizaos:plugin:1.0.0",
+    "pluginParameters": {
+      "LOCAL_STORAGE_PATH": {
+        "type": "string",
+        "description": "Filesystem root for attachment storage. Defaults to ${ELIZA_STATE_DIR ?? ~/.eliza}/attachments.",
+        "required": false,
+        "sensitive": false
+      }
+    }
+  },
+  "eliza": {
+    "platforms": [
+      "node"
+    ],
+    "runtime": "node",
+    "platformDetails": {
+      "node": "Node.js build available — uses node:fs / node:path"
+    }
+  }
+}