@simulacra-ai/session 0.0.1

package/README.md

@@ -0,0 +1,108 @@
+# Simulacra Session
+
+Session persistence for the Simulacra conversation engine. Manages saving, loading, and labeling conversation sessions with pluggable storage backends.
+
+## Installation
+
+```bash
+npm install @simulacra-ai/core @simulacra-ai/session
+```
+
+## Quick Start
+
+```typescript
+import { SessionManager, FileSessionStore } from "@simulacra-ai/session";
+
+const store = new FileSessionStore("./sessions");
+const session = new SessionManager(store, conversation);
+
+session.start_new("my first session");
+// ... conversation happens ...
+await session.save();
+```
+
+With `auto_save` (default `true`), messages are saved automatically after each model response.
+
+## SessionManager
+
+`SessionManager` coordinates a conversation with a storage backend and handles the lifecycle of sessions: creation, loading, saving, and disposal.
+
+```typescript
+new SessionManager(store, conversation, options?)
+```
+
+Option|Type|Default|Description
+-|-|-|-
+`auto_save`|`boolean`|`true`|Save after every `message_complete` event
+`auto_slug`|`boolean`|`true`|Derive a label from the first user message
+
+### Methods
+
+Method|Description
+-|-
+`start_new(label?)`|Begin a new session, returns the session ID
+`load(id?)`|Load a session by ID, or the most recent if omitted
+`save(metadata?)`|Persist current messages and metadata
+`fork(parent_id, options?)`|Create a child session branching from a parent
+`list()`|List all sessions from the store
+`delete(id)`|Remove a session
+`rename(id, label)`|Change a session's label
+
+### Events
+
+Event|Payload|When
+-|-|-
+`load`|`{ id, messages }`|Session loaded from store
+`save`|`{ id, messages }`|Session written to store
+`dispose`|(none)|Manager disposed
+
+### Auto-Slug
+
+When `auto_slug` is enabled, `SessionManager` derives a label from the first ~50 characters of the first user message (trimmed to a word boundary). This runs once on the first save; explicitly setting a label via `start_new(label)` or `rename()` takes precedence.
+
+### Child Sessions
+
+`SessionManager` listens for the conversation's `create_child` event. When a child conversation is spawned — via orchestration, checkpoints, or `spawn_child` — the session manager automatically creates a child session backed by a detached fork. Child sessions auto-save independently and are disposed when the child conversation ends.
+
+Checkpoint children have `auto_slug` disabled since their sessions are internal.
+
+## Built-in Stores
+
+### FileSessionStore
+
+Persists sessions as JSON files on disk. Each session is a single `{id}.json` file.
+
+```typescript
+import { FileSessionStore } from "@simulacra-ai/session";
+
+const store = new FileSessionStore("./data/sessions");
+```
+
+Child session relationships are indexed using hard links under `{parent-id}-forks/` directories.
+
+### InMemorySessionStore
+
+Non-persistent store for testing. Sessions live in a `Map` and are lost on process exit.
+
+```typescript
+import { InMemorySessionStore } from "@simulacra-ai/session";
+
+const store = new InMemorySessionStore();
+```
+
+## SessionStore Interface
+
+Custom storage backends implement the `SessionStore` interface. See the [extensibility guide](EXTENSIBILITY.md) for implementation details and examples.
+
+```typescript
+interface SessionStore {
+  list(): Promise<SessionMetadata[]>;
+  load(id: string): Promise<{ metadata: SessionMetadata; messages: Message[] } | undefined>;
+  save(id: string, messages: Message[], metadata?: Partial<SessionMetadata>): Promise<void>;
+  delete(id: string): Promise<boolean>;
+}
+```
+
+## License
+
+MIT

package/dist/file-session-store.d.ts

@@ -0,0 +1,60 @@
+import type { Message } from "@simulacra-ai/core";
+import type { SessionMetadata, SessionStore } from "./types.ts";
+/**
+ * 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.
+ */
+export 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>;
+}
+//# sourceMappingURL=file-session-store.d.ts.map

package/dist/file-session-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-session-store.d.ts","sourceRoot":"","sources":["../src/file-session-store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAOhE;;;;;;GAMG;AACH,qBAAa,gBAAiB,YAAW,YAAY;;IAGnD;;;;OAIG;gBACS,IAAI,EAAE,MAAM;IAIxB;;;;;;OAMG;IACG,IAAI,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAqBxC;;;;;OAKG;IACG,IAAI,CAAC,EAAE,EAAE,MAAM;kBAyGuB,eAAe;;;IArG3D;;;;;;;;;;;OAWG;IACG,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,QAAQ,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC;IA2B/E;;;;;;;;OAQG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM;CA0ExB"}

package/dist/file-session-store.js

@@ -0,0 +1,166 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+/**
+ * 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.
+ */
+export class FileSessionStore {
+    #root;
+    /**
+     * Creates a new FileSessionStore instance.
+     *
+     * @param root - The absolute path to the directory where session files will be stored.
+     */
+    constructor(root) {
+        this.#root = root;
+    }
+    /**
+     * 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.
+     */
+    async list() {
+        await this.#ensure_dir();
+        const sessions = [];
+        const entries = await fs.readdir(this.#root, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isFile() || !entry.name.endsWith(".json")) {
+                continue;
+            }
+            const session = await this.#read_session(path.join(this.#root, entry.name), entry.name.replace(/\.json$/, ""));
+            if (session) {
+                sessions.push(session);
+            }
+        }
+        return sessions.sort((a, b) => b.updated_at.localeCompare(a.updated_at));
+    }
+    /**
+     * 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.
+     */
+    async load(id) {
+        return this.#read_file(path.join(this.#root, `${id}.json`), id);
+    }
+    /**
+     * 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.
+     */
+    async save(id, messages, metadata) {
+        const now = new Date().toISOString();
+        await this.#ensure_dir();
+        const file_path = path.join(this.#root, `${id}.json`);
+        const existing = await this.#read_file(file_path, id);
+        const existing_metadata = existing?.metadata ?? {};
+        const parent_id = metadata?.parent_id ?? existing_metadata.parent_id;
+        const file = {
+            metadata: {
+                ...existing_metadata,
+                created_at: existing_metadata.created_at ?? now,
+                updated_at: now,
+                message_count: messages.length,
+                ...metadata,
+            },
+            messages,
+        };
+        await fs.writeFile(file_path, JSON.stringify(file, null, 2), "utf8");
+        if (parent_id) {
+            await this.#ensure_fork_link(parent_id, id);
+        }
+    }
+    /**
+     * 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.
+     */
+    async delete(id) {
+        const file_path = path.join(this.#root, `${id}.json`);
+        try {
+            const result = await this.#read_file(file_path, id);
+            await fs.unlink(file_path);
+            if (result?.metadata.parent_id) {
+                const link = path.join(this.#root, `${result.metadata.parent_id}-forks`, `${id}.json`);
+                try {
+                    await fs.unlink(link);
+                }
+                catch {
+                    /* link may not exist */
+                }
+            }
+            const fork_dir = path.join(this.#root, `${id}-forks`);
+            try {
+                await fs.rm(fork_dir, { recursive: true });
+            }
+            catch {
+                /* no forks */
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async #ensure_fork_link(parent_id, fork_id) {
+        const fork_dir = path.join(this.#root, `${parent_id}-forks`);
+        await fs.mkdir(fork_dir, { recursive: true });
+        const canonical = path.join(this.#root, `${fork_id}.json`);
+        const link = path.join(fork_dir, `${fork_id}.json`);
+        try {
+            await fs.unlink(link);
+        }
+        catch {
+            /* doesn't exist yet */
+        }
+        try {
+            await fs.link(canonical, link);
+        }
+        catch {
+            // hard links can fail across filesystems — fall back to no index
+        }
+    }
+    async #read_file(file_path, id) {
+        try {
+            const content = await fs.readFile(file_path, "utf8");
+            const data = JSON.parse(content);
+            return {
+                metadata: { id, ...data.metadata },
+                messages: data.messages,
+            };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async #read_session(file_path, id) {
+        try {
+            const content = await fs.readFile(file_path, "utf8");
+            const data = JSON.parse(content);
+            return { id, ...data.metadata };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async #ensure_dir() {
+        await fs.mkdir(this.#root, { recursive: true });
+    }
+}
+//# sourceMappingURL=file-session-store.js.map

package/dist/file-session-store.js.map

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

package/dist/in-memory-session-store.d.ts

@@ -0,0 +1,62 @@
+import type { Message } from "@simulacra-ai/core";
+import type { SessionMetadata, SessionStore } from "./types.ts";
+/**
+ * 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.
+ */
+export 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?: import("@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>;
+}
+//# sourceMappingURL=in-memory-session-store.d.ts.map

package/dist/in-memory-session-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-session-store.d.ts","sourceRoot":"","sources":["../src/in-memory-session-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEhE;;;;;GAKG;AACH,qBAAa,oBAAqB,YAAW,YAAY;;IAGvD;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAMxC;;;;;;;OAOG;IACG,IAAI,CAAC,EAAE,EAAE,MAAM;;;;;;;;;;;;;;;;;IAWrB;;;;;;;;;;OAUG;IACG,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,QAAQ,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC;IAiB/E;;;;;OAKG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM;CAGxB"}

package/dist/in-memory-session-store.js

@@ -0,0 +1,73 @@
+/**
+ * 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.
+ */
+export class InMemorySessionStore {
+    #sessions = new Map();
+    /**
+     * Lists all sessions stored in memory.
+     *
+     * @returns A promise that resolves to an array of session metadata, sorted by most recently updated first.
+     */
+    async list() {
+        return [...this.#sessions.values()]
+            .map((s) => s.metadata)
+            .sort((a, b) => b.updated_at.localeCompare(a.updated_at));
+    }
+    /**
+     * 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.
+     */
+    async load(id) {
+        const entry = this.#sessions.get(id);
+        if (!entry) {
+            return undefined;
+        }
+        return {
+            metadata: { ...entry.metadata },
+            messages: structuredClone(entry.messages),
+        };
+    }
+    /**
+     * 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.
+     */
+    async save(id, messages, metadata) {
+        const now = new Date().toISOString();
+        const existing = this.#sessions.get(id);
+        this.#sessions.set(id, {
+            metadata: {
+                id,
+                ...existing?.metadata,
+                created_at: existing?.metadata.created_at ?? now,
+                updated_at: now,
+                message_count: messages.length,
+                ...metadata,
+            },
+            messages: structuredClone(messages),
+        });
+    }
+    /**
+     * 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.
+     */
+    async delete(id) {
+        return this.#sessions.delete(id);
+    }
+}
+//# sourceMappingURL=in-memory-session-store.js.map

package/dist/in-memory-session-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-session-store.js","sourceRoot":"","sources":["../src/in-memory-session-store.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,MAAM,OAAO,oBAAoB;IACtB,SAAS,GAAG,IAAI,GAAG,EAA8D,CAAC;IAE3F;;;;OAIG;IACH,KAAK,CAAC,IAAI;QACR,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC;aAChC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;aACtB,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI,CAAC,EAAU;QACnB,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACrC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO;YACL,QAAQ,EAAE,EAAE,GAAG,KAAK,CAAC,QAAQ,EAAE;YAC/B,QAAQ,EAAE,eAAe,CAAC,KAAK,CAAC,QAAQ,CAAC;SAC1C,CAAC;IACJ,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,IAAI,CAAC,EAAU,EAAE,QAAmB,EAAE,QAAmC;QAC7E,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAExC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,EAAE;YACrB,QAAQ,EAAE;gBACR,EAAE;gBACF,GAAG,QAAQ,EAAE,QAAQ;gBACrB,UAAU,EAAE,QAAQ,EAAE,QAAQ,CAAC,UAAU,IAAI,GAAG;gBAChD,UAAU,EAAE,GAAG;gBACf,aAAa,EAAE,QAAQ,CAAC,MAAM;gBAC9B,GAAG,QAAQ;aACZ;YACD,QAAQ,EAAE,eAAe,CAAC,QAAQ,CAAC;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,MAAM,CAAC,EAAU;QACrB,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACnC,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { SessionMetadata, SessionStore, SessionManagerOptions, SessionManagerEvents, } from "./types.ts";
+export { SessionManager } from "./session-manager.ts";
+export { FileSessionStore } from "./file-session-store.ts";
+export { InMemorySessionStore } from "./in-memory-session-store.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,eAAe,EACf,YAAY,EACZ,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { SessionManager } from "./session-manager.js";
+export { FileSessionStore } from "./file-session-store.js";
+export { InMemorySessionStore } from "./in-memory-session-store.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/session-manager.d.ts

@@ -0,0 +1,131 @@
+import type { Conversation } from "@simulacra-ai/core";
+import type { SessionMetadata, SessionStore, SessionManagerOptions, SessionManagerEvents } from "./types.ts";
+/**
+ * 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.
+ */
+export 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;
+}
+//# sourceMappingURL=session-manager.d.ts.map

package/dist/session-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../src/session-manager.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAW,MAAM,oBAAoB,CAAC;AAChE,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,qBAAa,cAAc;;IAazB;;;;;;OAMG;gBACS,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,qBAAqB;IAa5F;;;;OAIG;IACH,IAAI,kBAAkB,uBAErB;IAED;;;;OAIG;IACH,IAAI,SAAS,YAEZ;IAED;;;;;;OAMG;IACH,CAAC,MAAM,CAAC,OAAO,CAAC;IAkBhB;;;;;;;;OAQG;IACH,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM;IAmBjC;;;;;;;;;;;OAWG;IACG,IAAI,CAAC,iBAAiB,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAqCxF;;;;;;;;;;OAUG;IACG,IAAI,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BtC;;;;;;;;;;OAUG;IACG,IAAI,CACR,QAAQ,CAAC,EAAE,OAAO,CAChB,IAAI,CACF,eAAe,EACf,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,WAAW,GAAG,iBAAiB,GAAG,UAAU,CAC9E,CACF;IAkCH;;;;OAIG;IACG,IAAI;IAIV;;;;;;;;OAQG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM;IAQvB;;;;;;;OAOG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAWtC;;;;;;OAMG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,oBAAoB,EACrC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,oBAAoB,CAAC,CAAC,CAAC,KAAK,IAAI,GACnD,IAAI;IAMP;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,SAAS,MAAM,oBAAoB,EACtC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,oBAAoB,CAAC,CAAC,CAAC,KAAK,IAAI,GACnD,IAAI;CA6FR"}

package/dist/session-manager.js

@@ -0,0 +1,366 @@
+var _a;
+import { randomUUID } from "node:crypto";
+import EventEmitter from "node:events";
+/**
+ * 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.
+ */
+export class SessionManager {
+    #store;
+    #conversation;
+    #auto_save;
+    #auto_slug;
+    #event_emitter = new EventEmitter();
+    #child_sessions = [];
+    #session_id;
+    #fork_offset = 0;
+    #has_label = false;
+    #disposed = false;
+    /**
+     * 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, conversation, options) {
+        this.#store = store;
+        this.#conversation = conversation;
+        this.#auto_save = options?.auto_save ?? true;
+        this.#auto_slug = options?.auto_slug ?? true;
+        if (this.#auto_save) {
+            this.#conversation.on("message_complete", this.#on_message_complete);
+        }
+        this.#conversation.on("create_child", this.#on_create_child);
+        this.#conversation.once("dispose", this.#on_conversation_dispose);
+    }
+    /**
+     * The ID of the currently active session.
+     *
+     * @returns The session ID if a session is active, otherwise undefined.
+     */
+    get current_session_id() {
+        return this.#session_id;
+    }
+    /**
+     * Whether a session is currently loaded.
+     *
+     * @returns True if a session is active, false otherwise.
+     */
+    get is_loaded() {
+        return !!this.#session_id;
+    }
+    /**
+     * 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]() {
+        if (this.#disposed) {
+            return;
+        }
+        this.#disposed = true;
+        for (const child of this.#child_sessions) {
+            child[Symbol.dispose]();
+        }
+        this.#child_sessions.length = 0;
+        this.#conversation.off("message_complete", this.#on_message_complete);
+        this.#conversation.off("create_child", this.#on_create_child);
+        this.#conversation.off("dispose", this.#on_conversation_dispose);
+        this.#event_emitter.emit("dispose");
+        this.#event_emitter.removeAllListeners();
+    }
+    /**
+     * 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) {
+        this.#session_id = randomUUID();
+        this.#fork_offset = 0;
+        this.#has_label = !!label;
+        if (this.#conversation.messages.length > 0) {
+            this.#conversation.clear();
+        }
+        if (label || this.#auto_save) {
+            this.save({ label }).catch((error) => {
+                this.#event_emitter.emit("lifecycle_error", {
+                    error,
+                    operation: "save",
+                    context: { session_id: this.#session_id },
+                });
+            });
+        }
+        return this.#session_id;
+    }
+    /**
+     * 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.
+     */
+    async fork(parent_session_id, options) {
+        const detached = options?.detached ?? false;
+        this.#session_id = randomUUID();
+        this.#has_label = false;
+        if (!detached) {
+            this.#conversation.clear();
+        }
+        let fork_message_id;
+        if (!detached) {
+            const messages = await this.#resolve_messages(parent_session_id);
+            if (messages.length > 0) {
+                this.#conversation.load(messages);
+                this.#fork_offset = messages.length;
+                fork_message_id = messages.at(-1)?.id;
+            }
+            else {
+                this.#fork_offset = 0;
+            }
+        }
+        else {
+            this.#fork_offset = 0;
+        }
+        const parent_result = await this.#store.load(parent_session_id);
+        if (parent_result?.metadata.checkpoint_state) {
+            this.#conversation.checkpoint_state = parent_result.metadata.checkpoint_state;
+        }
+        await this.save({
+            parent_id: parent_session_id,
+            fork_message_id,
+            detached,
+        });
+        return this.#session_id;
+    }
+    /**
+     * 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.
+     */
+    async load(id) {
+        if (id) {
+            const messages = await this.#resolve_messages(id);
+            const result = await this.#store.load(id);
+            if (!result) {
+                throw new Error(`session not found: ${id}`);
+            }
+            this.#session_id = id;
+            this.#has_label = !!result.metadata.label;
+            this.#conversation.clear();
+            this.#fork_offset = messages.length - result.messages.length;
+            this.#conversation.load(messages);
+            this.#conversation.checkpoint_state = result.metadata.checkpoint_state;
+            this.#emit_load(messages);
+            return;
+        }
+        const sessions = await this.#store.list();
+        if (!sessions.length) {
+            this.start_new();
+            return;
+        }
+        const latest = sessions[0];
+        return this.load(latest.id);
+    }
+    /**
+     * 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.
+     */
+    async save(metadata) {
+        if (!this.#session_id) {
+            throw new Error("no active session");
+        }
+        const all_messages = this.#conversation.messages;
+        const owned_messages = [...all_messages].slice(this.#fork_offset);
+        if (this.#auto_slug && !metadata?.label && !this.#has_label) {
+            const slug = _a.#derive_slug(all_messages);
+            if (slug) {
+                metadata = { ...metadata, label: slug };
+                this.#has_label = true;
+            }
+        }
+        const conversation_metadata = { ...metadata };
+        if (this.#conversation.is_checkpoint) {
+            conversation_metadata.is_checkpoint = true;
+        }
+        const checkpoint_state = this.#conversation.checkpoint_state;
+        if (checkpoint_state) {
+            conversation_metadata.checkpoint_state = { ...checkpoint_state };
+        }
+        await this.#store.save(this.#session_id, owned_messages, conversation_metadata);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this.#event_emitter.emit("save", {
+            id: this.#session_id,
+            messages: Object.freeze([...all_messages]),
+        });
+    }
+    /**
+     * Lists all sessions stored in the store.
+     *
+     * @returns A promise that resolves to an array of session metadata, typically sorted by last update time.
+     */
+    async list() {
+        return this.#store.list();
+    }
+    /**
+     * 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.
+     */
+    async delete(id) {
+        if (id === this.#session_id) {
+            this.#session_id = undefined;
+            this.#conversation.clear();
+        }
+        return this.#store.delete(id);
+    }
+    /**
+     * 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.
+     */
+    async rename(id, label) {
+        const result = await this.#store.load(id);
+        if (!result) {
+            throw new Error(`session not found: ${id}`);
+        }
+        await this.#store.save(id, result.messages, { label });
+        if (id === this.#session_id) {
+            this.#has_label = true;
+        }
+    }
+    /**
+     * 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(event, listener) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this.#event_emitter.on(event, listener);
+        return 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(event, listener) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this.#event_emitter.off(event, listener);
+        return this;
+    }
+    #emit_load(messages) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this.#event_emitter.emit("load", {
+            id: this.#session_id,
+            messages: Object.freeze([...messages]),
+        });
+    }
+    async #resolve_messages(id) {
+        const result = await this.#store.load(id);
+        if (!result) {
+            return [];
+        }
+        const { metadata, messages } = result;
+        if (metadata.parent_id && !metadata.detached) {
+            const parent_messages = await this.#resolve_messages(metadata.parent_id);
+            if (metadata.fork_message_id) {
+                const cut = parent_messages.findIndex((m) => m.id === metadata.fork_message_id);
+                if (cut >= 0) {
+                    return [...parent_messages.slice(0, cut + 1), ...messages];
+                }
+            }
+            return [...parent_messages, ...messages];
+        }
+        return messages;
+    }
+    static #derive_slug(messages) {
+        const first_user = messages.find((m) => m.role === "user");
+        if (!first_user) {
+            return undefined;
+        }
+        const text_content = first_user.content.find((c) => c.type === "text");
+        if (!text_content || text_content.type !== "text" || !text_content.text) {
+            return undefined;
+        }
+        const raw = text_content.text.trim();
+        if (!raw) {
+            return undefined;
+        }
+        const truncated = raw.slice(0, 60);
+        const at_boundary = truncated.replace(/\s+\S*$/, "");
+        return (at_boundary || truncated).slice(0, 50);
+    }
+    #on_create_child = (child) => {
+        if (!this.#session_id) {
+            return;
+        }
+        const child_session = new _a(this.#store, child, {
+            auto_save: this.#auto_save,
+            auto_slug: !child.is_checkpoint && this.#auto_slug,
+        });
+        child_session.fork(this.#session_id, { detached: true }).catch((error) => {
+            this.#event_emitter.emit("lifecycle_error", { error, operation: "fork" });
+        });
+        this.#child_sessions.push(child_session);
+        child.once("dispose", () => {
+            child_session[Symbol.dispose]();
+            const idx = this.#child_sessions.indexOf(child_session);
+            if (idx >= 0) {
+                this.#child_sessions.splice(idx, 1);
+            }
+        });
+    };
+    #on_message_complete = () => {
+        if (this.#session_id) {
+            this.save().catch((error) => {
+                this.#event_emitter.emit("lifecycle_error", {
+                    error,
+                    operation: "save",
+                    context: { session_id: this.#session_id },
+                });
+            });
+        }
+    };
+    #on_conversation_dispose = () => this[Symbol.dispose]();
+}
+_a = SessionManager;
+//# sourceMappingURL=session-manager.js.map

package/dist/session-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.js","sourceRoot":"","sources":["../src/session-manager.ts"],"names":[],"mappings":";AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,YAAY,MAAM,aAAa,CAAC;AASvC;;;;;;GAMG;AACH,MAAM,OAAO,cAAc;IAChB,MAAM,CAAe;IACrB,aAAa,CAAe;IAC5B,UAAU,CAAU;IACpB,UAAU,CAAU;IACpB,cAAc,GAAG,IAAI,YAAY,EAAwB,CAAC;IAC1D,eAAe,GAAqB,EAAE,CAAC;IAEhD,WAAW,CAAU;IACrB,YAAY,GAAG,CAAC,CAAC;IACjB,UAAU,GAAG,KAAK,CAAC;IACnB,SAAS,GAAG,KAAK,CAAC;IAElB;;;;;;OAMG;IACH,YAAY,KAAmB,EAAE,YAA0B,EAAE,OAA+B;QAC1F,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,aAAa,GAAG,YAAY,CAAC;QAClC,IAAI,CAAC,UAAU,GAAG,OAAO,EAAE,SAAS,IAAI,IAAI,CAAC;QAC7C,IAAI,CAAC,UAAU,GAAG,OAAO,EAAE,SAAS,IAAI,IAAI,CAAC;QAE7C,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC,kBAAkB,EAAE,IAAI,CAAC,oBAAoB,CAAC,CAAC;QACvE,CAAC;QACD,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC,cAAc,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC;QAC7D,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,wBAAwB,CAAC,CAAC;IACpE,CAAC;IAED;;;;OAIG;IACH,IAAI,kBAAkB;QACpB,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED;;;;OAIG;IACH,IAAI,SAAS;QACX,OAAO,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC;IAC5B,CAAC;IAED;;;;;;OAMG;IACH,CAAC,MAAM,CAAC,OAAO,CAAC;QACd,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QAEtB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACzC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1B,CAAC;QACD,IAAI,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,CAAC;QAEhC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,kBAAkB,EAAE,IAAI,CAAC,oBAAoB,CAAC,CAAC;QACtE,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,cAAc,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC;QAC9D,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,wBAAwB,CAAC,CAAC;QACjE,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACpC,IAAI,CAAC,cAAc,CAAC,kBAAkB,EAAE,CAAC;IAC3C,CAAC;IAED;;;;;;;;OAQG;IACH,SAAS,CAAC,KAAc;QACtB,IAAI,CAAC,WAAW,GAAG,UAAU,EAAE,CAAC;QAChC,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC;QAC1B,IAAI,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3C,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;QAC7B,CAAC;QACD,IAAI,KAAK,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YAC7B,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;gBACnC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,iBAAiB,EAAE;oBAC1C,KAAK;oBACL,SAAS,EAAE,MAAM;oBACjB,OAAO,EAAE,EAAE,UAAU,EAAE,IAAI,CAAC,WAAW,EAAE;iBAC1C,CAAC,CAAC;YACL,CAAC,CAAC,CAAC;QACL,CAAC;QACD,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,IAAI,CAAC,iBAAyB,EAAE,OAAgC;QACpE,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,KAAK,CAAC;QAC5C,IAAI,CAAC,WAAW,GAAG,UAAU,EAAE,CAAC;QAChC,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;QACxB,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;QAC7B,CAAC;QAED,IAAI,eAAmC,CAAC;QAExC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC,iBAAiB,CAAC,CAAC;YACjE,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACxB,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBAClC,IAAI,CAAC,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC;gBACpC,eAAe,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;YACxC,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;YACxB,CAAC;QACH,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;QACxB,CAAC;QAED,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QAChE,IAAI,aAAa,EAAE,QAAQ,CAAC,gBAAgB,EAAE,CAAC;YAC7C,IAAI,CAAC,aAAa,CAAC,gBAAgB,GAAG,aAAa,CAAC,QAAQ,CAAC,gBAAgB,CAAC;QAChF,CAAC;QAED,MAAM,IAAI,CAAC,IAAI,CAAC;YACd,SAAS,EAAE,iBAAiB;YAC5B,eAAe;YACf,QAAQ;SACT,CAAC,CAAC;QAEH,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,IAAI,CAAC,EAAW;QACpB,IAAI,EAAE,EAAE,CAAC;YACP,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC,EAAE,CAAC,CAAC;YAClD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC1C,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CAAC,sBAAsB,EAAE,EAAE,CAAC,CAAC;YAC9C,CAAC;YACD,IAAI,CAAC,WAAW,GAAG,EAAE,CAAC;YACtB,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;YAC1C,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;YAC3B,IAAI,CAAC,YAAY,GAAG,QAAQ,CAAC,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;YAC7D,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAClC,IAAI,CAAC,aAAa,CAAC,gBAAgB,GAAG,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAC;YACvE,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;YAC1B,OAAO;QACT,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAC1C,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;YACrB,IAAI,CAAC,SAAS,EAAE,CAAC;YACjB,OAAO;QACT,CAAC;QAED,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;QAC3B,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC9B,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,IAAI,CACR,QAKC;QAED,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;QACvC,CAAC;QACD,MAAM,YAAY,GAAG,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC;QACjD,MAAM,cAAc,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAElE,IAAI,IAAI,CAAC,UAAU,IAAI,CAAC,QAAQ,EAAE,KAAK,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YAC5D,MAAM,IAAI,GAAG,EAAc,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC;YACvD,IAAI,IAAI,EAAE,CAAC;gBACT,QAAQ,GAAG,EAAE,GAAG,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;gBACxC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;YACzB,CAAC;QACH,CAAC;QAED,MAAM,qBAAqB,GAA6B,EAAE,GAAG,QAAQ,EAAE,CAAC;QACxE,IAAI,IAAI,CAAC,aAAa,CAAC,aAAa,EAAE,CAAC;YACrC,qBAAqB,CAAC,aAAa,GAAG,IAAI,CAAC;QAC7C,CAAC;QACD,MAAM,gBAAgB,GAAG,IAAI,CAAC,aAAa,CAAC,gBAAgB,CAAC;QAC7D,IAAI,gBAAgB,EAAE,CAAC;YACrB,qBAAqB,CAAC,gBAAgB,GAAG,EAAE,GAAG,gBAAgB,EAAE,CAAC;QACnE,CAAC;QAED,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,cAAc,EAAE,qBAAqB,CAAC,CAAC;QAEhF,8DAA8D;QAC7D,IAAI,CAAC,cAAsB,CAAC,IAAI,CAAC,MAAM,EAAE;YACxC,EAAE,EAAE,IAAI,CAAC,WAAW;YACpB,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC;SAC3C,CAAC,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,IAAI;QACR,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IAC5B,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,MAAM,CAAC,EAAU;QACrB,IAAI,EAAE,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC;YAC5B,IAAI,CAAC,WAAW,GAAG,SAAS,CAAC;YAC7B,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;QAC7B,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAChC,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,MAAM,CAAC,EAAU,EAAE,KAAa;QACpC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC1C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,sBAAsB,EAAE,EAAE,CAAC,CAAC;QAC9C,CAAC;QACD,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QACvD,IAAI,EAAE,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC;YAC5B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACzB,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,EAAE,CACA,KAAQ,EACR,QAAoD;QAEpD,8DAA8D;QAC7D,IAAI,CAAC,cAAsB,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACjD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACH,GAAG,CACD,KAAQ,EACR,QAAoD;QAEpD,8DAA8D;QAC7D,IAAI,CAAC,cAAsB,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QAClD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,UAAU,CAAC,QAA6B;QACtC,8DAA8D;QAC7D,IAAI,CAAC,cAAsB,CAAC,IAAI,CAAC,MAAM,EAAE;YACxC,EAAE,EAAE,IAAI,CAAC,WAAW;YACpB,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC;SACvC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,iBAAiB,CAAC,EAAU;QAChC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC1C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC;QAEtC,IAAI,QAAQ,CAAC,SAAS,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;YAC7C,MAAM,eAAe,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;YACzE,IAAI,QAAQ,CAAC,eAAe,EAAE,CAAC;gBAC7B,MAAM,GAAG,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,QAAQ,CAAC,eAAe,CAAC,CAAC;gBAChF,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;oBACb,OAAO,CAAC,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,EAAE,GAAG,QAAQ,CAAC,CAAC;gBAC7D,CAAC;YACH,CAAC;YACD,OAAO,CAAC,GAAG,eAAe,EAAE,GAAG,QAAQ,CAAC,CAAC;QAC3C,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,CAAC,YAAY,CAAC,QAAsC;QACxD,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;QAC3D,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;QACvE,IAAI,CAAC,YAAY,IAAI,YAAY,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC;YACxE,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACrC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACnC,MAAM,WAAW,GAAG,SAAS,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QACrD,OAAO,CAAC,WAAW,IAAI,SAAS,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACjD,CAAC;IAED,gBAAgB,GAAG,CAAC,KAAmB,EAAE,EAAE;QACzC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,OAAO;QACT,CAAC;QAED,MAAM,aAAa,GAAG,IAAI,EAAc,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE;YAC3D,SAAS,EAAE,IAAI,CAAC,UAAU;YAC1B,SAAS,EAAE,CAAC,KAAK,CAAC,aAAa,IAAI,IAAI,CAAC,UAAU;SACnD,CAAC,CAAC;QACH,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YACvE,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,iBAAiB,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;QAC5E,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAEzC,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE;YACzB,aAAa,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;YAChC,MAAM,GAAG,GAAG,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;YACxD,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;gBACb,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YACtC,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,oBAAoB,GAAG,GAAG,EAAE;QAC1B,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;gBAC1B,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,iBAAiB,EAAE;oBAC1C,KAAK;oBACL,SAAS,EAAE,MAAM;oBACjB,OAAO,EAAE,EAAE,UAAU,EAAE,IAAI,CAAC,WAAW,EAAE;iBAC1C,CAAC,CAAC;YACL,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC;IAEF,wBAAwB,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;CACzD"}

package/dist/types.d.ts

@@ -0,0 +1,114 @@
+import type { CheckpointState, LifecycleErrorEvent, Message } 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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: [];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAExF;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,EAAE,EAAE,MAAM,CAAC;IACX,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,aAAa,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,kEAAkE;IAClE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,yDAAyD;IACzD,gBAAgB,CAAC,EAAE,eAAe,CAAC;CACpC;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IAEnC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,eAAe,CAAC;QAAC,QAAQ,EAAE,OAAO,EAAE,CAAA;KAAE,GAAG,SAAS,CAAC,CAAC;IAE1F;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,QAAQ,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1F;;;;;OAKG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,wCAAwC;IACxC,IAAI,EAAE,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;KAAE,CAAC,CAAC;IACtD,uCAAuC;IACvC,IAAI,EAAE,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;KAAE,CAAC,CAAC;IACtD,mEAAmE;IACnE,eAAe,EAAE,CAAC,mBAAmB,CAAC,CAAC;IACvC,mDAAmD;IACnD,OAAO,EAAE,EAAE,CAAC;CACb"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@simulacra-ai/session",
+  "version": "0.0.1",
+  "description": "Session persistence for the Simulacra conversation engine — pluggable storage with file and in-memory providers",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "peerDependencies": {
+    "@simulacra-ai/core": "0.0.1"
+  },
+  "license": "MIT"
+}