@almadar/agent 1.0.0

package/dist/persistence/index.d.ts

@@ -0,0 +1,201 @@
+import { d as SessionMetadata, e as SessionRecord, b as FirestoreDb, S as Session } from '../firestore-checkpointer-DxbQ10ve.js';
+export { F as FirestoreCheckpointer, a as FirestoreCheckpointerOptions, c as FirestoreTimestamp, P as PersistenceMode } from '../firestore-checkpointer-DxbQ10ve.js';
+import { BaseStore, Operation, OperationResults } from '@langchain/langgraph-checkpoint';
+import '@langchain/core/runnables';
+
+/**
+ * In-Memory Persistence Backend
+ *
+ * Provides in-memory session metadata storage for development.
+ * Data is lost on process restart.
+ */
+
+/**
+ * In-memory session metadata store.
+ */
+declare class MemorySessionBackend {
+    private sessions;
+    /**
+     * Store session metadata.
+     */
+    store(threadId: string, metadata: SessionMetadata): void;
+    /**
+     * Get session metadata.
+     */
+    get(threadId: string): SessionMetadata | undefined;
+    /**
+     * Delete session metadata.
+     */
+    delete(threadId: string): boolean;
+    /**
+     * List all sessions.
+     */
+    list(): SessionRecord[];
+    /**
+     * Check if a session exists.
+     */
+    has(threadId: string): boolean;
+}
+
+/**
+ * Firestore Session Store for DeepAgent
+ *
+ * Provides persistent session storage for skill-based agents.
+ * Sessions are stored in Firestore and persist across server restarts.
+ *
+ * IMPORTANT: This module does NOT import firebase-admin directly.
+ * The Firestore `db` instance must be injected via constructor options.
+ */
+
+/**
+ * Options for FirestoreSessionStore.
+ */
+interface FirestoreSessionStoreOptions {
+    /**
+     * Firestore instance. Required — injected by consumer.
+     */
+    db: FirestoreDb;
+    /**
+     * Collection name for sessions.
+     * @default 'agent_sessions'
+     */
+    collection?: string;
+}
+/**
+ * Firestore-backed session store for skill agents.
+ *
+ * @example
+ * ```typescript
+ * const sessionStore = new FirestoreSessionStore({ db: getFirestore() });
+ *
+ * await sessionStore.save({
+ *   threadId: 'abc-123',
+ *   skill: 'kflow-generating-m',
+ *   workDir: '/tmp/workspace',
+ *   createdAt: new Date(),
+ *   lastActivityAt: new Date(),
+ * });
+ *
+ * const session = await sessionStore.get('abc-123');
+ * ```
+ */
+declare class FirestoreSessionStore {
+    private db;
+    private collection;
+    constructor(options: FirestoreSessionStoreOptions);
+    /**
+     * Save a session.
+     */
+    save(session: Session): Promise<void>;
+    /**
+     * Get a session by thread ID.
+     */
+    get(threadId: string): Promise<Session | null>;
+    /**
+     * Update session's last activity timestamp.
+     */
+    touch(threadId: string): Promise<void>;
+    /**
+     * Delete a session.
+     */
+    delete(threadId: string): Promise<void>;
+    /**
+     * List sessions, optionally filtered by user ID.
+     */
+    list(options?: {
+        userId?: string;
+        limit?: number;
+    }): Promise<Session[]>;
+    /**
+     * Delete expired sessions (older than specified hours).
+     */
+    deleteExpired(maxAgeHours?: number): Promise<number>;
+}
+
+/**
+ * Firestore Store for LangGraph
+ *
+ * Custom implementation of BaseStore using Firebase Firestore.
+ * This provides persistent key-value storage for agent memories.
+ *
+ * IMPORTANT: This module does NOT import firebase-admin directly.
+ * The Firestore `db` instance must be injected via constructor options.
+ */
+
+/**
+ * Options for FirestoreStore.
+ */
+interface FirestoreStoreOptions {
+    /**
+     * Firestore instance. Required — injected by consumer.
+     */
+    db: FirestoreDb;
+    /**
+     * Collection name for store items.
+     * @default 'agent_memories'
+     */
+    collection?: string;
+}
+/**
+ * Firestore-backed store for LangGraph agent memories.
+ *
+ * Provides persistent key-value storage that can be shared across threads.
+ * Items are organized by hierarchical namespaces.
+ *
+ * @example
+ * ```typescript
+ * import { getFirestore } from 'firebase-admin/firestore';
+ *
+ * const store = new FirestoreStore({
+ *   db: getFirestore(),
+ *   collection: 'agent_memories',
+ * });
+ *
+ * // Store a memory
+ * await store.put(['agent', 'patterns'], 'schema-best-practices', {
+ *   content: 'Always validate schemas before saving',
+ * });
+ *
+ * // Retrieve a memory
+ * const item = await store.get(['agent', 'patterns'], 'schema-best-practices');
+ * ```
+ */
+declare class FirestoreStore extends BaseStore {
+    private db;
+    private collection;
+    constructor(options: FirestoreStoreOptions);
+    /**
+     * Create document ID from namespace and key.
+     */
+    private makeDocId;
+    /**
+     * Create namespace key for querying.
+     */
+    private makeNamespaceKey;
+    /**
+     * Execute multiple operations in a batch.
+     */
+    batch<Op extends Operation[]>(operations: Op): Promise<OperationResults<Op>>;
+    /**
+     * Get an item by namespace and key.
+     */
+    private getItem;
+    /**
+     * Put an item.
+     */
+    private putItem;
+    /**
+     * Delete an item.
+     */
+    private deleteItem;
+    /**
+     * Search for items.
+     */
+    private searchItems;
+    /**
+     * List namespaces.
+     */
+    private listNamespacesItems;
+}
+
+export { FirestoreDb, FirestoreSessionStore, type FirestoreSessionStoreOptions, FirestoreStore, type FirestoreStoreOptions, MemorySessionBackend, Session, SessionMetadata, SessionRecord };

package/dist/persistence/index.js

@@ -0,0 +1,489 @@
+import { BaseCheckpointSaver, BaseStore } from '@langchain/langgraph-checkpoint';
+
+// src/persistence/memory-backend.ts
+var MemorySessionBackend = class {
+  constructor() {
+    this.sessions = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Store session metadata.
+   */
+  store(threadId, metadata) {
+    this.sessions.set(threadId, metadata);
+  }
+  /**
+   * Get session metadata.
+   */
+  get(threadId) {
+    return this.sessions.get(threadId);
+  }
+  /**
+   * Delete session metadata.
+   */
+  delete(threadId) {
+    return this.sessions.delete(threadId);
+  }
+  /**
+   * List all sessions.
+   */
+  list() {
+    return Array.from(this.sessions.entries()).map(([threadId, meta]) => ({
+      threadId,
+      ...meta
+    }));
+  }
+  /**
+   * Check if a session exists.
+   */
+  has(threadId) {
+    return this.sessions.has(threadId);
+  }
+};
+var FirestoreCheckpointer = class extends BaseCheckpointSaver {
+  constructor(options) {
+    super();
+    this.db = options.db;
+    this.checkpointsCollection = options.checkpointsCollection ?? "agent_checkpoints";
+    this.writesCollection = options.writesCollection ?? "agent_writes";
+  }
+  /**
+   * Get thread ID from config.
+   */
+  getThreadId(config) {
+    const threadId = config.configurable?.thread_id;
+    if (!threadId || typeof threadId !== "string") {
+      throw new Error("thread_id is required in config.configurable");
+    }
+    return threadId;
+  }
+  /**
+   * Get checkpoint ID from config, or undefined for latest.
+   */
+  getCheckpointId(config) {
+    return config.configurable?.checkpoint_id;
+  }
+  /**
+   * Get checkpoint by config.
+   */
+  async getTuple(config) {
+    const threadId = this.getThreadId(config);
+    const checkpointId = this.getCheckpointId(config);
+    let query = this.db.collection(this.checkpointsCollection).where("threadId", "==", threadId);
+    if (checkpointId) {
+      query = query.where("checkpointId", "==", checkpointId);
+    } else {
+      query = query.orderBy("createdAt", "desc").limit(1);
+    }
+    const snapshot = await query.get();
+    if (snapshot.empty) {
+      return void 0;
+    }
+    const doc = snapshot.docs[0];
+    const data = doc.data();
+    const writesSnapshot = await this.db.collection(this.writesCollection).where("threadId", "==", threadId).where("checkpointId", "==", data.checkpointId).get();
+    const pendingWrites = writesSnapshot.docs.map((writeDoc) => {
+      const writeData = writeDoc.data();
+      return [writeData.taskId, writeData.channel, writeData.value];
+    });
+    const parentConfig = data.parentCheckpointId ? {
+      configurable: {
+        thread_id: threadId,
+        checkpoint_id: data.parentCheckpointId
+      }
+    } : void 0;
+    return {
+      config: {
+        configurable: {
+          thread_id: threadId,
+          checkpoint_id: data.checkpointId
+        }
+      },
+      checkpoint: data.checkpoint,
+      metadata: data.metadata,
+      parentConfig,
+      pendingWrites
+    };
+  }
+  /**
+   * List checkpoints for a thread.
+   */
+  async *list(config, options) {
+    const threadId = this.getThreadId(config);
+    const limit = options?.limit ?? 10;
+    let query = this.db.collection(this.checkpointsCollection).where("threadId", "==", threadId).orderBy("createdAt", "desc").limit(limit);
+    if (options?.filter) {
+      for (const [key, value] of Object.entries(options.filter)) {
+        query = query.where(`metadata.${key}`, "==", value);
+      }
+    }
+    if (options?.before?.configurable?.checkpoint_id) {
+      const beforeDoc = await this.db.collection(this.checkpointsCollection).where("threadId", "==", threadId).where("checkpointId", "==", options.before.configurable.checkpoint_id).get();
+      if (!beforeDoc.empty) {
+        query = query.startAfter(beforeDoc.docs[0]);
+      }
+    }
+    const snapshot = await query.get();
+    for (const doc of snapshot.docs) {
+      const data = doc.data();
+      const parentConfig = data.parentCheckpointId ? {
+        configurable: {
+          thread_id: threadId,
+          checkpoint_id: data.parentCheckpointId
+        }
+      } : void 0;
+      yield {
+        config: {
+          configurable: {
+            thread_id: threadId,
+            checkpoint_id: data.checkpointId
+          }
+        },
+        checkpoint: data.checkpoint,
+        metadata: data.metadata,
+        parentConfig
+      };
+    }
+  }
+  /**
+   * Save a checkpoint.
+   */
+  async put(config, checkpoint, metadata, _newVersions) {
+    const threadId = this.getThreadId(config);
+    const checkpointId = checkpoint.id;
+    const parentCheckpointId = this.getCheckpointId(config);
+    const now = /* @__PURE__ */ new Date();
+    const docData = {
+      threadId,
+      checkpointId,
+      parentCheckpointId,
+      checkpoint,
+      metadata,
+      createdAt: now,
+      updatedAt: now
+    };
+    const docId = `${threadId}_${checkpointId}`;
+    await this.db.collection(this.checkpointsCollection).doc(docId).set(docData);
+    return {
+      configurable: {
+        thread_id: threadId,
+        checkpoint_id: checkpointId
+      }
+    };
+  }
+  /**
+   * Store pending writes for a checkpoint.
+   */
+  async putWrites(config, writes, taskId) {
+    const threadId = this.getThreadId(config);
+    const checkpointId = this.getCheckpointId(config);
+    if (!checkpointId) {
+      throw new Error("checkpoint_id is required for putWrites");
+    }
+    const batch = this.db.batch();
+    const now = /* @__PURE__ */ new Date();
+    for (const [idx, [channel, value]] of writes.entries()) {
+      const docId = `${threadId}_${checkpointId}_${taskId}_${idx}`;
+      const docRef = this.db.collection(this.writesCollection).doc(docId);
+      const writeData = {
+        threadId,
+        checkpointId,
+        taskId,
+        channel,
+        value,
+        createdAt: now
+      };
+      batch.set(docRef, writeData);
+    }
+    await batch.commit();
+  }
+  /**
+   * Delete all checkpoints and writes for a thread.
+   */
+  async deleteThread(threadId) {
+    const checkpointsSnapshot = await this.db.collection(this.checkpointsCollection).where("threadId", "==", threadId).get();
+    const checkpointBatch = this.db.batch();
+    for (const doc of checkpointsSnapshot.docs) {
+      checkpointBatch.delete(doc.ref);
+    }
+    await checkpointBatch.commit();
+    const writesSnapshot = await this.db.collection(this.writesCollection).where("threadId", "==", threadId).get();
+    const writesBatch = this.db.batch();
+    for (const doc of writesSnapshot.docs) {
+      writesBatch.delete(doc.ref);
+    }
+    await writesBatch.commit();
+  }
+};
+
+// src/persistence/firestore-session-store.ts
+var FirestoreSessionStore = class {
+  constructor(options) {
+    this.db = options.db;
+    this.collection = options.collection ?? "agent_sessions";
+  }
+  /**
+   * Save a session.
+   */
+  async save(session) {
+    const now = /* @__PURE__ */ new Date();
+    const docData = {
+      threadId: session.threadId,
+      skill: session.skill,
+      workDir: session.workDir,
+      userId: session.userId,
+      createdAt: session.createdAt,
+      lastActivityAt: now
+    };
+    await this.db.collection(this.collection).doc(session.threadId).set(docData);
+  }
+  /**
+   * Get a session by thread ID.
+   */
+  async get(threadId) {
+    const doc = await this.db.collection(this.collection).doc(threadId).get();
+    if (!doc.exists) {
+      return null;
+    }
+    const data = doc.data();
+    return {
+      threadId: data.threadId,
+      skill: data.skill,
+      workDir: data.workDir,
+      userId: data.userId,
+      createdAt: data.createdAt?.toDate?.() ?? new Date(data.createdAt),
+      lastActivityAt: data.lastActivityAt?.toDate?.() ?? new Date(data.lastActivityAt)
+    };
+  }
+  /**
+   * Update session's last activity timestamp.
+   */
+  async touch(threadId) {
+    await this.db.collection(this.collection).doc(threadId).update({
+      lastActivityAt: /* @__PURE__ */ new Date()
+    });
+  }
+  /**
+   * Delete a session.
+   */
+  async delete(threadId) {
+    await this.db.collection(this.collection).doc(threadId).delete();
+  }
+  /**
+   * List sessions, optionally filtered by user ID.
+   */
+  async list(options) {
+    let query = this.db.collection(this.collection).orderBy("lastActivityAt", "desc");
+    if (options?.userId) {
+      query = query.where("userId", "==", options.userId);
+    }
+    const limit = options?.limit ?? 100;
+    query = query.limit(limit);
+    const snapshot = await query.get();
+    return snapshot.docs.map((doc) => {
+      const data = doc.data();
+      return {
+        threadId: data.threadId,
+        skill: data.skill,
+        workDir: data.workDir,
+        userId: data.userId,
+        createdAt: data.createdAt?.toDate?.() ?? new Date(data.createdAt),
+        lastActivityAt: data.lastActivityAt?.toDate?.() ?? new Date(data.lastActivityAt)
+      };
+    });
+  }
+  /**
+   * Delete expired sessions (older than specified hours).
+   */
+  async deleteExpired(maxAgeHours = 24) {
+    const cutoff = new Date(Date.now() - maxAgeHours * 60 * 60 * 1e3);
+    const snapshot = await this.db.collection(this.collection).where("lastActivityAt", "<", cutoff).get();
+    const batch = this.db.batch();
+    for (const doc of snapshot.docs) {
+      batch.delete(doc.ref);
+    }
+    await batch.commit();
+    return snapshot.size;
+  }
+};
+var FirestoreStore = class extends BaseStore {
+  constructor(options) {
+    super();
+    this.db = options.db;
+    this.collection = options.collection ?? "agent_memories";
+  }
+  /**
+   * Create document ID from namespace and key.
+   */
+  makeDocId(namespace, key) {
+    return [...namespace, key].join("/");
+  }
+  /**
+   * Create namespace key for querying.
+   */
+  makeNamespaceKey(namespace) {
+    return namespace.join("/");
+  }
+  /**
+   * Execute multiple operations in a batch.
+   */
+  async batch(operations) {
+    const results = [];
+    for (const op of operations) {
+      if ("key" in op && "namespace" in op && !("namespacePrefix" in op)) {
+        if ("value" in op) {
+          const putOp = op;
+          if (putOp.value === null) {
+            await this.deleteItem(putOp.namespace, putOp.key);
+          } else {
+            await this.putItem(putOp.namespace, putOp.key, putOp.value);
+          }
+          results.push(void 0);
+        } else {
+          const getOp = op;
+          const item = await this.getItem(getOp.namespace, getOp.key);
+          results.push(item);
+        }
+      } else if ("namespacePrefix" in op) {
+        const searchOp = op;
+        const items = await this.searchItems(searchOp);
+        results.push(items);
+      } else if ("matchConditions" in op || "limit" in op && "offset" in op && !("namespacePrefix" in op)) {
+        const listOp = op;
+        const namespaces = await this.listNamespacesItems(listOp);
+        results.push(namespaces);
+      }
+    }
+    return results;
+  }
+  /**
+   * Get an item by namespace and key.
+   */
+  async getItem(namespace, key) {
+    const docId = this.makeDocId(namespace, key);
+    const doc = await this.db.collection(this.collection).doc(docId).get();
+    if (!doc.exists) {
+      return null;
+    }
+    const data = doc.data();
+    return {
+      namespace: data.namespace,
+      key: data.key,
+      value: data.value,
+      createdAt: data.createdAt?.toDate?.() ?? new Date(data.createdAt),
+      updatedAt: data.updatedAt?.toDate?.() ?? new Date(data.updatedAt)
+    };
+  }
+  /**
+   * Put an item.
+   */
+  async putItem(namespace, key, value) {
+    const docId = this.makeDocId(namespace, key);
+    const now = /* @__PURE__ */ new Date();
+    const existingDoc = await this.db.collection(this.collection).doc(docId).get();
+    const createdAt = existingDoc.exists ? existingDoc.data().createdAt : now;
+    const docData = {
+      namespace,
+      namespaceKey: this.makeNamespaceKey(namespace),
+      key,
+      value,
+      createdAt,
+      updatedAt: now
+    };
+    await this.db.collection(this.collection).doc(docId).set(docData);
+  }
+  /**
+   * Delete an item.
+   */
+  async deleteItem(namespace, key) {
+    const docId = this.makeDocId(namespace, key);
+    await this.db.collection(this.collection).doc(docId).delete();
+  }
+  /**
+   * Search for items.
+   */
+  async searchItems(op) {
+    const namespacePrefix = this.makeNamespaceKey(op.namespacePrefix);
+    const limit = op.limit ?? 10;
+    const offset = op.offset ?? 0;
+    let query = this.db.collection(this.collection);
+    if (namespacePrefix) {
+      query = query.where("namespaceKey", ">=", namespacePrefix).where("namespaceKey", "<", namespacePrefix + "\uFFFF");
+    }
+    if (op.filter) {
+      for (const [key, filterValue] of Object.entries(op.filter)) {
+        if (typeof filterValue === "object" && filterValue !== null) {
+          for (const [operator, value] of Object.entries(filterValue)) {
+            switch (operator) {
+              case "$eq":
+                query = query.where(`value.${key}`, "==", value);
+                break;
+              case "$ne":
+                query = query.where(`value.${key}`, "!=", value);
+                break;
+              case "$gt":
+                query = query.where(`value.${key}`, ">", value);
+                break;
+              case "$gte":
+                query = query.where(`value.${key}`, ">=", value);
+                break;
+              case "$lt":
+                query = query.where(`value.${key}`, "<", value);
+                break;
+              case "$lte":
+                query = query.where(`value.${key}`, "<=", value);
+                break;
+            }
+          }
+        } else {
+          query = query.where(`value.${key}`, "==", filterValue);
+        }
+      }
+    }
+    query = query.limit(limit + offset);
+    const snapshot = await query.get();
+    const docs = snapshot.docs.slice(offset);
+    return docs.map((doc) => {
+      const data = doc.data();
+      return {
+        namespace: data.namespace,
+        key: data.key,
+        value: data.value,
+        createdAt: data.createdAt?.toDate?.() ?? new Date(data.createdAt),
+        updatedAt: data.updatedAt?.toDate?.() ?? new Date(data.updatedAt)
+      };
+    });
+  }
+  /**
+   * List namespaces.
+   */
+  async listNamespacesItems(op) {
+    const limit = op.limit ?? 10;
+    const offset = op.offset ?? 0;
+    let query = this.db.collection(this.collection);
+    if (op.matchConditions) {
+      for (const condition of op.matchConditions) {
+        const path = condition.path.filter((p) => p !== "*").join("/");
+        if (condition.matchType === "prefix") {
+          query = query.where("namespaceKey", ">=", path).where("namespaceKey", "<", path + "\uFFFF");
+        }
+      }
+    }
+    const snapshot = await query.get();
+    const namespaceSet = /* @__PURE__ */ new Set();
+    for (const doc of snapshot.docs) {
+      const data = doc.data();
+      const namespace = data.namespace;
+      if (op.maxDepth !== void 0 && namespace.length > op.maxDepth) {
+        namespaceSet.add(namespace.slice(0, op.maxDepth).join("/"));
+      } else {
+        namespaceSet.add(namespace.join("/"));
+      }
+    }
+    const namespaces = Array.from(namespaceSet).map((ns) => ns.split("/")).slice(offset, offset + limit);
+    return namespaces;
+  }
+};
+
+export { FirestoreCheckpointer, FirestoreSessionStore, FirestoreStore, MemorySessionBackend };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map