@lleverage-ai/agent-sdk 0.0.1

package/dist/backends/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/backends/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,gBAAgB,EAEhB,sBAAsB,GAEvB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,iBAAiB,EAEjB,kBAAkB,EAClB,YAAY,GACb,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,uBAAuB,EACvB,aAAa,EAEb,iBAAiB,GAElB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,YAAY,GAEb,MAAM,cAAc,CAAC;AACtB,OAAO,EAEL,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,GAGb,MAAM,YAAY,CAAC"}

package/dist/backends/persistent.d.ts

@@ -0,0 +1,312 @@
+/**
+ * Persistent backend using a pluggable key-value store.
+ *
+ * PersistentBackend provides cross-conversation persistence by storing files
+ * in a key-value store. This enables long-term memory and state preservation
+ * across agent sessions.
+ *
+ * The backend supports any storage system that implements the KeyValueStore
+ * interface, including Redis, SQLite, DynamoDB, or cloud storage.
+ *
+ * @example
+ * ```typescript
+ * // Using the built-in in-memory store (for development)
+ * const store = new InMemoryStore();
+ * const backend = new PersistentBackend({ store });
+ *
+ * // With namespace isolation
+ * const backend = new PersistentBackend({
+ *   store,
+ *   namespace: "user-123",
+ * });
+ *
+ * // Files are persisted across sessions
+ * await backend.write("/notes.md", "# My Notes\n");
+ * // Later, in a new session:
+ * const content = await backend.read("/notes.md");
+ * ```
+ *
+ * @packageDocumentation
+ */
+import type { BackendProtocol, EditResult, FileData, FileInfo, GrepMatch, WriteResult } from "../backend.js";
+/**
+ * Pluggable key-value store interface.
+ *
+ * Implement this interface to add persistence to any storage backend.
+ * The namespace array allows for hierarchical organization of data.
+ *
+ * @example
+ * ```typescript
+ * // Example Redis implementation
+ * class RedisStore implements KeyValueStore {
+ *   private redis: RedisClient;
+ *
+ *   private makeKey(namespace: string[], key: string): string {
+ *     return [...namespace, key].join(":");
+ *   }
+ *
+ *   async get(namespace: string[], key: string) {
+ *     const data = await this.redis.get(this.makeKey(namespace, key));
+ *     return data ? JSON.parse(data) : undefined;
+ *   }
+ *
+ *   async put(namespace: string[], key: string, value: Record<string, unknown>) {
+ *     await this.redis.set(this.makeKey(namespace, key), JSON.stringify(value));
+ *   }
+ *
+ *   async delete(namespace: string[], key: string) {
+ *     await this.redis.del(this.makeKey(namespace, key));
+ *   }
+ *
+ *   async list(namespace: string[]) {
+ *     const pattern = [...namespace, "*"].join(":");
+ *     const keys = await this.redis.keys(pattern);
+ *     return Promise.all(keys.map(async k => ({
+ *       key: k.split(":").pop()!,
+ *       value: JSON.parse(await this.redis.get(k) || "{}"),
+ *     })));
+ *   }
+ * }
+ * ```
+ *
+ * @category Backend
+ */
+export interface KeyValueStore {
+    /**
+     * Get a value by namespace and key.
+     *
+     * @param namespace - Hierarchical namespace array (e.g., ["user-123", "filesystem"])
+     * @param key - The key to retrieve
+     * @returns The value if found, undefined otherwise
+     */
+    get(namespace: string[], key: string): Promise<Record<string, unknown> | undefined>;
+    /**
+     * Store a value at the given namespace and key.
+     *
+     * @param namespace - Hierarchical namespace array
+     * @param key - The key to store at
+     * @param value - The value to store (must be JSON-serializable)
+     */
+    put(namespace: string[], key: string, value: Record<string, unknown>): Promise<void>;
+    /**
+     * Delete a value by namespace and key.
+     *
+     * @param namespace - Hierarchical namespace array
+     * @param key - The key to delete
+     */
+    delete(namespace: string[], key: string): Promise<void>;
+    /**
+     * List all keys and values in a namespace.
+     *
+     * @param namespace - Hierarchical namespace array
+     * @returns Array of key-value pairs in the namespace
+     */
+    list(namespace: string[]): Promise<Array<{
+        key: string;
+        value: Record<string, unknown>;
+    }>>;
+}
+/**
+ * In-memory implementation of KeyValueStore for development and testing.
+ *
+ * Data is stored in a Map and lost when the process ends.
+ * Use this for development or as a reference implementation.
+ *
+ * @example
+ * ```typescript
+ * const store = new InMemoryStore();
+ *
+ * // Store data
+ * await store.put(["app", "users"], "user-1", { name: "Alice" });
+ *
+ * // Retrieve data
+ * const user = await store.get(["app", "users"], "user-1");
+ *
+ * // List all users
+ * const users = await store.list(["app", "users"]);
+ * ```
+ *
+ * @category Backend
+ */
+export declare class InMemoryStore implements KeyValueStore {
+    private data;
+    /**
+     * Create a composite key from namespace and key.
+     * @internal
+     */
+    private makeKey;
+    /**
+     * Parse a composite key to extract namespace and key.
+     * @internal
+     */
+    private parseKey;
+    /**
+     * Check if a composite key starts with the given namespace.
+     * @internal
+     */
+    private startsWithNamespace;
+    get(namespace: string[], key: string): Promise<Record<string, unknown> | undefined>;
+    put(namespace: string[], key: string, value: Record<string, unknown>): Promise<void>;
+    delete(namespace: string[], key: string): Promise<void>;
+    list(namespace: string[]): Promise<Array<{
+        key: string;
+        value: Record<string, unknown>;
+    }>>;
+    /**
+     * Clear all data from the store.
+     *
+     * Useful for testing cleanup.
+     */
+    clear(): void;
+    /**
+     * Get the number of entries in the store.
+     *
+     * Useful for testing.
+     */
+    get size(): number;
+}
+/**
+ * Configuration options for PersistentBackend.
+ *
+ * @category Backend
+ */
+export interface PersistentBackendOptions {
+    /**
+     * The key-value store to use for persistence.
+     */
+    store: KeyValueStore;
+    /**
+     * Optional namespace prefix for all keys.
+     *
+     * Use this to isolate data between different agents, users, or sessions.
+     *
+     * @defaultValue undefined (no namespace prefix)
+     *
+     * @example
+     * ```typescript
+     * // Isolate by user
+     * new PersistentBackend({ store, namespace: "user-123" });
+     *
+     * // Isolate by agent
+     * new PersistentBackend({ store, namespace: "agent-coding" });
+     * ```
+     */
+    namespace?: string;
+}
+/**
+ * Backend implementation using a pluggable key-value store.
+ *
+ * All file operations are persisted to the underlying store, allowing
+ * data to survive across process restarts and agent sessions.
+ *
+ * Files are stored at: [namespace?, "filesystem", encodedPath]
+ *
+ * @example
+ * ```typescript
+ * import { PersistentBackend, InMemoryStore } from "@lleverage-ai/agent-sdk";
+ *
+ * // Create with in-memory store
+ * const store = new InMemoryStore();
+ * const backend = new PersistentBackend({ store });
+ *
+ * // Write persists to store
+ * await backend.write("/notes.md", "# Notes");
+ *
+ * // Read retrieves from store
+ * const content = await backend.read("/notes.md");
+ *
+ * // With namespace for multi-tenant isolation
+ * const userBackend = new PersistentBackend({
+ *   store,
+ *   namespace: "user-456",
+ * });
+ * ```
+ *
+ * @category Backend
+ */
+export declare class PersistentBackend implements BackendProtocol {
+    private readonly store;
+    private readonly namespacePrefix;
+    /**
+     * Create a new PersistentBackend.
+     *
+     * @param options - Configuration options
+     */
+    constructor(options: PersistentBackendOptions);
+    /**
+     * Encode a file path as a safe key.
+     *
+     * File paths may contain characters that are problematic for some
+     * key-value stores. We use base64url encoding for safety.
+     *
+     * @internal
+     */
+    private encodePathAsKey;
+    /**
+     * Decode a key back to a file path.
+     * @internal
+     */
+    private decodeKeyToPath;
+    /**
+     * Normalize a path to ensure consistent format.
+     * @internal
+     */
+    private normalizePath;
+    /**
+     * Get the namespace for a file path.
+     * @internal
+     */
+    private getNamespace;
+    /**
+     * List files and directories at the given path.
+     */
+    lsInfo(path: string): Promise<FileInfo[]>;
+    /**
+     * Read file content with line numbers.
+     */
+    read(filePath: string, offset?: number, limit?: number): Promise<string>;
+    /**
+     * Read raw file content as FileData.
+     */
+    readRaw(filePath: string): Promise<FileData>;
+    /**
+     * Search for pattern matches using regex.
+     */
+    grepRaw(pattern: string, path?: string | null, glob?: string | null): Promise<GrepMatch[]>;
+    /**
+     * Find files matching a glob pattern.
+     */
+    globInfo(pattern: string, path?: string): Promise<FileInfo[]>;
+    /**
+     * Create or overwrite a file.
+     */
+    write(filePath: string, content: string): Promise<WriteResult>;
+    /**
+     * Edit a file by replacing text.
+     */
+    edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<EditResult>;
+    /**
+     * Check if a path matches a glob pattern.
+     * Supports basic glob patterns: *, **, ?
+     * @internal
+     */
+    private matchesGlob;
+}
+/**
+ * Create a new PersistentBackend.
+ *
+ * Convenience function that wraps the PersistentBackend constructor.
+ *
+ * @param options - Configuration options
+ * @returns A new PersistentBackend instance
+ *
+ * @example
+ * ```typescript
+ * const store = new InMemoryStore();
+ * const backend = createPersistentBackend({ store });
+ * ```
+ *
+ * @category Backend
+ */
+export declare function createPersistentBackend(options: PersistentBackendOptions): PersistentBackend;
+//# sourceMappingURL=persistent.d.ts.map

package/dist/backends/persistent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistent.d.ts","sourceRoot":"","sources":["../../src/backends/persistent.ts"],"names":[],"mappings":"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"}