@simulacra-ai/session 0.0.3 → 0.0.5

package/dist/index.cjs

@@ -0,0 +1,693 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DrizzleSessionStore: () => DrizzleSessionStore,
+  FileSessionStore: () => FileSessionStore,
+  InMemorySessionStore: () => InMemorySessionStore,
+  SessionManager: () => SessionManager
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/session-manager.ts
+var import_node_crypto = require("crypto");
+var import_node_events = __toESM(require("events"), 1);
+var SessionManager = class _SessionManager {
+  #store;
+  #conversation;
+  #auto_save;
+  #auto_slug;
+  #event_emitter = new import_node_events.default();
+  #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 = (0, import_node_crypto.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 = (0, import_node_crypto.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 = _SessionManager.#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);
+    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 = void 0;
+      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) {
+    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) {
+    this.#event_emitter.off(event, listener);
+    return this;
+  }
+  #emit_load(messages) {
+    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 void 0;
+    }
+    const text_content = first_user.content.find((c) => c.type === "text");
+    if (!text_content || text_content.type !== "text" || !text_content.text) {
+      return void 0;
+    }
+    const raw = text_content.text.trim();
+    if (!raw) {
+      return void 0;
+    }
+    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 _SessionManager(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]();
+};
+
+// src/file-session-store.ts
+var import_promises = __toESM(require("fs/promises"), 1);
+var import_node_path = __toESM(require("path"), 1);
+var FileSessionStore = class {
+  #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 import_promises.default.readdir(this.#root, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith(".json")) {
+        continue;
+      }
+      const session = await this.#read_session(
+        import_node_path.default.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(import_node_path.default.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 = (/* @__PURE__ */ new Date()).toISOString();
+    await this.#ensure_dir();
+    const file_path = import_node_path.default.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 import_promises.default.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 = import_node_path.default.join(this.#root, `${id}.json`);
+    try {
+      const result = await this.#read_file(file_path, id);
+      await import_promises.default.unlink(file_path);
+      if (result?.metadata.parent_id) {
+        const link = import_node_path.default.join(this.#root, `${result.metadata.parent_id}-forks`, `${id}.json`);
+        try {
+          await import_promises.default.unlink(link);
+        } catch {
+        }
+      }
+      const fork_dir = import_node_path.default.join(this.#root, `${id}-forks`);
+      try {
+        await import_promises.default.rm(fork_dir, { recursive: true });
+      } catch {
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async #ensure_fork_link(parent_id, fork_id) {
+    const fork_dir = import_node_path.default.join(this.#root, `${parent_id}-forks`);
+    await import_promises.default.mkdir(fork_dir, { recursive: true });
+    const canonical = import_node_path.default.join(this.#root, `${fork_id}.json`);
+    const link = import_node_path.default.join(fork_dir, `${fork_id}.json`);
+    try {
+      await import_promises.default.unlink(link);
+    } catch {
+    }
+    try {
+      await import_promises.default.link(canonical, link);
+    } catch {
+    }
+  }
+  async #read_file(file_path, id) {
+    try {
+      const content = await import_promises.default.readFile(file_path, "utf8");
+      const data = JSON.parse(content);
+      return {
+        metadata: { id, ...data.metadata },
+        messages: data.messages
+      };
+    } catch {
+      return void 0;
+    }
+  }
+  async #read_session(file_path, id) {
+    try {
+      const content = await import_promises.default.readFile(file_path, "utf8");
+      const data = JSON.parse(content);
+      return { id, ...data.metadata };
+    } catch {
+      return void 0;
+    }
+  }
+  async #ensure_dir() {
+    await import_promises.default.mkdir(this.#root, { recursive: true });
+  }
+};
+
+// src/in-memory-session-store.ts
+var InMemorySessionStore = class {
+  #sessions = /* @__PURE__ */ 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 void 0;
+    }
+    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 = (/* @__PURE__ */ 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);
+  }
+};
+
+// src/drizzle-session-store.ts
+var DrizzleSessionStore = class {
+  #adapter;
+  constructor(adapter) {
+    this.#adapter = adapter;
+  }
+  /**
+   * Lists all sessions, sorted by most recently updated first.
+   *
+   * @returns A promise that resolves to an array of session metadata.
+   */
+  async list() {
+    const rows = await this.#adapter.list();
+    return rows.map((row) => ({
+      id: row.id,
+      ...row.metadata
+    }));
+  }
+  /**
+   * 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.
+   */
+  async load(id) {
+    const row = await this.#adapter.load(id);
+    if (!row) {
+      return void 0;
+    }
+    return {
+      metadata: {
+        id,
+        ...row.metadata
+      },
+      messages: row.messages
+    };
+  }
+  /**
+   * Saves a session with the given messages and metadata.
+   *
+   * Creates a new session if the ID does not exist, or updates the 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 = (/* @__PURE__ */ new Date()).toISOString();
+    const existing = await this.#adapter.load(id);
+    const existing_metadata = existing?.metadata;
+    const merged = {
+      ...existing_metadata,
+      created_at: existing_metadata?.created_at ?? now,
+      updated_at: now,
+      message_count: messages.length,
+      ...metadata
+    };
+    await this.#adapter.upsert({
+      id,
+      metadata: merged,
+      messages,
+      updated_at: now
+    });
+  }
+  /**
+   * 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.
+   */
+  async delete(id) {
+    return this.#adapter.delete(id);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DrizzleSessionStore,
+  FileSessionStore,
+  InMemorySessionStore,
+  SessionManager
+});
+//# sourceMappingURL=index.cjs.map