@simulacra-ai/session 0.0.2 → 0.0.4

package/dist/index.d.cts

@@ -0,0 +1,364 @@
+import * as _simulacra_ai_core from '@simulacra-ai/core';
+import { CheckpointState, Message, LifecycleErrorEvent, Conversation } from '@simulacra-ai/core';
+
+/**
+ * Metadata that describes a conversation session.
+ *
+ * Sessions can form a tree structure through forking, where a child session
+ * can inherit messages from its parent session up to a specific fork point.
+ */
+interface SessionMetadata {
+    /** The unique identifier for the session. */
+    id: string;
+    /** ISO 8601 timestamp when the session was created. */
+    created_at: string;
+    /** ISO 8601 timestamp when the session was last updated. */
+    updated_at: string;
+    /** The AI provider used in this session (e.g., "anthropic", "openai"). */
+    provider?: string;
+    /** The model identifier used in this session (e.g., "claude-3-5-sonnet-20241022"). */
+    model?: string;
+    /** A human-readable label or title for the session. */
+    label?: string;
+    /** The number of messages stored in this session. */
+    message_count: number;
+    /** The ID of the parent session if this is a fork. */
+    parent_id?: string;
+    /** The ID of the last message from the parent session included in this fork. */
+    fork_message_id?: string;
+    /** Whether this fork is detached and does not inherit parent messages. */
+    detached?: boolean;
+    /** Whether this session is a checkpoint summarization session. */
+    is_checkpoint?: boolean;
+    /** The latest checkpoint state for this conversation. */
+    checkpoint_state?: CheckpointState;
+}
+/**
+ * A storage backend for conversation sessions.
+ *
+ * Implementations are responsible for persisting sessions and their messages,
+ * whether in memory, on disk, or in a database.
+ */
+interface SessionStore {
+    /**
+     * Lists all stored sessions.
+     *
+     * @returns A promise that resolves to an array of session metadata, typically sorted by last update time.
+     */
+    list(): Promise<SessionMetadata[]>;
+    /**
+     * Loads a session by its ID.
+     *
+     * @param id - The unique identifier of the session to load.
+     * @returns A promise that resolves to the session metadata and messages, or undefined if not found.
+     */
+    load(id: string): Promise<{
+        metadata: SessionMetadata;
+        messages: Message[];
+    } | undefined>;
+    /**
+     * Saves a session with the given messages and metadata.
+     *
+     * If the session already exists, it updates the existing entry. If it does not exist, it creates a new one.
+     *
+     * @param id - The unique identifier of the session.
+     * @param messages - The messages to store for this session.
+     * @param metadata - Optional partial metadata to merge with existing or create new metadata.
+     * @returns A promise that resolves when the save operation is complete.
+     */
+    save(id: string, messages: Message[], metadata?: Partial<SessionMetadata>): Promise<void>;
+    /**
+     * Deletes a session by its ID.
+     *
+     * @param id - The unique identifier of the session to delete.
+     * @returns A promise that resolves to true if the session was deleted, false if it was not found.
+     */
+    delete(id: string): Promise<boolean>;
+}
+/**
+ * Configuration options for SessionManager behavior.
+ */
+interface SessionManagerOptions {
+    /**
+     * Whether to automatically save the session after each completed message.
+     *
+     * @defaultValue true
+     */
+    auto_save?: boolean;
+    /**
+     * Whether to automatically generate a label from the first user message.
+     *
+     * @defaultValue true
+     */
+    auto_slug?: boolean;
+}
+/**
+ * Events emitted by SessionManager instances.
+ *
+ * Each event key maps to a tuple representing the arguments passed to event listeners.
+ */
+interface SessionManagerEvents {
+    /** Emitted when a session is loaded. */
+    load: [{
+        id: string;
+        messages: Readonly<Message[]>;
+    }];
+    /** Emitted when a session is saved. */
+    save: [{
+        id: string;
+        messages: Readonly<Message[]>;
+    }];
+    /** Emitted when an infrastructure or lifecycle operation fails. */
+    lifecycle_error: [LifecycleErrorEvent];
+    /** Emitted when the SessionManager is disposed. */
+    dispose: [];
+}
+
+/**
+ * Manages conversation sessions including creation, loading, saving, and forking.
+ *
+ * The SessionManager acts as a bridge between a Conversation instance and a SessionStore,
+ * handling session lifecycle, automatic saving, and session tree management through forking.
+ * It supports disposable resource management and event emission for session operations.
+ */
+declare class SessionManager {
+    #private;
+    /**
+     * Creates a new SessionManager instance.
+     *
+     * @param store - The storage backend to use for persisting sessions.
+     * @param conversation - The conversation instance to manage.
+     * @param options - Optional configuration for session management behavior.
+     */
+    constructor(store: SessionStore, conversation: Conversation, options?: SessionManagerOptions);
+    /**
+     * The ID of the currently active session.
+     *
+     * @returns The session ID if a session is active, otherwise undefined.
+     */
+    get current_session_id(): string | undefined;
+    /**
+     * Whether a session is currently loaded.
+     *
+     * @returns True if a session is active, false otherwise.
+     */
+    get is_loaded(): boolean;
+    /**
+     * Disposes of the SessionManager and cleans up resources.
+     *
+     * This method removes event listeners, disposes child sessions, and emits the dispose event.
+     * It is called automatically when the associated conversation is disposed or when using
+     * explicit resource management.
+     */
+    [Symbol.dispose](): void;
+    /**
+     * Starts a new session with a freshly generated ID.
+     *
+     * This method clears the conversation history and creates a new session. If auto_save
+     * is enabled or a label is provided, the session is immediately saved to the store.
+     *
+     * @param label - Optional label to assign to the new session.
+     * @returns The generated session ID.
+     */
+    start_new(label?: string): string;
+    /**
+     * Creates a new session as a fork of an existing parent session.
+     *
+     * A fork creates a new session that inherits messages from the parent session up to
+     * the fork point. If detached, the fork does not inherit any messages from the parent
+     * but still maintains a parent reference for organizational purposes.
+     *
+     * @param parent_session_id - The ID of the session to fork from.
+     * @param options - Optional configuration for the fork operation.
+     * @param options.detached - Whether to create a detached fork that does not inherit parent messages.
+     * @returns A promise that resolves to the generated session ID for the fork.
+     */
+    fork(parent_session_id: string, options?: {
+        detached?: boolean;
+    }): Promise<string>;
+    /**
+     * Loads a session by ID or loads the most recent session if no ID is provided.
+     *
+     * If no session ID is provided and no sessions exist in the store, this method
+     * starts a new session automatically. Loading a session resolves its full message
+     * history by recursively following parent references.
+     *
+     * @param id - The ID of the session to load, or undefined to load the most recent session.
+     * @returns A promise that resolves when the session is loaded.
+     * @throws {Error} If the specified session ID is not found in the store.
+     */
+    load(id?: string): Promise<void>;
+    /**
+     * Saves the current session to the store.
+     *
+     * This method persists only the messages owned by this session, excluding any messages
+     * inherited from parent sessions. If auto_slug is enabled and no label has been set,
+     * a label is automatically generated from the first user message.
+     *
+     * @param metadata - Optional partial metadata to update on the session.
+     * @returns A promise that resolves when the save operation is complete.
+     * @throws {Error} If no session is currently active.
+     */
+    save(metadata?: Partial<Pick<SessionMetadata, "label" | "provider" | "model" | "parent_id" | "fork_message_id" | "detached">>): Promise<void>;
+    /**
+     * Lists all sessions stored in the store.
+     *
+     * @returns A promise that resolves to an array of session metadata, typically sorted by last update time.
+     */
+    list(): Promise<SessionMetadata[]>;
+    /**
+     * Deletes a session from the store.
+     *
+     * If the deleted session is currently active, the conversation is cleared and the
+     * current session is unset.
+     *
+     * @param id - The ID of the session to delete.
+     * @returns A promise that resolves to true if the session was deleted, false if it was not found.
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * Renames a session by updating its label.
+     *
+     * @param id - The ID of the session to rename.
+     * @param label - The new label to assign to the session.
+     * @returns A promise that resolves when the rename operation is complete.
+     * @throws {Error} If the specified session ID is not found in the store.
+     */
+    rename(id: string, label: string): Promise<void>;
+    /**
+     * Registers an event listener for the specified event.
+     *
+     * @param event - The name of the event to listen for.
+     * @param listener - The callback function to invoke when the event is emitted.
+     * @returns This SessionManager instance for method chaining.
+     */
+    on<E extends keyof SessionManagerEvents>(event: E, listener: (...args: SessionManagerEvents[E]) => void): this;
+    /**
+     * Removes an event listener for the specified event.
+     *
+     * @param event - The name of the event to stop listening for.
+     * @param listener - The callback function to remove.
+     * @returns This SessionManager instance for method chaining.
+     */
+    off<E extends keyof SessionManagerEvents>(event: E, listener: (...args: SessionManagerEvents[E]) => void): this;
+}
+
+/**
+ * A file-based implementation of SessionStore.
+ *
+ * This store persists sessions as JSON files in a specified directory. Each session
+ * is stored in a separate file named with its session ID. The store also maintains
+ * hard links for fork relationships to enable efficient querying of session trees.
+ */
+declare class FileSessionStore implements SessionStore {
+    #private;
+    /**
+     * Creates a new FileSessionStore instance.
+     *
+     * @param root - The absolute path to the directory where session files will be stored.
+     */
+    constructor(root: string);
+    /**
+     * Lists all sessions stored in the file system.
+     *
+     * Reads all JSON files from the root directory and parses their metadata.
+     *
+     * @returns A promise that resolves to an array of session metadata, sorted by most recently updated first.
+     */
+    list(): Promise<SessionMetadata[]>;
+    /**
+     * Loads a session from the file system.
+     *
+     * @param id - The unique identifier of the session to load.
+     * @returns A promise that resolves to the session metadata and messages, or undefined if not found.
+     */
+    load(id: string): Promise<{
+        metadata: SessionMetadata;
+        messages: Message[];
+    } | undefined>;
+    /**
+     * Saves a session to the file system.
+     *
+     * Creates a new session file if the ID does not exist, or updates an existing file.
+     * Automatically updates the updated_at timestamp and message_count. If the session
+     * has a parent, creates a hard link in the parent's fork directory for efficient querying.
+     *
+     * @param id - The unique identifier of the session.
+     * @param messages - The messages to store for this session.
+     * @param metadata - Optional partial metadata to merge with existing metadata.
+     * @returns A promise that resolves when the save operation is complete.
+     */
+    save(id: string, messages: Message[], metadata?: Partial<SessionMetadata>): Promise<void>;
+    /**
+     * Deletes a session from the file system.
+     *
+     * Removes the session file, any hard links in parent fork directories, and the session's
+     * own fork directory if it exists.
+     *
+     * @param id - The unique identifier of the session to delete.
+     * @returns A promise that resolves to true if the session was deleted, false if it was not found.
+     */
+    delete(id: string): Promise<boolean>;
+}
+
+/**
+ * An in-memory implementation of SessionStore.
+ *
+ * This store keeps all session data in memory using a Map. Data is not persisted
+ * across process restarts. Useful for testing or scenarios where persistence is not required.
+ */
+declare class InMemorySessionStore implements SessionStore {
+    #private;
+    /**
+     * Lists all sessions stored in memory.
+     *
+     * @returns A promise that resolves to an array of session metadata, sorted by most recently updated first.
+     */
+    list(): Promise<SessionMetadata[]>;
+    /**
+     * Loads a session from memory.
+     *
+     * Returns a deep clone of the stored data to prevent external mutations.
+     *
+     * @param id - The unique identifier of the session to load.
+     * @returns A promise that resolves to the session metadata and messages, or undefined if not found.
+     */
+    load(id: string): Promise<{
+        metadata: {
+            id: string;
+            created_at: string;
+            updated_at: string;
+            provider?: string;
+            model?: string;
+            label?: string;
+            message_count: number;
+            parent_id?: string;
+            fork_message_id?: string;
+            detached?: boolean;
+            is_checkpoint?: boolean;
+            checkpoint_state?: _simulacra_ai_core.CheckpointState;
+        };
+        messages: Message[];
+    } | undefined>;
+    /**
+     * Saves a session to memory.
+     *
+     * Creates a new session if the ID does not exist, or updates an existing session.
+     * Automatically updates the updated_at timestamp and message_count.
+     *
+     * @param id - The unique identifier of the session.
+     * @param messages - The messages to store for this session.
+     * @param metadata - Optional partial metadata to merge with existing metadata.
+     * @returns A promise that resolves when the save operation is complete.
+     */
+    save(id: string, messages: Message[], metadata?: Partial<SessionMetadata>): Promise<void>;
+    /**
+     * Deletes a session from memory.
+     *
+     * @param id - The unique identifier of the session to delete.
+     * @returns A promise that resolves to true if the session was deleted, false if it was not found.
+     */
+    delete(id: string): Promise<boolean>;
+}
+
+export { FileSessionStore, InMemorySessionStore, SessionManager, type SessionManagerEvents, type SessionManagerOptions, type SessionMetadata, type SessionStore };