@lleverage-ai/agent-sdk 0.0.1

package/dist/checkpointer/file-saver.d.ts

@@ -0,0 +1,182 @@
+/**
+ * File-based checkpoint saver for JSON persistence.
+ *
+ * FileSaver stores checkpoints as JSON files on disk, providing:
+ * - Persistence across process restarts
+ * - Human-readable checkpoint data
+ * - Simple backup and debugging capabilities
+ *
+ * Each checkpoint is stored as a separate JSON file: `{dir}/{threadId}.json`
+ *
+ * @example
+ * ```typescript
+ * const saver = new FileSaver({ dir: "./.checkpoints" });
+ *
+ * // Save a checkpoint
+ * await saver.save(checkpoint);
+ * // Creates: .checkpoints/session-123.json
+ *
+ * // Load it back
+ * const loaded = await saver.load("session-123");
+ * ```
+ *
+ * @packageDocumentation
+ */
+import type { BaseCheckpointSaver, Checkpoint, CheckpointSaverOptions } from "./types.js";
+/**
+ * Options for creating a FileSaver.
+ *
+ * @category Checkpointer
+ */
+export interface FileSaverOptions extends CheckpointSaverOptions {
+    /**
+     * Directory path for storing checkpoint files.
+     *
+     * The directory will be created if it doesn't exist.
+     */
+    dir: string;
+    /**
+     * File extension for checkpoint files.
+     * @defaultValue ".json"
+     */
+    extension?: string;
+    /**
+     * Whether to format JSON with indentation for readability.
+     * @defaultValue true
+     */
+    pretty?: boolean;
+}
+/**
+ * File-based checkpoint saver using JSON files.
+ *
+ * Stores each checkpoint as a separate JSON file in the specified directory.
+ * Thread IDs are sanitized to create safe filenames.
+ *
+ * @example
+ * ```typescript
+ * const saver = new FileSaver({ dir: "./.checkpoints" });
+ *
+ * // Save multiple checkpoints
+ * await saver.save(checkpoint1);
+ * await saver.save(checkpoint2);
+ *
+ * // List all threads
+ * const threads = await saver.list();
+ * // ["session-1", "session-2"]
+ *
+ * // Clean up
+ * for (const thread of threads) {
+ *   await saver.delete(thread);
+ * }
+ * ```
+ *
+ * @category Checkpointer
+ */
+export declare class FileSaver implements BaseCheckpointSaver {
+    private readonly dir;
+    private readonly extension;
+    private readonly pretty;
+    private readonly namespace?;
+    private initialized;
+    /**
+     * Create a new FileSaver.
+     *
+     * @param options - Configuration including the directory path
+     */
+    constructor(options: FileSaverOptions);
+    /**
+     * Save a checkpoint to a JSON file.
+     *
+     * Creates the directory if it doesn't exist.
+     * Overwrites existing checkpoint with the same threadId.
+     *
+     * @param checkpoint - The checkpoint to save
+     */
+    save(checkpoint: Checkpoint): Promise<void>;
+    /**
+     * Load a checkpoint from a JSON file.
+     *
+     * @param threadId - The thread ID to load
+     * @returns The checkpoint if found and valid, undefined otherwise
+     */
+    load(threadId: string): Promise<Checkpoint | undefined>;
+    /**
+     * List all thread IDs that have checkpoint files.
+     *
+     * @returns Array of thread IDs
+     */
+    list(): Promise<string[]>;
+    /**
+     * Delete a checkpoint file.
+     *
+     * @param threadId - The thread ID to delete
+     * @returns True if a file was deleted, false if not found
+     */
+    delete(threadId: string): Promise<boolean>;
+    /**
+     * Check if a checkpoint file exists.
+     *
+     * @param threadId - The thread ID to check
+     * @returns True if the file exists
+     */
+    exists(threadId: string): Promise<boolean>;
+    /**
+     * Get the directory path where checkpoints are stored.
+     */
+    getDir(): string;
+    /**
+     * Get the full file path for a thread ID.
+     *
+     * @param threadId - The thread ID
+     * @returns The full file path
+     */
+    getFilePath(threadId: string): string;
+    /**
+     * Ensure the checkpoint directory exists.
+     * @internal
+     */
+    private ensureInitialized;
+    /**
+     * Convert a thread ID to a safe filename.
+     *
+     * Sanitizes the thread ID to remove or replace characters that are
+     * problematic in filenames across different operating systems.
+     *
+     * @internal
+     */
+    private threadIdToFile;
+    /**
+     * Convert a filename back to a thread ID.
+     *
+     * @internal
+     */
+    private fileToThreadId;
+}
+/**
+ * Create a new FileSaver instance.
+ *
+ * @param options - Configuration including the directory path
+ * @returns A new FileSaver instance
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const saver = createFileSaver({ dir: "./.checkpoints" });
+ *
+ * // With namespace for multi-tenant isolation
+ * const userSaver = createFileSaver({
+ *   dir: "./.checkpoints",
+ *   namespace: "user-123",
+ * });
+ *
+ * // Compact JSON (no pretty printing)
+ * const compactSaver = createFileSaver({
+ *   dir: "./.checkpoints",
+ *   pretty: false,
+ * });
+ * ```
+ *
+ * @category Checkpointer
+ */
+export declare function createFileSaver(options: FileSaverOptions): FileSaver;
+//# sourceMappingURL=file-saver.d.ts.map

package/dist/checkpointer/file-saver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-saver.d.ts","sourceRoot":"","sources":["../../src/checkpointer/file-saver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAO1F;;;;GAIG;AACH,MAAM,WAAW,gBAAiB,SAAQ,sBAAsB;IAC9D;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,SAAU,YAAW,mBAAmB;IACnD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;IACpC,OAAO,CAAC,WAAW,CAAS;IAE5B;;;;OAIG;gBACS,OAAO,EAAE,gBAAgB;IAOrC;;;;;;;OAOG;IACG,IAAI,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IASjD;;;;;OAKG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAuB7D;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IA0B/B;;;;;OAKG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAchD;;;;;OAKG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAehD;;OAEG;IACH,MAAM,IAAI,MAAM;IAIhB;;;;;OAKG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IASrC;;;OAGG;YACW,iBAAiB;IAiB/B;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IAmBtB;;;;OAIG;IACH,OAAO,CAAC,cAAc;CAqBvB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CAEpE"}

package/dist/checkpointer/file-saver.js

@@ -0,0 +1,298 @@
+/**
+ * File-based checkpoint saver for JSON persistence.
+ *
+ * FileSaver stores checkpoints as JSON files on disk, providing:
+ * - Persistence across process restarts
+ * - Human-readable checkpoint data
+ * - Simple backup and debugging capabilities
+ *
+ * Each checkpoint is stored as a separate JSON file: `{dir}/{threadId}.json`
+ *
+ * @example
+ * ```typescript
+ * const saver = new FileSaver({ dir: "./.checkpoints" });
+ *
+ * // Save a checkpoint
+ * await saver.save(checkpoint);
+ * // Creates: .checkpoints/session-123.json
+ *
+ * // Load it back
+ * const loaded = await saver.load("session-123");
+ * ```
+ *
+ * @packageDocumentation
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { isCheckpoint } from "./types.js";
+// =============================================================================
+// FileSaver Implementation
+// =============================================================================
+/**
+ * File-based checkpoint saver using JSON files.
+ *
+ * Stores each checkpoint as a separate JSON file in the specified directory.
+ * Thread IDs are sanitized to create safe filenames.
+ *
+ * @example
+ * ```typescript
+ * const saver = new FileSaver({ dir: "./.checkpoints" });
+ *
+ * // Save multiple checkpoints
+ * await saver.save(checkpoint1);
+ * await saver.save(checkpoint2);
+ *
+ * // List all threads
+ * const threads = await saver.list();
+ * // ["session-1", "session-2"]
+ *
+ * // Clean up
+ * for (const thread of threads) {
+ *   await saver.delete(thread);
+ * }
+ * ```
+ *
+ * @category Checkpointer
+ */
+export class FileSaver {
+    dir;
+    extension;
+    pretty;
+    namespace;
+    initialized = false;
+    /**
+     * Create a new FileSaver.
+     *
+     * @param options - Configuration including the directory path
+     */
+    constructor(options) {
+        this.dir = path.resolve(options.dir);
+        this.extension = options.extension ?? ".json";
+        this.pretty = options.pretty ?? true;
+        this.namespace = options.namespace;
+    }
+    /**
+     * Save a checkpoint to a JSON file.
+     *
+     * Creates the directory if it doesn't exist.
+     * Overwrites existing checkpoint with the same threadId.
+     *
+     * @param checkpoint - The checkpoint to save
+     */
+    async save(checkpoint) {
+        await this.ensureInitialized();
+        const filePath = this.getFilePath(checkpoint.threadId);
+        const data = this.pretty ? JSON.stringify(checkpoint, null, 2) : JSON.stringify(checkpoint);
+        await fs.writeFile(filePath, data, "utf-8");
+    }
+    /**
+     * Load a checkpoint from a JSON file.
+     *
+     * @param threadId - The thread ID to load
+     * @returns The checkpoint if found and valid, undefined otherwise
+     */
+    async load(threadId) {
+        const filePath = this.getFilePath(threadId);
+        try {
+            const data = await fs.readFile(filePath, "utf-8");
+            const parsed = JSON.parse(data);
+            // Validate the parsed data
+            if (!isCheckpoint(parsed)) {
+                console.warn(`Invalid checkpoint data in ${filePath}, expected Checkpoint object`);
+                return undefined;
+            }
+            return parsed;
+        }
+        catch (error) {
+            // File not found or read error
+            if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+                return undefined;
+            }
+            throw error;
+        }
+    }
+    /**
+     * List all thread IDs that have checkpoint files.
+     *
+     * @returns Array of thread IDs
+     */
+    async list() {
+        await this.ensureInitialized();
+        try {
+            const files = await fs.readdir(this.dir);
+            const threads = [];
+            for (const file of files) {
+                if (file.endsWith(this.extension)) {
+                    const threadId = this.fileToThreadId(file);
+                    if (threadId) {
+                        threads.push(threadId);
+                    }
+                }
+            }
+            return threads;
+        }
+        catch (error) {
+            // Directory doesn't exist yet
+            if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+                return [];
+            }
+            throw error;
+        }
+    }
+    /**
+     * Delete a checkpoint file.
+     *
+     * @param threadId - The thread ID to delete
+     * @returns True if a file was deleted, false if not found
+     */
+    async delete(threadId) {
+        const filePath = this.getFilePath(threadId);
+        try {
+            await fs.unlink(filePath);
+            return true;
+        }
+        catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+                return false;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Check if a checkpoint file exists.
+     *
+     * @param threadId - The thread ID to check
+     * @returns True if the file exists
+     */
+    async exists(threadId) {
+        const filePath = this.getFilePath(threadId);
+        try {
+            await fs.access(filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // ===========================================================================
+    // Additional Utility Methods
+    // ===========================================================================
+    /**
+     * Get the directory path where checkpoints are stored.
+     */
+    getDir() {
+        return this.dir;
+    }
+    /**
+     * Get the full file path for a thread ID.
+     *
+     * @param threadId - The thread ID
+     * @returns The full file path
+     */
+    getFilePath(threadId) {
+        const filename = this.threadIdToFile(threadId);
+        return path.join(this.dir, filename);
+    }
+    // ===========================================================================
+    // Private Helpers
+    // ===========================================================================
+    /**
+     * Ensure the checkpoint directory exists.
+     * @internal
+     */
+    async ensureInitialized() {
+        if (this.initialized) {
+            return;
+        }
+        try {
+            await fs.mkdir(this.dir, { recursive: true });
+        }
+        catch (error) {
+            // Directory already exists is fine
+            if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) {
+                throw error;
+            }
+        }
+        this.initialized = true;
+    }
+    /**
+     * Convert a thread ID to a safe filename.
+     *
+     * Sanitizes the thread ID to remove or replace characters that are
+     * problematic in filenames across different operating systems.
+     *
+     * @internal
+     */
+    threadIdToFile(threadId) {
+        // Apply namespace prefix if configured
+        const prefixed = this.namespace ? `${this.namespace}_${threadId}` : threadId;
+        // Replace problematic characters with underscores
+        // Keep: alphanumeric, dash, underscore, dot
+        // Replace: slashes, colons, special chars
+        const sanitized = prefixed
+            .replace(/[/\\:*?"<>|]/g, "_")
+            .replace(/\s+/g, "_")
+            .replace(/_+/g, "_") // Collapse multiple underscores
+            .replace(/^_|_$/g, ""); // Trim leading/trailing underscores
+        // Ensure we have a valid filename
+        const filename = sanitized || "checkpoint";
+        return `${filename}${this.extension}`;
+    }
+    /**
+     * Convert a filename back to a thread ID.
+     *
+     * @internal
+     */
+    fileToThreadId(filename) {
+        if (!filename.endsWith(this.extension)) {
+            return undefined;
+        }
+        // Remove extension
+        let threadId = filename.slice(0, -this.extension.length);
+        // Remove namespace prefix if configured
+        if (this.namespace) {
+            const prefix = `${this.namespace}_`;
+            if (threadId.startsWith(prefix)) {
+                threadId = threadId.slice(prefix.length);
+            }
+            else {
+                // File doesn't belong to this namespace
+                return undefined;
+            }
+        }
+        return threadId || undefined;
+    }
+}
+// =============================================================================
+// Factory Function
+// =============================================================================
+/**
+ * Create a new FileSaver instance.
+ *
+ * @param options - Configuration including the directory path
+ * @returns A new FileSaver instance
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const saver = createFileSaver({ dir: "./.checkpoints" });
+ *
+ * // With namespace for multi-tenant isolation
+ * const userSaver = createFileSaver({
+ *   dir: "./.checkpoints",
+ *   namespace: "user-123",
+ * });
+ *
+ * // Compact JSON (no pretty printing)
+ * const compactSaver = createFileSaver({
+ *   dir: "./.checkpoints",
+ *   pretty: false,
+ * });
+ * ```
+ *
+ * @category Checkpointer
+ */
+export function createFileSaver(options) {
+    return new FileSaver(options);
+}
+//# sourceMappingURL=file-saver.js.map

package/dist/checkpointer/file-saver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-saver.js","sourceRoot":"","sources":["../../src/checkpointer/file-saver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAgC1C,gFAAgF;AAChF,2BAA2B;AAC3B,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,OAAO,SAAS;IACH,GAAG,CAAS;IACZ,SAAS,CAAS;IAClB,MAAM,CAAU;IAChB,SAAS,CAAU;IAC5B,WAAW,GAAG,KAAK,CAAC;IAE5B;;;;OAIG;IACH,YAAY,OAAyB;QACnC,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC;QAC9C,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC;QACrC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACrC,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI,CAAC,UAAsB;QAC/B,MAAM,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAE/B,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;QACvD,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;QAE5F,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAC9C,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,IAAI,CAAC,QAAgB;QACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;QAE5C,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAClD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAEhC,2BAA2B;YAC3B,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC1B,OAAO,CAAC,IAAI,CAAC,8BAA8B,QAAQ,8BAA8B,CAAC,CAAC;gBACnF,OAAO,SAAS,CAAC;YACnB,CAAC;YAED,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,+BAA+B;YAC/B,IAAI,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACzE,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,IAAI;QACR,MAAM,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAE/B,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACzC,MAAM,OAAO,GAAa,EAAE,CAAC;YAE7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;oBAClC,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;oBAC3C,IAAI,QAAQ,EAAE,CAAC;wBACb,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;oBACzB,CAAC;gBACH,CAAC;YACH,CAAC;YAED,OAAO,OAAO,CAAC;QACjB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,8BAA8B;YAC9B,IAAI,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACzE,OAAO,EAAE,CAAC;YACZ,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,MAAM,CAAC,QAAgB;QAC3B,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;QAE5C,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC1B,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACzE,OAAO,KAAK,CAAC;YACf,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,MAAM,CAAC,QAAgB;QAC3B,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;QAE5C,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC1B,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,8EAA8E;IAC9E,6BAA6B;IAC7B,8EAA8E;IAE9E;;OAEG;IACH,MAAM;QACJ,OAAO,IAAI,CAAC,GAAG,CAAC;IAClB,CAAC;IAED;;;;;OAKG;IACH,WAAW,CAAC,QAAgB;QAC1B,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;QAC/C,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED,8EAA8E;IAC9E,kBAAkB;IAClB,8EAA8E;IAE9E;;;OAGG;IACK,KAAK,CAAC,iBAAiB;QAC7B,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,OAAO;QACT,CAAC;QAED,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,mCAAmC;YACnC,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,EAAE,CAAC;gBAC5E,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;QAED,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;IAC1B,CAAC;IAED;;;;;;;OAOG;IACK,cAAc,CAAC,QAAgB;QACrC,uCAAuC;QACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,IAAI,QAAQ,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;QAE7E,kDAAkD;QAClD,4CAA4C;QAC5C,0CAA0C;QAC1C,MAAM,SAAS,GAAG,QAAQ;aACvB,OAAO,CAAC,eAAe,EAAE,GAAG,CAAC;aAC7B,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;aACpB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,gCAAgC;aACpD,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,oCAAoC;QAE9D,kCAAkC;QAClC,MAAM,QAAQ,GAAG,SAAS,IAAI,YAAY,CAAC;QAE3C,OAAO,GAAG,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;IACxC,CAAC;IAED;;;;OAIG;IACK,cAAc,CAAC,QAAgB;QACrC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YACvC,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,mBAAmB;QACnB,IAAI,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAEzD,wCAAwC;QACxC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,MAAM,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,GAAG,CAAC;YACpC,IAAI,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;gBAChC,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC3C,CAAC;iBAAM,CAAC;gBACN,wCAAwC;gBACxC,OAAO,SAAS,CAAC;YACnB,CAAC;QACH,CAAC;QAED,OAAO,QAAQ,IAAI,SAAS,CAAC;IAC/B,CAAC;CACF;AAED,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,eAAe,CAAC,OAAyB;IACvD,OAAO,IAAI,SAAS,CAAC,OAAO,CAAC,CAAC;AAChC,CAAC"}

package/dist/checkpointer/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Checkpointer system for session persistence and resumption.
+ *
+ * This module provides tools for saving and restoring agent sessions,
+ * enabling:
+ * - Cross-conversation persistence
+ * - Session resumption after process restart
+ * - Tool approval interrupts
+ *
+ * ## Available Savers
+ *
+ * - **MemorySaver** - In-memory storage (ephemeral, for testing/development)
+ * - **FileSaver** - JSON file storage (persistent, human-readable)
+ * - **KeyValueStoreSaver** - Adapter for any KeyValueStore implementation
+ *
+ * @example
+ * ```typescript
+ * import { MemorySaver, FileSaver, KeyValueStoreSaver } from "@lleverage-ai/agent-sdk";
+ *
+ * // For testing
+ * const memorySaver = new MemorySaver();
+ *
+ * // For persistence
+ * const fileSaver = new FileSaver({ dir: "./.checkpoints" });
+ *
+ * // For custom storage (Redis, SQLite, etc.)
+ * const kvSaver = new KeyValueStoreSaver({ store: myCustomStore });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export type { FileSaverOptions } from "./file-saver.js";
+export { createFileSaver, FileSaver } from "./file-saver.js";
+export type { KeyValueStoreSaverOptions } from "./kv-saver.js";
+export { createKeyValueStoreSaver, KeyValueStoreSaver } from "./kv-saver.js";
+export type { MemorySaverOptions } from "./memory-saver.js";
+export { createMemorySaver, MemorySaver } from "./memory-saver.js";
+export type { ApprovalInterrupt, ApprovalRequest, ApprovalResponse, BaseCheckpointSaver, Checkpoint, CheckpointEvent, CheckpointLoadedEvent, CheckpointSavedEvent, CheckpointSaverOptions, Interrupt, } from "./types.js";
+export { createApprovalInterrupt, createCheckpoint, createInterrupt, isApprovalInterrupt, isCheckpoint, isInterrupt, updateCheckpoint, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/checkpointer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/checkpointer/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC7D,YAAY,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAE/D,OAAO,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC7E,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACnE,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,UAAU,EACV,eAAe,EACf,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,SAAS,GACV,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,uBAAuB,EACvB,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,YAAY,EACZ,WAAW,EACX,gBAAgB,GACjB,MAAM,YAAY,CAAC"}

package/dist/checkpointer/index.js

@@ -0,0 +1,40 @@
+/**
+ * Checkpointer system for session persistence and resumption.
+ *
+ * This module provides tools for saving and restoring agent sessions,
+ * enabling:
+ * - Cross-conversation persistence
+ * - Session resumption after process restart
+ * - Tool approval interrupts
+ *
+ * ## Available Savers
+ *
+ * - **MemorySaver** - In-memory storage (ephemeral, for testing/development)
+ * - **FileSaver** - JSON file storage (persistent, human-readable)
+ * - **KeyValueStoreSaver** - Adapter for any KeyValueStore implementation
+ *
+ * @example
+ * ```typescript
+ * import { MemorySaver, FileSaver, KeyValueStoreSaver } from "@lleverage-ai/agent-sdk";
+ *
+ * // For testing
+ * const memorySaver = new MemorySaver();
+ *
+ * // For persistence
+ * const fileSaver = new FileSaver({ dir: "./.checkpoints" });
+ *
+ * // For custom storage (Redis, SQLite, etc.)
+ * const kvSaver = new KeyValueStoreSaver({ store: myCustomStore });
+ * ```
+ *
+ * @packageDocumentation
+ */
+// File Saver
+export { createFileSaver, FileSaver } from "./file-saver.js";
+// KeyValueStore Saver
+export { createKeyValueStoreSaver, KeyValueStoreSaver } from "./kv-saver.js";
+// Memory Saver
+export { createMemorySaver, MemorySaver } from "./memory-saver.js";
+// Types
+export { createApprovalInterrupt, createCheckpoint, createInterrupt, isApprovalInterrupt, isCheckpoint, isInterrupt, updateCheckpoint, } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/checkpointer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/checkpointer/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,aAAa;AACb,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE7D,sBAAsB;AACtB,OAAO,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAE7E,eAAe;AACf,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAanE,QAAQ;AACR,OAAO,EACL,uBAAuB,EACvB,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,YAAY,EACZ,WAAW,EACX,gBAAgB,GACjB,MAAM,YAAY,CAAC"}