@dexto/core 1.3.0 → 1.5.0

package/dist/session/history/database.cjs

@@ -24,47 +24,58 @@ module.exports = __toCommonJS(database_exports);
 var import_types = require("../../logger/v2/types.cjs");
 var import_errors = require("../errors.js");
 class DatabaseHistoryProvider {
+  // Debounce window for batching updates
   constructor(sessionId, database, logger) {
     this.sessionId = sessionId;
     this.database = database;
     this.logger = logger.createChild(import_types.DextoLogComponent.SESSION);
   }
   logger;
+  // Cache state
+  cache = null;
+  dirty = false;
+  flushTimer = null;
+  flushPromise = null;
+  // Flush configuration
+  static FLUSH_DELAY_MS = 100;
   async getHistory() {
-    const key = this.getMessagesKey();
-    try {
-      const messages = await this.database.getRange(key, 0, 1e3);
-      this.logger.debug(
-        `DatabaseHistoryProvider: Retrieved ${messages.length} messages for session ${this.sessionId}`
-      );
-      return messages;
-    } catch (error) {
-      this.logger.error(
-        `DatabaseHistoryProvider: Error retrieving messages for session ${this.sessionId}: ${error instanceof Error ? error.message : String(error)}`
-      );
-      return [];
+    if (this.cache === null) {
+      const key = this.getMessagesKey();
+      try {
+        this.cache = await this.database.getRange(key, 0, 1e4);
+        this.logger.debug(
+          `DatabaseHistoryProvider: Loaded ${this.cache.length} messages from DB for session ${this.sessionId}`
+        );
+      } catch (error) {
+        this.logger.error(
+          `DatabaseHistoryProvider: Error loading messages for session ${this.sessionId}: ${error instanceof Error ? error.message : String(error)}`
+        );
+        throw import_errors.SessionError.storageFailed(
+          this.sessionId,
+          "load history",
+          error instanceof Error ? error.message : String(error)
+        );
+      }
     }
+    return [...this.cache];
   }
   async saveMessage(message) {
     const key = this.getMessagesKey();
+    if (this.cache === null) {
+      await this.getHistory();
+    }
+    this.cache.push(message);
     try {
       await this.database.append(key, message);
-      let contentPreview = "[no content]";
-      if (message.content) {
-        if (typeof message.content === "string") {
-          contentPreview = message.content.length > 100 ? `${message.content.substring(0, 100)}...` : message.content;
-        } else if (Array.isArray(message.content)) {
-          contentPreview = `[${message.content.length} parts]`;
-        }
-      }
       this.logger.debug(
         `DatabaseHistoryProvider: Saved message for session ${this.sessionId}`,
         {
           role: message.role,
-          content: contentPreview
+          id: message.id
         }
       );
     } catch (error) {
+      this.cache.pop();
       this.logger.error(
         `DatabaseHistoryProvider: Error saving message for session ${this.sessionId}: ${error instanceof Error ? error.message : String(error)}`
       );
@@ -75,7 +86,34 @@ class DatabaseHistoryProvider {
       );
     }
   }
+  async updateMessage(message) {
+    if (!message.id) {
+      this.logger.warn(
+        `DatabaseHistoryProvider: Ignoring update for message without id in session ${this.sessionId}`
+      );
+      return;
+    }
+    if (this.cache === null) {
+      await this.getHistory();
+    }
+    const index = this.cache.findIndex((m) => m.id === message.id);
+    if (index !== -1) {
+      this.cache[index] = message;
+      this.dirty = true;
+      this.scheduleFlush();
+      this.logger.debug(
+        `DatabaseHistoryProvider: Updated message ${message.id} in cache for session ${this.sessionId}`
+      );
+    } else {
+      this.logger.warn(
+        `DatabaseHistoryProvider: Message ${message.id} not found for update in session ${this.sessionId}`
+      );
+    }
+  }
   async clearHistory() {
+    this.cancelPendingFlush();
+    this.cache = [];
+    this.dirty = false;
     const key = this.getMessagesKey();
     try {
       await this.database.delete(key);
@@ -92,6 +130,81 @@ class DatabaseHistoryProvider {
       );
     }
   }
+  /**
+   * Flush any pending updates to the database.
+   * Should be called at turn boundaries to ensure durability.
+   */
+  async flush() {
+    if (this.flushPromise) {
+      await this.flushPromise;
+      return;
+    }
+    this.cancelPendingFlush();
+    if (!this.dirty || !this.cache) {
+      return;
+    }
+    this.flushPromise = this.doFlush();
+    try {
+      await this.flushPromise;
+    } finally {
+      this.flushPromise = null;
+    }
+  }
+  /**
+   * Internal flush implementation.
+   * Writes entire cache to DB (delete + re-append all).
+   */
+  async doFlush() {
+    if (!this.dirty || !this.cache) {
+      return;
+    }
+    const key = this.getMessagesKey();
+    const messageCount = this.cache.length;
+    try {
+      await this.database.delete(key);
+      for (const msg of this.cache) {
+        await this.database.append(key, msg);
+      }
+      if (!this.flushTimer) {
+        this.dirty = false;
+      }
+      this.logger.debug(
+        `DatabaseHistoryProvider: Flushed ${messageCount} messages to DB for session ${this.sessionId}`
+      );
+    } catch (error) {
+      this.logger.error(
+        `DatabaseHistoryProvider: Error flushing messages for session ${this.sessionId}: ${error instanceof Error ? error.message : String(error)}`
+      );
+      throw import_errors.SessionError.storageFailed(
+        this.sessionId,
+        "flush messages",
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+  /**
+   * Schedule a debounced flush.
+   * Batches rapid updateMessage() calls into a single DB write.
+   */
+  scheduleFlush() {
+    if (this.flushTimer) {
+      return;
+    }
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = null;
+      this.doFlush().catch(() => {
+      });
+    }, DatabaseHistoryProvider.FLUSH_DELAY_MS);
+  }
+  /**
+   * Cancel any pending scheduled flush.
+   */
+  cancelPendingFlush() {
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+  }
   getMessagesKey() {
     return `messages:${this.sessionId}`;
   }

package/dist/session/history/database.d.ts

@@ -4,24 +4,53 @@ import type { InternalMessage } from '../../context/types.js';
 import type { IConversationHistoryProvider } from './types.js';
 /**
  * History provider that works directly with DatabaseBackend.
- * Handles message-specific operations and key formatting internally.
+ * Uses write-through caching for read performance while maintaining durability.
  *
- * TODO: Add in-memory caching to reduce database queries.
- * Cache should be invalidated on writes and persist across LLM switches.
- * Consider caching strategy:
- * - Load cache on first getHistory() call
- * - Update cache optimistically on saveMessage()
- * - Clear cache on clearHistory()
- * This will significantly improve performance for sessions with many messages.
+ * Caching strategy:
+ * - getHistory(): Returns cached messages after first load (eliminates repeated DB reads)
+ * - saveMessage(): Updates cache AND writes to DB immediately (new messages are critical)
+ * - updateMessage(): Updates cache immediately, debounces DB writes (batches rapid updates)
+ * - flush(): Forces all pending updates to DB (called at turn boundaries)
+ * - clearHistory(): Clears cache and DB immediately
+ *
+ * Durability guarantees:
+ * - New messages (saveMessage) are always immediately durable
+ * - Updates (updateMessage) are durable within flush interval or on explicit flush()
+ * - Worst case on crash: lose updates from last flush interval (typically <100ms)
  */
 export declare class DatabaseHistoryProvider implements IConversationHistoryProvider {
     private sessionId;
     private database;
     private logger;
+    private cache;
+    private dirty;
+    private flushTimer;
+    private flushPromise;
+    private static readonly FLUSH_DELAY_MS;
     constructor(sessionId: string, database: Database, logger: IDextoLogger);
     getHistory(): Promise<InternalMessage[]>;
     saveMessage(message: InternalMessage): Promise<void>;
+    updateMessage(message: InternalMessage): Promise<void>;
     clearHistory(): Promise<void>;
+    /**
+     * Flush any pending updates to the database.
+     * Should be called at turn boundaries to ensure durability.
+     */
+    flush(): Promise<void>;
+    /**
+     * Internal flush implementation.
+     * Writes entire cache to DB (delete + re-append all).
+     */
+    private doFlush;
+    /**
+     * Schedule a debounced flush.
+     * Batches rapid updateMessage() calls into a single DB write.
+     */
+    private scheduleFlush;
+    /**
+     * Cancel any pending scheduled flush.
+     */
+    private cancelPendingFlush;
     private getMessagesKey;
 }
 //# sourceMappingURL=database.d.ts.map

package/dist/session/history/database.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../../src/session/history/database.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAE/D;;;;;;;;;;;GAWG;AACH,qBAAa,uBAAwB,YAAW,4BAA4B;IAIpE,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,QAAQ;IAJpB,OAAO,CAAC,MAAM,CAAe;gBAGjB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,QAAQ,EAC1B,MAAM,EAAE,YAAY;IAKlB,UAAU,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAmBxC,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAqCpD,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAkBnC,OAAO,CAAC,cAAc;CAGzB"}
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../../src/session/history/database.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAE/D;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,uBAAwB,YAAW,4BAA4B;IAapE,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,QAAQ;IAbpB,OAAO,CAAC,MAAM,CAAe;IAG7B,OAAO,CAAC,KAAK,CAAkC;IAC/C,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,UAAU,CAA8C;IAChE,OAAO,CAAC,YAAY,CAA8B;IAGlD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAO;gBAGjC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,QAAQ,EAC1B,MAAM,EAAE,YAAY;IAKlB,UAAU,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAyBxC,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAoCpD,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAiCtD,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IA0BnC;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAwB5B;;;OAGG;YACW,OAAO;IAoCrB;;;OAGG;IACH,OAAO,CAAC,aAAa;IAerB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,cAAc;CAGzB"}

package/dist/session/history/database.js

@@ -1,48 +1,59 @@
-import "../../chunk-C6A6W6XS.js";
+import "../../chunk-PTJYTZNU.js";
 import { DextoLogComponent } from "../../logger/v2/types.js";
 import { SessionError } from "../errors.js";
 class DatabaseHistoryProvider {
+  // Debounce window for batching updates
   constructor(sessionId, database, logger) {
     this.sessionId = sessionId;
     this.database = database;
     this.logger = logger.createChild(DextoLogComponent.SESSION);
   }
   logger;
+  // Cache state
+  cache = null;
+  dirty = false;
+  flushTimer = null;
+  flushPromise = null;
+  // Flush configuration
+  static FLUSH_DELAY_MS = 100;
   async getHistory() {
-    const key = this.getMessagesKey();
-    try {
-      const messages = await this.database.getRange(key, 0, 1e3);
-      this.logger.debug(
-        `DatabaseHistoryProvider: Retrieved ${messages.length} messages for session ${this.sessionId}`
-      );
-      return messages;
-    } catch (error) {
-      this.logger.error(
-        `DatabaseHistoryProvider: Error retrieving messages for session ${this.sessionId}: ${error instanceof Error ? error.message : String(error)}`
-      );
-      return [];
+    if (this.cache === null) {
+      const key = this.getMessagesKey();
+      try {
+        this.cache = await this.database.getRange(key, 0, 1e4);
+        this.logger.debug(
+          `DatabaseHistoryProvider: Loaded ${this.cache.length} messages from DB for session ${this.sessionId}`
+        );
+      } catch (error) {
+        this.logger.error(
+          `DatabaseHistoryProvider: Error loading messages for session ${this.sessionId}: ${error instanceof Error ? error.message : String(error)}`
+        );
+        throw SessionError.storageFailed(
+          this.sessionId,
+          "load history",
+          error instanceof Error ? error.message : String(error)
+        );
+      }
     }
+    return [...this.cache];
   }
   async saveMessage(message) {
     const key = this.getMessagesKey();
+    if (this.cache === null) {
+      await this.getHistory();
+    }
+    this.cache.push(message);
     try {
       await this.database.append(key, message);
-      let contentPreview = "[no content]";
-      if (message.content) {
-        if (typeof message.content === "string") {
-          contentPreview = message.content.length > 100 ? `${message.content.substring(0, 100)}...` : message.content;
-        } else if (Array.isArray(message.content)) {
-          contentPreview = `[${message.content.length} parts]`;
-        }
-      }
       this.logger.debug(
         `DatabaseHistoryProvider: Saved message for session ${this.sessionId}`,
         {
           role: message.role,
-          content: contentPreview
+          id: message.id
         }
       );
     } catch (error) {
+      this.cache.pop();
       this.logger.error(
         `DatabaseHistoryProvider: Error saving message for session ${this.sessionId}: ${error instanceof Error ? error.message : String(error)}`
       );
@@ -53,7 +64,34 @@ class DatabaseHistoryProvider {
       );
     }
   }
+  async updateMessage(message) {
+    if (!message.id) {
+      this.logger.warn(
+        `DatabaseHistoryProvider: Ignoring update for message without id in session ${this.sessionId}`
+      );
+      return;
+    }
+    if (this.cache === null) {
+      await this.getHistory();
+    }
+    const index = this.cache.findIndex((m) => m.id === message.id);
+    if (index !== -1) {
+      this.cache[index] = message;
+      this.dirty = true;
+      this.scheduleFlush();
+      this.logger.debug(
+        `DatabaseHistoryProvider: Updated message ${message.id} in cache for session ${this.sessionId}`
+      );
+    } else {
+      this.logger.warn(
+        `DatabaseHistoryProvider: Message ${message.id} not found for update in session ${this.sessionId}`
+      );
+    }
+  }
   async clearHistory() {
+    this.cancelPendingFlush();
+    this.cache = [];
+    this.dirty = false;
     const key = this.getMessagesKey();
     try {
       await this.database.delete(key);
@@ -70,6 +108,81 @@ class DatabaseHistoryProvider {
       );
     }
   }
+  /**
+   * Flush any pending updates to the database.
+   * Should be called at turn boundaries to ensure durability.
+   */
+  async flush() {
+    if (this.flushPromise) {
+      await this.flushPromise;
+      return;
+    }
+    this.cancelPendingFlush();
+    if (!this.dirty || !this.cache) {
+      return;
+    }
+    this.flushPromise = this.doFlush();
+    try {
+      await this.flushPromise;
+    } finally {
+      this.flushPromise = null;
+    }
+  }
+  /**
+   * Internal flush implementation.
+   * Writes entire cache to DB (delete + re-append all).
+   */
+  async doFlush() {
+    if (!this.dirty || !this.cache) {
+      return;
+    }
+    const key = this.getMessagesKey();
+    const messageCount = this.cache.length;
+    try {
+      await this.database.delete(key);
+      for (const msg of this.cache) {
+        await this.database.append(key, msg);
+      }
+      if (!this.flushTimer) {
+        this.dirty = false;
+      }
+      this.logger.debug(
+        `DatabaseHistoryProvider: Flushed ${messageCount} messages to DB for session ${this.sessionId}`
+      );
+    } catch (error) {
+      this.logger.error(
+        `DatabaseHistoryProvider: Error flushing messages for session ${this.sessionId}: ${error instanceof Error ? error.message : String(error)}`
+      );
+      throw SessionError.storageFailed(
+        this.sessionId,
+        "flush messages",
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+  /**
+   * Schedule a debounced flush.
+   * Batches rapid updateMessage() calls into a single DB write.
+   */
+  scheduleFlush() {
+    if (this.flushTimer) {
+      return;
+    }
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = null;
+      this.doFlush().catch(() => {
+      });
+    }, DatabaseHistoryProvider.FLUSH_DELAY_MS);
+  }
+  /**
+   * Cancel any pending scheduled flush.
+   */
+  cancelPendingFlush() {
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+  }
   getMessagesKey() {
     return `messages:${this.sessionId}`;
   }

package/dist/session/history/factory.js

@@ -1,4 +1,4 @@
-import "../../chunk-C6A6W6XS.js";
+import "../../chunk-PTJYTZNU.js";
 import { DatabaseHistoryProvider } from "./database.js";
 function createDatabaseHistoryProvider(database, sessionId, logger) {
   return new DatabaseHistoryProvider(sessionId, database, logger);

package/dist/session/history/memory.cjs

@@ -22,6 +22,9 @@ __export(memory_exports, {
 });
 module.exports = __toCommonJS(memory_exports);
 class MemoryHistoryProvider {
+  constructor(logger) {
+    this.logger = logger;
+  }
   messages = [];
   async getHistory() {
     return [...this.messages];
@@ -29,9 +32,24 @@ class MemoryHistoryProvider {
   async saveMessage(message) {
     this.messages.push(message);
   }
+  async updateMessage(message) {
+    if (!message.id) {
+      this.logger.warn("MemoryHistoryProvider: Ignoring update for message without id");
+      return;
+    }
+    const index = this.messages.findIndex((m) => m.id === message.id);
+    if (index !== -1) {
+      this.messages[index] = message;
+    }
+  }
   async clearHistory() {
     this.messages = [];
   }
+  /**
+   * No-op for in-memory provider - all operations are already "flushed".
+   */
+  async flush() {
+  }
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/session/history/memory.d.ts

@@ -1,14 +1,22 @@
 import type { InternalMessage } from '../../context/types.js';
 import type { IConversationHistoryProvider } from './types.js';
+import type { IDextoLogger } from '../../logger/v2/types.js';
 /**
  * Lightweight in-memory history provider for ephemeral, isolated LLM calls.
  * Used to run background tasks (e.g., title generation) without touching
  * the real session history or emitting history-related side effects.
  */
 export declare class MemoryHistoryProvider implements IConversationHistoryProvider {
+    private logger;
     private messages;
+    constructor(logger: IDextoLogger);
     getHistory(): Promise<InternalMessage[]>;
     saveMessage(message: InternalMessage): Promise<void>;
+    updateMessage(message: InternalMessage): Promise<void>;
     clearHistory(): Promise<void>;
+    /**
+     * No-op for in-memory provider - all operations are already "flushed".
+     */
+    flush(): Promise<void>;
 }
 //# sourceMappingURL=memory.d.ts.map

package/dist/session/history/memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../src/session/history/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAE/D;;;;GAIG;AACH,qBAAa,qBAAsB,YAAW,4BAA4B;IACtE,OAAO,CAAC,QAAQ,CAAyB;IAEnC,UAAU,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAKxC,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpD,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;CAGtC"}
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../src/session/history/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE7D;;;;GAIG;AACH,qBAAa,qBAAsB,YAAW,4BAA4B;IAG1D,OAAO,CAAC,MAAM;IAF1B,OAAO,CAAC,QAAQ,CAAyB;gBAErB,MAAM,EAAE,YAAY;IAElC,UAAU,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAKxC,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpD,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAYtD,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAInC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B"}

package/dist/session/history/memory.js

@@ -1,5 +1,8 @@
-import "../../chunk-C6A6W6XS.js";
+import "../../chunk-PTJYTZNU.js";
 class MemoryHistoryProvider {
+  constructor(logger) {
+    this.logger = logger;
+  }
   messages = [];
   async getHistory() {
     return [...this.messages];
@@ -7,9 +10,24 @@ class MemoryHistoryProvider {
   async saveMessage(message) {
     this.messages.push(message);
   }
+  async updateMessage(message) {
+    if (!message.id) {
+      this.logger.warn("MemoryHistoryProvider: Ignoring update for message without id");
+      return;
+    }
+    const index = this.messages.findIndex((m) => m.id === message.id);
+    if (index !== -1) {
+      this.messages[index] = message;
+    }
+  }
   async clearHistory() {
     this.messages = [];
   }
+  /**
+   * No-op for in-memory provider - all operations are already "flushed".
+   */
+  async flush() {
+  }
 }
 export {
   MemoryHistoryProvider

package/dist/session/history/types.d.ts

@@ -2,13 +2,25 @@ import type { InternalMessage } from '../../context/types.js';
 /**
  * Session-scoped conversation history provider.
  * Each instance is tied to a specific session and manages only that session's messages.
+ *
+ * Implementations may use caching to optimize read performance. If caching is used,
+ * the flush() method should be called at turn boundaries to ensure all updates
+ * are persisted to durable storage.
  */
 export interface IConversationHistoryProvider {
     /** Load the full message history for this session */
     getHistory(): Promise<InternalMessage[]>;
-    /** Append a message to this session's history */
+    /** Append a message to this session's history (must be durable immediately) */
     saveMessage(message: InternalMessage): Promise<void>;
+    /** Update an existing message in this session's history (may be cached/batched) */
+    updateMessage(message: InternalMessage): Promise<void>;
     /** Clear all messages for this session */
     clearHistory(): Promise<void>;
+    /**
+     * Flush any pending updates to durable storage.
+     * Called at turn boundaries to ensure data durability.
+     * Implementations without caching can make this a no-op.
+     */
+    flush(): Promise<void>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/session/history/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/session/history/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;GAGG;AACH,MAAM,WAAW,4BAA4B;IACzC,qDAAqD;IACrD,UAAU,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IAEzC,iDAAiD;IACjD,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErD,0CAA0C;IAC1C,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACjC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/session/history/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;;;;;GAOG;AACH,MAAM,WAAW,4BAA4B;IACzC,qDAAqD;IACrD,UAAU,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IAEzC,+EAA+E;IAC/E,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErD,mFAAmF;IACnF,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvD,0CAA0C;IAC1C,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9B;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B"}

package/dist/session/index.cjs

@@ -19,6 +19,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var session_exports = {};
 __export(session_exports, {
   ChatSession: () => import_chat_session.ChatSession,
+  MessageQueueService: () => import_message_queue.MessageQueueService,
   SessionError: () => import_errors.SessionError,
   SessionErrorCode: () => import_error_codes.SessionErrorCode,
   SessionManager: () => import_session_manager.SessionManager
@@ -28,9 +29,11 @@ var import_chat_session = require("./chat-session.js");
 var import_session_manager = require("./session-manager.js");
 var import_error_codes = require("./error-codes.js");
 var import_errors = require("./errors.js");
+var import_message_queue = require("./message-queue.js");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ChatSession,
+  MessageQueueService,
   SessionError,
   SessionErrorCode,
   SessionManager

package/dist/session/index.d.ts

@@ -3,4 +3,7 @@ export { SessionManager } from './session-manager.js';
 export type { SessionMetadata } from './session-manager.js';
 export { SessionErrorCode } from './error-codes.js';
 export { SessionError } from './errors.js';
+export { MessageQueueService } from './message-queue.js';
+export type { UserMessageInput } from './message-queue.js';
+export type { QueuedMessage, CoalescedMessage } from './types.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}

package/dist/session/index.js

@@ -1,10 +1,12 @@
-import "../chunk-C6A6W6XS.js";
+import "../chunk-PTJYTZNU.js";
 import { ChatSession } from "./chat-session.js";
 import { SessionManager } from "./session-manager.js";
 import { SessionErrorCode } from "./error-codes.js";
 import { SessionError } from "./errors.js";
+import { MessageQueueService } from "./message-queue.js";
 export {
   ChatSession,
+  MessageQueueService,
   SessionError,
   SessionErrorCode,
   SessionManager