@agentxjs/node-platform 2.0.0

package/src/persistence/Persistence.ts

@@ -0,0 +1,53 @@
+/**
+ * Persistence - Core persistence implementation
+ *
+ * Creates a Persistence instance from a driver.
+ * Each driver provides a createStorage() method that returns an unstorage Storage instance.
+ */
+
+import type { Storage } from "unstorage";
+import { createLogger } from "commonxjs/logger";
+import type { Persistence, PersistenceDriver } from "./types";
+import { StorageContainerRepository } from "./StorageContainerRepository";
+import { StorageImageRepository } from "./StorageImageRepository";
+import { StorageSessionRepository } from "./StorageSessionRepository";
+
+const logger = createLogger("node-platform/Persistence");
+
+/**
+ * PersistenceImpl - Internal implementation
+ */
+class PersistenceImpl implements Persistence {
+  readonly containers: StorageContainerRepository;
+  readonly images: StorageImageRepository;
+  readonly sessions: StorageSessionRepository;
+
+  constructor(storage: Storage) {
+    this.containers = new StorageContainerRepository(storage);
+    this.images = new StorageImageRepository(storage);
+    this.sessions = new StorageSessionRepository(storage);
+  }
+}
+
+/**
+ * Create a Persistence instance from a driver
+ *
+ * @param driver - The persistence driver to use
+ * @returns Promise<Persistence> instance
+ *
+ * @example
+ * ```typescript
+ * import { createPersistence, memoryDriver } from "@agentxjs/node-platform/persistence";
+ *
+ * const persistence = await createPersistence(memoryDriver());
+ * ```
+ */
+export async function createPersistence(driver: PersistenceDriver): Promise<Persistence> {
+  logger.debug("Creating persistence");
+
+  const storage = await driver.createStorage();
+  const persistence = new PersistenceImpl(storage);
+
+  logger.info("Persistence created successfully");
+  return persistence;
+}

package/src/persistence/StorageContainerRepository.ts

@@ -0,0 +1,58 @@
+/**
+ * StorageContainerRepository - unstorage-based ContainerRepository
+ *
+ * Uses unstorage for backend-agnostic storage (Memory, Redis, SQLite, etc.)
+ */
+
+import type { Storage } from "unstorage";
+import type { ContainerRepository, ContainerRecord } from "@agentxjs/core/persistence";
+import { createLogger } from "commonxjs/logger";
+
+const logger = createLogger("node-platform/ContainerRepository");
+
+/** Key prefix for containers */
+const PREFIX = "containers";
+
+/**
+ * StorageContainerRepository - unstorage implementation
+ */
+export class StorageContainerRepository implements ContainerRepository {
+  constructor(private readonly storage: Storage) {}
+
+  private key(containerId: string): string {
+    return `${PREFIX}:${containerId}`;
+  }
+
+  async saveContainer(record: ContainerRecord): Promise<void> {
+    await this.storage.setItem(this.key(record.containerId), record);
+    logger.debug("Container saved", { containerId: record.containerId });
+  }
+
+  async findContainerById(containerId: string): Promise<ContainerRecord | null> {
+    const record = await this.storage.getItem<ContainerRecord>(this.key(containerId));
+    return record ?? null;
+  }
+
+  async findAllContainers(): Promise<ContainerRecord[]> {
+    const keys = await this.storage.getKeys(PREFIX);
+    const records: ContainerRecord[] = [];
+
+    for (const key of keys) {
+      const record = await this.storage.getItem<ContainerRecord>(key);
+      if (record) {
+        records.push(record);
+      }
+    }
+
+    return records.sort((a, b) => b.createdAt - a.createdAt);
+  }
+
+  async deleteContainer(containerId: string): Promise<void> {
+    await this.storage.removeItem(this.key(containerId));
+    logger.debug("Container deleted", { containerId });
+  }
+
+  async containerExists(containerId: string): Promise<boolean> {
+    return await this.storage.hasItem(this.key(containerId));
+  }
+}

package/src/persistence/StorageImageRepository.ts

@@ -0,0 +1,153 @@
+/**
+ * StorageImageRepository - unstorage-based ImageRepository
+ *
+ * Uses unstorage for backend-agnostic storage (Memory, Redis, SQLite, etc.)
+ */
+
+import type { Storage } from "unstorage";
+import type { ImageRepository, ImageRecord, ImageMetadata } from "@agentxjs/core/persistence";
+import { createLogger } from "commonxjs/logger";
+
+const logger = createLogger("node-platform/ImageRepository");
+
+/** Key prefix for images */
+const PREFIX = "images";
+
+/** Index prefix for name lookup */
+const INDEX_BY_NAME = "idx:images:name";
+
+/** Index prefix for container lookup */
+const INDEX_BY_CONTAINER = "idx:images:container";
+
+/**
+ * StorageImageRepository - unstorage implementation
+ */
+export class StorageImageRepository implements ImageRepository {
+  constructor(private readonly storage: Storage) {}
+
+  private key(imageId: string): string {
+    return `${PREFIX}:${imageId}`;
+  }
+
+  private nameIndexKey(name: string, imageId: string): string {
+    return `${INDEX_BY_NAME}:${name}:${imageId}`;
+  }
+
+  private containerIndexKey(containerId: string, imageId: string): string {
+    return `${INDEX_BY_CONTAINER}:${containerId}:${imageId}`;
+  }
+
+  async saveImage(record: ImageRecord): Promise<void> {
+    // Save main record
+    await this.storage.setItem(this.key(record.imageId), record);
+
+    // Save index for name lookup
+    await this.storage.setItem(this.nameIndexKey(record.name, record.imageId), record.imageId);
+
+    // Save index for container lookup
+    await this.storage.setItem(
+      this.containerIndexKey(record.containerId, record.imageId),
+      record.imageId
+    );
+
+    logger.debug("Image saved", { imageId: record.imageId });
+  }
+
+  async findImageById(imageId: string): Promise<ImageRecord | null> {
+    const record = await this.storage.getItem<ImageRecord>(this.key(imageId));
+    return record ?? null;
+  }
+
+  async findAllImages(): Promise<ImageRecord[]> {
+    const keys = await this.storage.getKeys(PREFIX);
+    const records: ImageRecord[] = [];
+
+    for (const key of keys) {
+      // Skip index keys
+      if (key.startsWith("idx:")) continue;
+
+      const record = await this.storage.getItem<ImageRecord>(key);
+      if (record) {
+        records.push(record);
+      }
+    }
+
+    return records.sort((a, b) => b.createdAt - a.createdAt);
+  }
+
+  async findImagesByName(name: string): Promise<ImageRecord[]> {
+    const indexPrefix = `${INDEX_BY_NAME}:${name}`;
+    const keys = await this.storage.getKeys(indexPrefix);
+    const records: ImageRecord[] = [];
+
+    for (const key of keys) {
+      const imageId = await this.storage.getItem<string>(key);
+      if (imageId) {
+        const record = await this.findImageById(imageId);
+        if (record) {
+          records.push(record);
+        }
+      }
+    }
+
+    return records.sort((a, b) => b.createdAt - a.createdAt);
+  }
+
+  async findImagesByContainerId(containerId: string): Promise<ImageRecord[]> {
+    const indexPrefix = `${INDEX_BY_CONTAINER}:${containerId}`;
+    const keys = await this.storage.getKeys(indexPrefix);
+    const records: ImageRecord[] = [];
+
+    for (const key of keys) {
+      const imageId = await this.storage.getItem<string>(key);
+      if (imageId) {
+        const record = await this.findImageById(imageId);
+        if (record) {
+          records.push(record);
+        }
+      }
+    }
+
+    return records.sort((a, b) => b.createdAt - a.createdAt);
+  }
+
+  async deleteImage(imageId: string): Promise<void> {
+    // Get record to find name and containerId for index cleanup
+    const record = await this.findImageById(imageId);
+
+    // Delete main record
+    await this.storage.removeItem(this.key(imageId));
+
+    // Delete indexes
+    if (record) {
+      await this.storage.removeItem(this.nameIndexKey(record.name, imageId));
+      await this.storage.removeItem(this.containerIndexKey(record.containerId, imageId));
+    }
+
+    logger.debug("Image deleted", { imageId });
+  }
+
+  async imageExists(imageId: string): Promise<boolean> {
+    return await this.storage.hasItem(this.key(imageId));
+  }
+
+  async updateMetadata(imageId: string, metadata: Partial<ImageMetadata>): Promise<void> {
+    const record = await this.findImageById(imageId);
+    if (!record) {
+      throw new Error(`Image not found: ${imageId}`);
+    }
+
+    // Merge metadata
+    const updatedRecord: ImageRecord = {
+      ...record,
+      metadata: {
+        ...record.metadata,
+        ...metadata,
+      },
+      updatedAt: Date.now(),
+    };
+
+    await this.storage.setItem(this.key(imageId), updatedRecord);
+    logger.debug("Image metadata updated", { imageId, metadata });
+  }
+}

package/src/persistence/StorageSessionRepository.ts

@@ -0,0 +1,171 @@
+/**
+ * StorageSessionRepository - unstorage-based SessionRepository
+ *
+ * Uses unstorage for backend-agnostic storage (Memory, Redis, SQLite, etc.)
+ */
+
+import type { Storage } from "unstorage";
+import type { SessionRepository, SessionRecord } from "@agentxjs/core/persistence";
+import type { Message } from "@agentxjs/core/agent";
+import { createLogger } from "commonxjs/logger";
+
+const logger = createLogger("node-platform/SessionRepository");
+
+/** Key prefix for sessions */
+const PREFIX = "sessions";
+
+/** Key prefix for messages */
+const MESSAGES_PREFIX = "messages";
+
+/** Index prefix for image lookup */
+const INDEX_BY_IMAGE = "idx:sessions:image";
+
+/** Index prefix for container lookup */
+const INDEX_BY_CONTAINER = "idx:sessions:container";
+
+/**
+ * StorageSessionRepository - unstorage implementation
+ */
+export class StorageSessionRepository implements SessionRepository {
+  constructor(private readonly storage: Storage) {}
+
+  private key(sessionId: string): string {
+    return `${PREFIX}:${sessionId}`;
+  }
+
+  private messagesKey(sessionId: string): string {
+    return `${MESSAGES_PREFIX}:${sessionId}`;
+  }
+
+  private imageIndexKey(imageId: string, sessionId: string): string {
+    return `${INDEX_BY_IMAGE}:${imageId}:${sessionId}`;
+  }
+
+  private containerIndexKey(containerId: string, sessionId: string): string {
+    return `${INDEX_BY_CONTAINER}:${containerId}:${sessionId}`;
+  }
+
+  async saveSession(record: SessionRecord): Promise<void> {
+    // Save main record
+    await this.storage.setItem(this.key(record.sessionId), record);
+
+    // Save index for image lookup
+    await this.storage.setItem(
+      this.imageIndexKey(record.imageId, record.sessionId),
+      record.sessionId
+    );
+
+    // Save index for container lookup
+    await this.storage.setItem(
+      this.containerIndexKey(record.containerId, record.sessionId),
+      record.sessionId
+    );
+
+    logger.debug("Session saved", { sessionId: record.sessionId });
+  }
+
+  async findSessionById(sessionId: string): Promise<SessionRecord | null> {
+    const record = await this.storage.getItem<SessionRecord>(this.key(sessionId));
+    return record ?? null;
+  }
+
+  async findSessionByImageId(imageId: string): Promise<SessionRecord | null> {
+    const indexPrefix = `${INDEX_BY_IMAGE}:${imageId}`;
+    const keys = await this.storage.getKeys(indexPrefix);
+
+    if (keys.length === 0) return null;
+
+    // Return the first (most recent) session for this image
+    const sessionId = await this.storage.getItem<string>(keys[0]);
+    if (!sessionId) return null;
+
+    return this.findSessionById(sessionId);
+  }
+
+  async findSessionsByContainerId(containerId: string): Promise<SessionRecord[]> {
+    const indexPrefix = `${INDEX_BY_CONTAINER}:${containerId}`;
+    const keys = await this.storage.getKeys(indexPrefix);
+    const records: SessionRecord[] = [];
+
+    for (const key of keys) {
+      const sessionId = await this.storage.getItem<string>(key);
+      if (sessionId) {
+        const record = await this.findSessionById(sessionId);
+        if (record) {
+          records.push(record);
+        }
+      }
+    }
+
+    return records.sort((a, b) => b.createdAt - a.createdAt);
+  }
+
+  async findAllSessions(): Promise<SessionRecord[]> {
+    const keys = await this.storage.getKeys(PREFIX);
+    const records: SessionRecord[] = [];
+
+    for (const key of keys) {
+      // Skip index keys
+      if (key.startsWith("idx:")) continue;
+
+      const record = await this.storage.getItem<SessionRecord>(key);
+      if (record) {
+        records.push(record);
+      }
+    }
+
+    return records.sort((a, b) => b.createdAt - a.createdAt);
+  }
+
+  async deleteSession(sessionId: string): Promise<void> {
+    // Get record for index cleanup
+    const record = await this.findSessionById(sessionId);
+
+    // Delete main record
+    await this.storage.removeItem(this.key(sessionId));
+
+    // Delete messages
+    await this.storage.removeItem(this.messagesKey(sessionId));
+
+    // Delete indexes
+    if (record) {
+      await this.storage.removeItem(this.imageIndexKey(record.imageId, sessionId));
+      await this.storage.removeItem(this.containerIndexKey(record.containerId, sessionId));
+    }
+
+    logger.debug("Session deleted", { sessionId });
+  }
+
+  async sessionExists(sessionId: string): Promise<boolean> {
+    return await this.storage.hasItem(this.key(sessionId));
+  }
+
+  // ==================== Message Operations ====================
+
+  async addMessage(sessionId: string, message: Message): Promise<void> {
+    const messages = await this.getMessages(sessionId);
+    messages.push(message);
+    await this.storage.setItem(this.messagesKey(sessionId), messages);
+    logger.debug("Message added to session", { sessionId, subtype: message.subtype });
+  }
+
+  async getMessages(sessionId: string): Promise<Message[]> {
+    const messages = await this.storage.getItem<Message[]>(this.messagesKey(sessionId));
+    // Ensure we always return an array (handle corrupted data)
+    if (!messages || !Array.isArray(messages)) {
+      if (messages) {
+        logger.warn("Messages data is not an array, resetting", {
+          sessionId,
+          type: typeof messages,
+        });
+      }
+      return [];
+    }
+    return messages;
+  }
+
+  async clearMessages(sessionId: string): Promise<void> {
+    await this.storage.removeItem(this.messagesKey(sessionId));
+    logger.debug("Messages cleared for session", { sessionId });
+  }
+}

package/src/persistence/index.ts

@@ -0,0 +1,38 @@
+/**
+ * Persistence Module
+ *
+ * Provides storage implementations for Node.js.
+ *
+ * @example
+ * ```typescript
+ * import { createPersistence, sqliteDriver, memoryDriver } from "@agentxjs/node-platform/persistence";
+ *
+ * // SQLite (persistent)
+ * const persistence = await createPersistence(
+ *   sqliteDriver({ path: "./data/agentx.db" })
+ * );
+ *
+ * // Memory (testing)
+ * const testPersistence = await createPersistence(memoryDriver());
+ *
+ * // Use repositories
+ * await persistence.containers.saveContainer(record);
+ * await persistence.images.saveImage(imageRecord);
+ * await persistence.sessions.addMessage(sessionId, message);
+ * ```
+ */
+
+// Types
+export type { PersistenceDriver, Persistence } from "./types";
+
+// Factory
+export { createPersistence } from "./Persistence";
+
+// Drivers
+export { sqliteDriver, type SqliteDriverOptions } from "./sqlite";
+export { memoryDriver } from "./memory";
+
+// Repositories (for advanced use cases)
+export { StorageContainerRepository } from "./StorageContainerRepository";
+export { StorageImageRepository } from "./StorageImageRepository";
+export { StorageSessionRepository } from "./StorageSessionRepository";

package/src/persistence/memory.ts

@@ -0,0 +1,27 @@
+/**
+ * Memory Driver - In-memory storage
+ *
+ * Useful for testing and development.
+ * Data is lost when the process exits.
+ *
+ * @example
+ * ```typescript
+ * import { createPersistence, memoryDriver } from "@agentxjs/node-platform/persistence";
+ *
+ * const persistence = await createPersistence(memoryDriver());
+ * ```
+ */
+
+import { createStorage, type Storage } from "unstorage";
+import type { PersistenceDriver } from "./types";
+
+/**
+ * Create a memory driver
+ */
+export function memoryDriver(): PersistenceDriver {
+  return {
+    async createStorage(): Promise<Storage> {
+      return createStorage();
+    },
+  };
+}

package/src/persistence/sqlite.ts

@@ -0,0 +1,111 @@
+/**
+ * SQLite Driver - SQLite database storage
+ *
+ * Uses commonxjs SQLite abstraction with automatic runtime detection:
+ * - Bun: uses bun:sqlite (built-in)
+ * - Node.js 22+: uses node:sqlite (built-in)
+ *
+ * @example
+ * ```typescript
+ * import { createPersistence, sqliteDriver } from "@agentxjs/node-platform/persistence";
+ *
+ * const persistence = await createPersistence(
+ *   sqliteDriver({ path: "./data/agentx.db" })
+ * );
+ * ```
+ */
+
+import { createStorage, type Storage, type Driver } from "unstorage";
+import { openDatabase, type Database } from "commonxjs/sqlite";
+import type { PersistenceDriver } from "./types";
+
+export interface SqliteDriverOptions {
+  /**
+   * Path to SQLite database file
+   * @example "./data/agentx.db"
+   */
+  path: string;
+}
+
+/**
+ * Create a custom unstorage driver using our SQLite abstraction
+ */
+function createSqliteUnstorageDriver(db: Database): Driver {
+  // Initialize schema
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS kv_storage (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_kv_key ON kv_storage(key);
+  `);
+
+  return {
+    name: "agentx-sqlite",
+
+    hasItem(key: string): boolean {
+      const row = db.prepare("SELECT 1 FROM kv_storage WHERE key = ?").get(key);
+      // Note: row can be null (not found) or object (found)
+      // Must use != null to handle both null and undefined
+      return row != null;
+    },
+
+    getItem(key: string): string | null {
+      const row = db.prepare("SELECT value FROM kv_storage WHERE key = ?").get(key) as
+        | { value: string }
+        | undefined;
+      return row?.value ?? null;
+    },
+
+    setItem(key: string, value: string): void {
+      const now = Date.now();
+      const existing = db.prepare("SELECT 1 FROM kv_storage WHERE key = ?").get(key);
+      if (existing) {
+        db.prepare("UPDATE kv_storage SET value = ?, updated_at = ? WHERE key = ?").run(
+          value,
+          now,
+          key
+        );
+      } else {
+        db.prepare(
+          "INSERT INTO kv_storage (key, value, created_at, updated_at) VALUES (?, ?, ?, ?)"
+        ).run(key, value, now, now);
+      }
+    },
+
+    removeItem(key: string): void {
+      db.prepare("DELETE FROM kv_storage WHERE key = ?").run(key);
+    },
+
+    getKeys(): string[] {
+      const rows = db.prepare("SELECT key FROM kv_storage").all() as { key: string }[];
+      return rows.map((r) => r.key);
+    },
+
+    clear(): void {
+      db.exec("DELETE FROM kv_storage");
+    },
+
+    dispose(): void {
+      db.close();
+    },
+  };
+}
+
+/**
+ * Create a SQLite driver
+ *
+ * @param options - Driver options
+ */
+export function sqliteDriver(options: SqliteDriverOptions): PersistenceDriver {
+  return {
+    async createStorage(): Promise<Storage> {
+      const db = openDatabase(options.path);
+      const driver = createSqliteUnstorageDriver(db);
+
+      return createStorage({ driver });
+    },
+  };
+}

package/src/persistence/types.ts

@@ -0,0 +1,32 @@
+/**
+ * Persistence Types for Node Provider
+ */
+
+import type { Storage } from "unstorage";
+import type {
+  ContainerRepository,
+  ImageRepository,
+  SessionRepository,
+} from "@agentxjs/core/persistence";
+
+/**
+ * Persistence driver interface
+ *
+ * Each driver must implement this interface.
+ * The createStorage() method is called once during initialization.
+ */
+export interface PersistenceDriver {
+  /**
+   * Create the underlying storage instance
+   */
+  createStorage(): Promise<Storage>;
+}
+
+/**
+ * Persistence - Aggregated repositories
+ */
+export interface Persistence {
+  readonly containers: ContainerRepository;
+  readonly images: ImageRepository;
+  readonly sessions: SessionRepository;
+}