@compilr-dev/agents 0.0.1

package/dist/state/checkpointer.js

@@ -0,0 +1,362 @@
+/**
+ * Checkpointer Implementations
+ *
+ * Built-in checkpointers for state persistence.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { JsonSerializer, defaultSerializer } from './serializer.js';
+import { StateError } from './errors.js';
+// ============================================================
+// Helper Functions
+// ============================================================
+/**
+ * Extract preview text from a message
+ */
+function getMessagePreview(content, maxLength = 100) {
+    if (typeof content === 'string') {
+        return content.length > maxLength ? content.substring(0, maxLength) + '...' : content;
+    }
+    if (Array.isArray(content)) {
+        // Find first text block
+        for (const block of content) {
+            if (block && typeof block === 'object') {
+                const typedBlock = block;
+                if (typedBlock.type === 'text' && typeof typedBlock.text === 'string') {
+                    const text = typedBlock.text;
+                    return text.length > maxLength ? text.substring(0, maxLength) + '...' : text;
+                }
+            }
+        }
+    }
+    return '';
+}
+/**
+ * Build session metadata from state
+ */
+function buildMetadata(state, overrides) {
+    // Find last user and assistant messages
+    let lastUserMessage;
+    let lastAssistantMessage;
+    for (let i = state.messages.length - 1; i >= 0; i--) {
+        const msg = state.messages[i];
+        if (!lastUserMessage && msg.role === 'user') {
+            lastUserMessage = getMessagePreview(msg.content);
+        }
+        if (!lastAssistantMessage && msg.role === 'assistant') {
+            lastAssistantMessage = getMessagePreview(msg.content);
+        }
+        if (lastUserMessage && lastAssistantMessage)
+            break;
+    }
+    return {
+        sessionId: state.sessionId,
+        createdAt: state.createdAt,
+        updatedAt: state.updatedAt,
+        messageCount: state.messages.length,
+        lastUserMessage,
+        lastAssistantMessage,
+        ...overrides,
+    };
+}
+/**
+ * Convert metadata to session info
+ */
+function toSessionInfo(metadata) {
+    return {
+        sessionId: metadata.sessionId,
+        name: metadata.name,
+        createdAt: metadata.createdAt,
+        updatedAt: metadata.updatedAt,
+        messageCount: metadata.messageCount,
+        preview: metadata.lastAssistantMessage || metadata.lastUserMessage,
+        tags: metadata.tags,
+    };
+}
+/**
+ * Validate session ID format
+ */
+function validateSessionId(sessionId) {
+    if (!sessionId || typeof sessionId !== 'string') {
+        throw StateError.invalidSessionId(sessionId);
+    }
+    // Allow alphanumeric, hyphens, underscores
+    if (!/^[a-zA-Z0-9_-]+$/.test(sessionId)) {
+        throw StateError.invalidSessionId(sessionId);
+    }
+    // Max length check
+    if (sessionId.length > 128) {
+        throw StateError.invalidSessionId(`Session ID too long: ${sessionId.substring(0, 20)}...`);
+    }
+}
+// ============================================================
+// Memory Checkpointer
+// ============================================================
+/**
+ * In-memory checkpointer for development and testing.
+ * State is lost when the process exits.
+ */
+export class MemoryCheckpointer {
+    sessions = new Map();
+    /**
+     * Save state to memory
+     *
+     * Pre-validates state before saving to prevent corrupted checkpoints.
+     * This catches issues like invalid data types that would fail on reload.
+     */
+    save(sessionId, state, metadataOverrides) {
+        validateSessionId(sessionId);
+        // Pre-checkpoint validation: validate state BEFORE saving
+        // This prevents corrupted checkpoints that can't be loaded later
+        // (See LangGraph issue #6491)
+        defaultSerializer.validate(state);
+        const metadata = buildMetadata(state, metadataOverrides);
+        this.sessions.set(sessionId, { state: { ...state }, metadata });
+        return Promise.resolve();
+    }
+    /**
+     * Load state from memory
+     */
+    load(sessionId) {
+        validateSessionId(sessionId);
+        const entry = this.sessions.get(sessionId);
+        return Promise.resolve(entry ? { ...entry.state } : null);
+    }
+    /**
+     * List all sessions
+     */
+    list(options) {
+        let sessions = Array.from(this.sessions.values()).map((entry) => toSessionInfo(entry.metadata));
+        // Filter by tags
+        if (options?.tags?.length) {
+            const tags = options.tags;
+            sessions = sessions.filter((s) => tags.every((tag) => s.tags?.includes(tag)));
+        }
+        // Sort
+        const orderBy = options?.orderBy ?? 'updatedAt';
+        const order = options?.order ?? 'desc';
+        sessions.sort((a, b) => {
+            const aDate = new Date(a[orderBy]).getTime();
+            const bDate = new Date(b[orderBy]).getTime();
+            return order === 'desc' ? bDate - aDate : aDate - bDate;
+        });
+        // Pagination
+        const offset = options?.offset ?? 0;
+        const limit = options?.limit ?? sessions.length;
+        return Promise.resolve(sessions.slice(offset, offset + limit));
+    }
+    /**
+     * Delete a session
+     */
+    delete(sessionId) {
+        validateSessionId(sessionId);
+        return Promise.resolve(this.sessions.delete(sessionId));
+    }
+    /**
+     * Check if session exists
+     */
+    exists(sessionId) {
+        validateSessionId(sessionId);
+        return Promise.resolve(this.sessions.has(sessionId));
+    }
+    /**
+     * Get session metadata
+     */
+    getMetadata(sessionId) {
+        validateSessionId(sessionId);
+        const entry = this.sessions.get(sessionId);
+        return Promise.resolve(entry ? { ...entry.metadata } : null);
+    }
+    /**
+     * Clear all sessions (useful for testing)
+     */
+    clear() {
+        this.sessions.clear();
+    }
+    /**
+     * Get current session count
+     */
+    get size() {
+        return this.sessions.size;
+    }
+}
+/**
+ * File-based checkpointer for simple persistence.
+ * Stores each session as a separate JSON file.
+ */
+export class FileCheckpointer {
+    baseDir;
+    serializer;
+    extension;
+    constructor(baseDir, options) {
+        this.baseDir = baseDir;
+        this.serializer = options?.serializer || new JsonSerializer();
+        this.extension = options?.extension || '.json';
+    }
+    /**
+     * Get file path for a session
+     */
+    getStatePath(sessionId) {
+        return path.join(this.baseDir, `${sessionId}${this.extension}`);
+    }
+    /**
+     * Get metadata file path for a session
+     */
+    getMetadataPath(sessionId) {
+        return path.join(this.baseDir, `${sessionId}.meta${this.extension}`);
+    }
+    /**
+     * Ensure base directory exists
+     */
+    async ensureDir() {
+        try {
+            await fs.mkdir(this.baseDir, { recursive: true });
+        }
+        catch (error) {
+            throw StateError.storage(`Failed to create directory: ${this.baseDir}`, error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * Save state to file
+     *
+     * Pre-validates state before saving to prevent corrupted checkpoints.
+     * This catches issues like invalid data types that would fail on reload.
+     */
+    async save(sessionId, state, metadataOverrides) {
+        validateSessionId(sessionId);
+        // Pre-checkpoint validation: validate state BEFORE saving
+        // This prevents corrupted checkpoints that can't be loaded later
+        // (See LangGraph issue #6491)
+        this.serializer.validate(state);
+        await this.ensureDir();
+        const metadata = buildMetadata(state, metadataOverrides);
+        try {
+            // Save state
+            const stateData = this.serializer.serialize(state);
+            await fs.writeFile(this.getStatePath(sessionId), stateData, 'utf-8');
+            // Save metadata separately for fast listing
+            const metaData = JSON.stringify(metadata, null, 2);
+            await fs.writeFile(this.getMetadataPath(sessionId), metaData, 'utf-8');
+        }
+        catch (error) {
+            throw StateError.storage(`Failed to save session: ${sessionId}`, error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * Load state from file
+     */
+    async load(sessionId) {
+        validateSessionId(sessionId);
+        try {
+            const data = await fs.readFile(this.getStatePath(sessionId), 'utf-8');
+            return this.serializer.deserialize(data);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return null;
+            }
+            throw StateError.storage(`Failed to load session: ${sessionId}`, error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * List all sessions
+     */
+    async list(options) {
+        try {
+            await this.ensureDir();
+            const files = await fs.readdir(this.baseDir);
+            // Find all metadata files
+            const metaFiles = files.filter((f) => f.endsWith(`.meta${this.extension}`));
+            let sessions = [];
+            for (const file of metaFiles) {
+                try {
+                    const metaPath = path.join(this.baseDir, file);
+                    const data = await fs.readFile(metaPath, 'utf-8');
+                    const metadata = JSON.parse(data);
+                    sessions.push(toSessionInfo(metadata));
+                }
+                catch {
+                    // Skip invalid metadata files
+                }
+            }
+            // Filter by tags
+            if (options?.tags?.length) {
+                const tags = options.tags;
+                sessions = sessions.filter((s) => tags.every((tag) => s.tags?.includes(tag)));
+            }
+            // Sort
+            const orderBy = options?.orderBy ?? 'updatedAt';
+            const order = options?.order ?? 'desc';
+            sessions.sort((a, b) => {
+                const aDate = new Date(a[orderBy]).getTime();
+                const bDate = new Date(b[orderBy]).getTime();
+                return order === 'desc' ? bDate - aDate : aDate - bDate;
+            });
+            // Pagination
+            const offset = options?.offset || 0;
+            const limit = options?.limit || sessions.length;
+            return sessions.slice(offset, offset + limit);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return [];
+            }
+            throw StateError.storage('Failed to list sessions', error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * Delete a session
+     */
+    async delete(sessionId) {
+        validateSessionId(sessionId);
+        let deleted = false;
+        try {
+            await fs.unlink(this.getStatePath(sessionId));
+            deleted = true;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw StateError.storage(`Failed to delete session state: ${sessionId}`, error instanceof Error ? error : undefined);
+            }
+        }
+        try {
+            await fs.unlink(this.getMetadataPath(sessionId));
+            deleted = true;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw StateError.storage(`Failed to delete session metadata: ${sessionId}`, error instanceof Error ? error : undefined);
+            }
+        }
+        return deleted;
+    }
+    /**
+     * Check if session exists
+     */
+    async exists(sessionId) {
+        validateSessionId(sessionId);
+        try {
+            await fs.access(this.getStatePath(sessionId));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get session metadata
+     */
+    async getMetadata(sessionId) {
+        validateSessionId(sessionId);
+        try {
+            const data = await fs.readFile(this.getMetadataPath(sessionId), 'utf-8');
+            return JSON.parse(data);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return null;
+            }
+            throw StateError.storage(`Failed to load session metadata: ${sessionId}`, error instanceof Error ? error : undefined);
+        }
+    }
+}

package/dist/state/errors.d.ts

@@ -0,0 +1,66 @@
+/**
+ * State Management Errors
+ *
+ * Custom error types for state serialization and persistence.
+ */
+/**
+ * Error codes for state management operations.
+ */
+export declare enum StateErrorCode {
+    /** Failed to serialize state to string */
+    SERIALIZATION_FAILED = "SERIALIZATION_FAILED",
+    /** Failed to deserialize string to state */
+    DESERIALIZATION_FAILED = "DESERIALIZATION_FAILED",
+    /** Session not found in storage */
+    SESSION_NOT_FOUND = "SESSION_NOT_FOUND",
+    /** Storage operation failed (I/O, permissions, etc.) */
+    STORAGE_ERROR = "STORAGE_ERROR",
+    /** State version mismatch (needs migration) */
+    VERSION_MISMATCH = "VERSION_MISMATCH",
+    /** Invalid state structure */
+    INVALID_STATE = "INVALID_STATE",
+    /** Session ID format is invalid */
+    INVALID_SESSION_ID = "INVALID_SESSION_ID"
+}
+/**
+ * Base error class for state management operations.
+ */
+export declare class StateError extends Error {
+    /**
+     * Error code for programmatic handling
+     */
+    readonly code: StateErrorCode;
+    /**
+     * Original error that caused this error (if any)
+     */
+    readonly cause?: Error;
+    constructor(message: string, code: StateErrorCode, cause?: Error);
+    /**
+     * Create a serialization error
+     */
+    static serialization(message: string, cause?: Error): StateError;
+    /**
+     * Create a deserialization error
+     */
+    static deserialization(message: string, cause?: Error): StateError;
+    /**
+     * Create a session not found error
+     */
+    static sessionNotFound(sessionId: string): StateError;
+    /**
+     * Create a storage error
+     */
+    static storage(message: string, cause?: Error): StateError;
+    /**
+     * Create a version mismatch error
+     */
+    static versionMismatch(expected: number, actual: number): StateError;
+    /**
+     * Create an invalid state error
+     */
+    static invalidState(message: string): StateError;
+    /**
+     * Create an invalid session ID error
+     */
+    static invalidSessionId(sessionId: string): StateError;
+}

package/dist/state/errors.js

@@ -0,0 +1,88 @@
+/**
+ * State Management Errors
+ *
+ * Custom error types for state serialization and persistence.
+ */
+/**
+ * Error codes for state management operations.
+ */
+export var StateErrorCode;
+(function (StateErrorCode) {
+    /** Failed to serialize state to string */
+    StateErrorCode["SERIALIZATION_FAILED"] = "SERIALIZATION_FAILED";
+    /** Failed to deserialize string to state */
+    StateErrorCode["DESERIALIZATION_FAILED"] = "DESERIALIZATION_FAILED";
+    /** Session not found in storage */
+    StateErrorCode["SESSION_NOT_FOUND"] = "SESSION_NOT_FOUND";
+    /** Storage operation failed (I/O, permissions, etc.) */
+    StateErrorCode["STORAGE_ERROR"] = "STORAGE_ERROR";
+    /** State version mismatch (needs migration) */
+    StateErrorCode["VERSION_MISMATCH"] = "VERSION_MISMATCH";
+    /** Invalid state structure */
+    StateErrorCode["INVALID_STATE"] = "INVALID_STATE";
+    /** Session ID format is invalid */
+    StateErrorCode["INVALID_SESSION_ID"] = "INVALID_SESSION_ID";
+})(StateErrorCode || (StateErrorCode = {}));
+/**
+ * Base error class for state management operations.
+ */
+export class StateError extends Error {
+    /**
+     * Error code for programmatic handling
+     */
+    code;
+    /**
+     * Original error that caused this error (if any)
+     */
+    cause;
+    constructor(message, code, cause) {
+        super(message);
+        this.name = 'StateError';
+        this.code = code;
+        this.cause = cause;
+        // Maintain proper stack trace for where error was thrown (V8)
+        Error.captureStackTrace(this, StateError);
+    }
+    /**
+     * Create a serialization error
+     */
+    static serialization(message, cause) {
+        return new StateError(`Serialization failed: ${message}`, StateErrorCode.SERIALIZATION_FAILED, cause);
+    }
+    /**
+     * Create a deserialization error
+     */
+    static deserialization(message, cause) {
+        return new StateError(`Deserialization failed: ${message}`, StateErrorCode.DESERIALIZATION_FAILED, cause);
+    }
+    /**
+     * Create a session not found error
+     */
+    static sessionNotFound(sessionId) {
+        return new StateError(`Session not found: ${sessionId}`, StateErrorCode.SESSION_NOT_FOUND);
+    }
+    /**
+     * Create a storage error
+     */
+    static storage(message, cause) {
+        return new StateError(`Storage error: ${message}`, StateErrorCode.STORAGE_ERROR, cause);
+    }
+    /**
+     * Create a version mismatch error
+     */
+    static versionMismatch(expected, actual) {
+        return new StateError(`Version mismatch: expected ${String(expected)}, got ${String(actual)}`, StateErrorCode.VERSION_MISMATCH);
+    }
+    /**
+     * Create an invalid state error
+     */
+    static invalidState(message) {
+        return new StateError(`Invalid state: ${message}`, StateErrorCode.INVALID_STATE);
+    }
+    /**
+     * Create an invalid session ID error
+     */
+    static invalidSessionId(sessionId) {
+        return new StateError(`Invalid session ID: ${sessionId}`, StateErrorCode.INVALID_SESSION_ID);
+    }
+}

package/dist/state/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * State Management Module
+ *
+ * Provides conversation persistence and session management.
+ * Inspired by LangGraph's checkpointer pattern.
+ *
+ * @example
+ * ```typescript
+ * import { FileCheckpointer, JsonSerializer } from '@compilr-dev/agents';
+ *
+ * // Create checkpointer
+ * const checkpointer = new FileCheckpointer('~/.myapp/sessions/');
+ *
+ * // Use with agent
+ * const agent = new Agent({
+ *   provider,
+ *   checkpointer,
+ *   autoCheckpoint: true,
+ * });
+ *
+ * // Or manually checkpoint
+ * await agent.run('Hello!');
+ * const sessionId = await agent.checkpoint();
+ *
+ * // Resume later
+ * const resumed = await Agent.resume(sessionId, { provider, checkpointer });
+ * ```
+ */
+export type { AgentState, SessionMetadata, SessionInfo, StateSerializer, Checkpointer, CheckpointerWithPending, PendingWrite, ListSessionsOptions, ResumeOptions, FromStateOptions, } from './types.js';
+export { CURRENT_STATE_VERSION } from './types.js';
+export { StateError, StateErrorCode } from './errors.js';
+export { JsonSerializer, CompactJsonSerializer, defaultSerializer } from './serializer.js';
+export { MemoryCheckpointer, FileCheckpointer } from './checkpointer.js';
+export type { FileCheckpointerOptions } from './checkpointer.js';
+export { generateSessionId, createEmptyState, createAgentState, serializeTodos, deserializeTodos, touchState, } from './agent-state.js';

package/dist/state/index.js

@@ -0,0 +1,37 @@
+/**
+ * State Management Module
+ *
+ * Provides conversation persistence and session management.
+ * Inspired by LangGraph's checkpointer pattern.
+ *
+ * @example
+ * ```typescript
+ * import { FileCheckpointer, JsonSerializer } from '@compilr-dev/agents';
+ *
+ * // Create checkpointer
+ * const checkpointer = new FileCheckpointer('~/.myapp/sessions/');
+ *
+ * // Use with agent
+ * const agent = new Agent({
+ *   provider,
+ *   checkpointer,
+ *   autoCheckpoint: true,
+ * });
+ *
+ * // Or manually checkpoint
+ * await agent.run('Hello!');
+ * const sessionId = await agent.checkpoint();
+ *
+ * // Resume later
+ * const resumed = await Agent.resume(sessionId, { provider, checkpointer });
+ * ```
+ */
+export { CURRENT_STATE_VERSION } from './types.js';
+// Errors
+export { StateError, StateErrorCode } from './errors.js';
+// Serializers
+export { JsonSerializer, CompactJsonSerializer, defaultSerializer } from './serializer.js';
+// Checkpointers
+export { MemoryCheckpointer, FileCheckpointer } from './checkpointer.js';
+// Agent state utilities
+export { generateSessionId, createEmptyState, createAgentState, serializeTodos, deserializeTodos, touchState, } from './agent-state.js';

package/dist/state/serializer.d.ts

@@ -0,0 +1,55 @@
+/**
+ * State Serializers
+ *
+ * Implementations for serializing/deserializing AgentState.
+ */
+import type { AgentState, StateSerializer } from './types.js';
+/**
+ * JSON-based state serializer.
+ * Handles standard JSON serialization with validation.
+ */
+export declare class JsonSerializer implements StateSerializer {
+    readonly version = "1.0";
+    /**
+     * Serialize agent state to JSON string
+     */
+    serialize(state: AgentState): string;
+    /**
+     * Deserialize JSON string to agent state
+     */
+    deserialize(data: string): AgentState;
+    /**
+     * Validate state before serialization (public interface method).
+     * This is called by checkpointers before saving to prevent corrupted checkpoints.
+     * @throws StateError if state is invalid
+     */
+    validate(state: AgentState): void;
+    /**
+     * Validate that parsed data is a valid AgentState
+     */
+    private validateParsed;
+    /**
+     * Migrate from older versions (currently no-op for v1)
+     */
+    migrate(data: string, fromVersion: string): string;
+}
+/**
+ * Compact JSON serializer (no pretty printing).
+ * Useful for storage-constrained environments.
+ */
+export declare class CompactJsonSerializer implements StateSerializer {
+    readonly version = "1.0";
+    serialize(state: AgentState): string;
+    deserialize(data: string): AgentState;
+    /**
+     * Validate state before serialization (public interface method).
+     * This is called by checkpointers before saving to prevent corrupted checkpoints.
+     * @throws StateError if state is invalid
+     */
+    validate(state: AgentState): void;
+    private validateParsed;
+}
+/**
+ * Default serializer instance
+ */
+export declare const defaultSerializer: JsonSerializer;