@dr33m/react-native-litert-lm 0.5.5 → 0.6.0

package/android/src/main/java/com/margelo/nitro/dev/litert/litertlm/HybridLiteRTLM.kt

@@ -563,6 +563,26 @@ class HybridLiteRTLM : HybridLiteRTLMSpec() {
         createNewConversation()
     }
 
+    override fun resetConversationWith(messages: Array<Message>) {
+        val seed = messages.map { msg ->
+            LiteRTMessage(
+                role = when (msg.role) {
+                    Role.MODEL -> com.google.ai.edge.litertlm.Role.MODEL
+                    Role.SYSTEM -> com.google.ai.edge.litertlm.Role.SYSTEM
+                    else -> com.google.ai.edge.litertlm.Role.USER
+                },
+                contents = Contents.of(Content.Text(msg.content))
+            )
+        }
+        synchronized(history) {
+            history.clear()
+            history.addAll(messages.toList())
+        }
+        // Recreating the conversation is what actually frees the old KV cache;
+        // the seed is replayed into the new one without triggering generation.
+        createNewConversation(seed)
+    }
+
     override fun isReady(): Boolean {
         return isLoaded_
     }
@@ -575,7 +595,10 @@ class HybridLiteRTLM : HybridLiteRTLMSpec() {
         return lastStats
     }
 
-    override fun getMemoryUsage(): MemoryUsage {
+    /** Shared by the public [getMemoryUsage] override and the pre-flight guard
+     * in [execute] — both need the same real, OS-level reading, not an
+     * estimate. */
+    private fun currentMemoryUsage(): MemoryUsage {
         // Native heap: allocated bytes from Debug APIs (most accurate for native allocations)
         val nativeHeapBytes = Debug.getNativeHeapAllocatedSize().toDouble()
 
@@ -619,6 +642,8 @@ class HybridLiteRTLM : HybridLiteRTLMSpec() {
         )
     }
 
+    override fun getMemoryUsage(): MemoryUsage = currentMemoryUsage()
+
     override fun checkModelCapabilities(modelPath: String): ModelCapabilities {
         var supportsSpeculativeDecoding = false
         try {
@@ -668,7 +693,7 @@ class HybridLiteRTLM : HybridLiteRTLMSpec() {
         }
     }
 
-    private fun createNewConversation() {
+    private fun createNewConversation(initialMessages: List<LiteRTMessage> = emptyList()) {
         ensureLoaded()
         // v0.10.2 enforces single-session: close existing conversation first
         conversation?.let { oldConv ->
@@ -711,6 +736,7 @@ class HybridLiteRTLM : HybridLiteRTLMSpec() {
                 temperature = temperature.toDouble(),
             ),
             systemInstruction = systemPrompt?.let { Contents.of(Content.Text(it)) },
+            initialMessages = initialMessages,
             tools = lmTools ?: emptyList()
         )
         // TODO: maxOutputTokens is not configurable on Android — the Kotlin SDK's
@@ -784,6 +810,16 @@ class HybridLiteRTLM : HybridLiteRTLMSpec() {
 
         return Promise.parallel {
             ensureLoaded()
+
+            // Refuse rather than risk it: growing the KV-cache under real memory
+            // pressure can fail at the native engine level in a way that never
+            // surfaces as a catchable Kotlin exception — it takes the whole
+            // process down. A plain RuntimeException here is a normal rejected
+            // Promise for callers, same contract as any other execute() failure.
+            if (currentMemoryUsage().isLowMemory) {
+                throw RuntimeException("LiteRTLM: Device memory is critically low; refusing to continue generation.")
+            }
+
             // Clear any previous tool calls before new inference
             pendingToolCalls.clear()
 

package/ios/HybridLiteRTLM+Execute.swift

@@ -80,6 +80,18 @@ extension HybridLiteRTLM {
                 return
             }
 
+            // Refuse rather than risk it: growing the KV-cache under real memory
+            // pressure can fail inside the underlying C engine in a way that
+            // never surfaces as a catchable Swift error — it takes the whole
+            // process down (Jetsam or a hard native failure). An NSError here
+            // is a normal rejected Promise for callers, same contract as any
+            // other execute() failure.
+            if Self.currentMemoryUsage().isLowMemory {
+                promise.reject(withError: NSError(domain: "LiteRTLM", code: 507,
+                    userInfo: [NSLocalizedDescriptionKey: "LiteRTLM: Device memory is critically low; refusing to continue generation."]))
+                return
+            }
+
             let payload: (json: String, tempFiles: [String])
             do { payload = try self.buildExecutePayload(preprocessed) }
             catch { promise.reject(withError: error); return }

package/ios/HybridLiteRTLM.swift

@@ -92,6 +92,26 @@ public class HybridLiteRTLM: HybridLiteRTLMSpec_base, HybridLiteRTLMSpec_protoco
         }
     }
     
+    public func resetConversationWith(messages: [Message]) throws {
+        queue.sync {
+            history = messages
+            lastStats = GenerationStats(
+                promptTokens: 0.0,
+                completionTokens: 0.0,
+                totalTokens: 0.0,
+                timeToFirstToken: 0.0,
+                totalTime: 0.0,
+                tokensPerSecond: 0.0
+            )
+            if isLoaded && engine != nil {
+                // Recreating the conversation is what actually frees the old KV
+                // cache; the seed is replayed into the new one without
+                // triggering generation.
+                createNewConversation(initialMessages: messages)
+            }
+        }
+    }
+
     public func getStats() throws -> GenerationStats {
         return queue.sync { lastStats }
     }
@@ -111,9 +131,18 @@ public class HybridLiteRTLM: HybridLiteRTLMSpec_base, HybridLiteRTLMSpec_protoco
     }
     
     public func getMemoryUsage() throws -> MemoryUsage {
+        return Self.currentMemoryUsage()
+    }
+
+    /// Shared by the public `getMemoryUsage()` override and the pre-flight
+    /// guard in `HybridLiteRTLM+Execute.swift` — both need the same real,
+    /// OS-level reading, not an estimate. `static` since it needs no
+    /// instance state, which also makes it trivially callable from the
+    /// extension file.
+    static func currentMemoryUsage() -> MemoryUsage {
         var residentBytes: Double = 0.0
         var nativeHeapBytes: Double = 0.0
-        
+
         // Retrieve process resident set size (RSS) via Mach basic task info
         var info = mach_task_basic_info()
         var count = mach_msg_type_number_t(MemoryLayout<mach_task_basic_info>.size / MemoryLayout<integer_t>.size)
@@ -122,18 +151,18 @@ public class HybridLiteRTLM: HybridLiteRTLMSpec_base, HybridLiteRTLMSpec_protoco
                 task_info(mach_task_self_, task_flavor_t(MACH_TASK_BASIC_INFO), $0, &count)
             }
         }
-        
+
         if kerr == KERN_SUCCESS {
             residentBytes = Double(info.resident_size)
             nativeHeapBytes = Double(info.resident_size)
         }
-        
+
         // os_proc_available_memory reports actual headroom available before Jetsam termination (iOS 13+)
         let availableBytes = Double(os_proc_available_memory())
-        
+
         // Flag memory warning at ~200MB remaining headroom
         let isLowMemory = availableBytes < 200.0 * 1024.0 * 1024.0
-        
+
         return MemoryUsage(
             nativeHeapBytes: nativeHeapBytes,
             residentBytes: residentBytes,
@@ -384,7 +413,7 @@ public class HybridLiteRTLM: HybridLiteRTLMSpec_base, HybridLiteRTLMSpec_protoco
     
     // MARK: - Internal Engine Helpers
     
-    private func createNewConversation() {
+    private func createNewConversation(initialMessages: [Message] = []) {
         guard let engine = self.engine else { return }
         
         if let oldConv = self.conversation {
@@ -437,6 +466,24 @@ public class HybridLiteRTLM: HybridLiteRTLMSpec_base, HybridLiteRTLMSpec_protoco
             }
         }
         
+        if !initialMessages.isEmpty {
+            let payload = initialMessages.map { msg -> [String: String] in
+                let role: String
+                switch msg.role {
+                case .model: role = "model"
+                case .system: role = "system"
+                default: role = "user"
+                }
+                return ["role": role, "content": msg.content]
+            }
+            if let data = try? JSONSerialization.data(withJSONObject: payload, options: []),
+               let jsonString = String(data: data, encoding: .utf8) {
+                jsonString.withCString { messagesC in
+                    litert_lm_conversation_config_set_messages(convConfig, messagesC)
+                }
+            }
+        }
+
         self.conversation = litert_lm_conversation_create(engine, convConfig)
     }
     

package/lib/__mocks__/react-native-nitro-modules.d.ts

@@ -14,6 +14,7 @@ export declare const mockLiteRTLM: {
     sendMessageWithAudioAsync: jest.Mock<Promise<void>, [msg: string, audioPath: string, onToken: (token: string, done: boolean) => void], any>;
     getHistory: jest.Mock<never[], [], any>;
     resetConversation: jest.Mock<any, any, any>;
+    resetConversationWith: jest.Mock<any, any, any>;
     getStats: jest.Mock<{
         promptTokens: number;
         completionTokens: number;
@@ -54,6 +55,7 @@ export declare const NitroModules: {
         sendMessageWithAudioAsync: jest.Mock<Promise<void>, [msg: string, audioPath: string, onToken: (token: string, done: boolean) => void], any>;
         getHistory: jest.Mock<never[], [], any>;
         resetConversation: jest.Mock<any, any, any>;
+        resetConversationWith: jest.Mock<any, any, any>;
         getStats: jest.Mock<{
             promptTokens: number;
             completionTokens: number;

package/lib/__mocks__/react-native-nitro-modules.js

@@ -56,6 +56,7 @@ exports.mockLiteRTLM = {
     sendMessageWithAudioAsync: jest.fn((msg, audioPath, onToken) => mockExecute([{ type: "text", text: msg }, { type: "audio", path: audioPath }], onToken).then(() => { })),
     getHistory: jest.fn(() => []),
     resetConversation: jest.fn(),
+    resetConversationWith: jest.fn(),
     getStats: jest.fn(() => ({
         promptTokens: 10,
         completionTokens: 20,

package/lib/__tests__/modelFactory.test.js

@@ -33,6 +33,25 @@ describe('modelFactory Security & Proxy Unit Tests', () => {
         expect(react_native_nitro_modules_1.mockLiteRTLM.resetConversation).toHaveBeenCalled();
         expect(react_native_nitro_modules_1.mockLiteRTLM.getMemoryUsage).toHaveBeenCalled();
     });
+    it('should successfully proxy resetConversationWith and record memory metrics', async () => {
+        const seed = [{ role: 'user', content: 'earlier turn' }];
+        await llm.resetConversationWith(seed);
+        expect(react_native_nitro_modules_1.mockLiteRTLM.resetConversationWith).toHaveBeenCalledWith(seed);
+        expect(react_native_nitro_modules_1.mockLiteRTLM.getMemoryUsage).toHaveBeenCalled();
+    });
+    it('should report resetConversationWith as absent on older native builds', () => {
+        // The app feature-detects this method, so the proxy must not hand back a
+        // wrapper the native side cannot service.
+        const original = react_native_nitro_modules_1.mockLiteRTLM.resetConversationWith;
+        // @ts-expect-error deliberately removing the method to simulate old native
+        delete react_native_nitro_modules_1.mockLiteRTLM.resetConversationWith;
+        try {
+            expect((0, modelFactory_1.createLLM)().resetConversationWith).toBeUndefined();
+        }
+        finally {
+            react_native_nitro_modules_1.mockLiteRTLM.resetConversationWith = original;
+        }
+    });
     it('should successfully proxy sendMessageAsync and record memory metrics when done', async () => {
         const onToken = jest.fn();
         await llm.sendMessageAsync("Async prompt", onToken);

package/lib/modelFactory.js

@@ -95,6 +95,19 @@ function createLLM(options) {
                     return result;
                 };
             }
+            if (prop === "resetConversationWith") {
+                // Absent on native builds older than this JS wrapper, and callers
+                // feature-detect it — so fall through rather than handing back a
+                // wrapper that would fail at the bridge.
+                if (typeof target.resetConversationWith !== "function") {
+                    return undefined;
+                }
+                return (messages) => {
+                    const result = target.resetConversationWith(messages);
+                    recordMemorySnapshot();
+                    return result;
+                };
+            }
             if (prop === "sendToolResponse") {
                 return (responses, onToken) => {
                     if (onToken) {

package/lib/specs/LiteRTLM.nitro.d.ts

@@ -313,6 +313,23 @@ export interface LiteRTLM extends HybridObject<{
      * Clear the conversation context and start fresh.
      */
     resetConversation(): void;
+    /**
+     * Clear the conversation and re-seed it with prior turns.
+     *
+     * The engine allocates one KV cache per conversation, sized by
+     * `maxContextTokens`. Long tool-calling sessions fill it, and overflowing it
+     * aborts the process rather than raising a catchable error. Recreating the
+     * conversation frees the cache, but `resetConversation()` alone also throws
+     * away the thread.
+     *
+     * This seeds the fresh conversation with `messages` as prior context, so a
+     * caller can drop the oldest turns and keep the recent ones. The system
+     * prompt and tools configured at `loadModel` are reapplied automatically.
+     * No generation is triggered and no reply is produced.
+     *
+     * @param messages Prior turns, oldest first.
+     */
+    resetConversationWith(messages: Message[]): void;
     /**
      * Check if a model is loaded and ready for inference.
      */

package/nitrogen/generated/android/c++/JHybridLiteRTLMSpec.cpp

@@ -288,6 +288,19 @@ namespace margelo::nitro::litertlm {
     static const auto method = _javaPart->javaClassStatic()->getMethod<void()>("resetConversation");
     method(_javaPart);
   }
+  void JHybridLiteRTLMSpec::resetConversationWith(const std::vector<Message>& messages) {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<void(jni::alias_ref<jni::JArrayClass<JMessage>> /* messages */)>("resetConversationWith");
+    method(_javaPart, [&](auto&& __input) {
+      size_t __size = __input.size();
+      jni::local_ref<jni::JArrayClass<JMessage>> __array = jni::JArrayClass<JMessage>::newArray(__size);
+      for (size_t __i = 0; __i < __size; __i++) {
+        const auto& __element = __input[__i];
+        auto __elementJni = JMessage::fromCpp(__element);
+        __array->setElement(__i, *__elementJni);
+      }
+      return __array;
+    }(messages));
+  }
   bool JHybridLiteRTLMSpec::isReady() {
     static const auto method = _javaPart->javaClassStatic()->getMethod<jboolean()>("isReady");
     auto __result = method(_javaPart);

package/nitrogen/generated/android/c++/JHybridLiteRTLMSpec.hpp

@@ -66,6 +66,7 @@ namespace margelo::nitro::litertlm {
     std::shared_ptr<Promise<void>> sendMessageAsync(const std::string& message, const std::function<void(const std::string& /* token */, bool /* done */)>& onToken) override;
     std::vector<Message> getHistory() override;
     void resetConversation() override;
+    void resetConversationWith(const std::vector<Message>& messages) override;
     bool isReady() override;
     GenerationStats getStats() override;
     double countTokens(const std::string& text) override;

package/nitrogen/generated/android/kotlin/com/margelo/nitro/dev/litert/litertlm/Func_void_double.kt

@@ -10,7 +10,6 @@ package com.margelo.nitro.dev.litert.litertlm
 import androidx.annotation.Keep
 import com.facebook.jni.HybridData
 import com.facebook.proguard.annotations.DoNotStrip
-import dalvik.annotation.optimization.FastNative
 
 
 /**
@@ -59,7 +58,6 @@ class Func_void_double_cxx: Func_void_double {
   override fun invoke(progress: Double): Unit
     = invoke_cxx(progress)
 
-  @FastNative
   private external fun invoke_cxx(progress: Double): Unit
 }
 

package/nitrogen/generated/android/kotlin/com/margelo/nitro/dev/litert/litertlm/Func_void_std__string_bool.kt

@@ -10,7 +10,6 @@ package com.margelo.nitro.dev.litert.litertlm
 import androidx.annotation.Keep
 import com.facebook.jni.HybridData
 import com.facebook.proguard.annotations.DoNotStrip
-import dalvik.annotation.optimization.FastNative
 
 
 /**
@@ -59,7 +58,6 @@ class Func_void_std__string_bool_cxx: Func_void_std__string_bool {
   override fun invoke(token: String, done: Boolean): Unit
     = invoke_cxx(token,done)
 
-  @FastNative
   private external fun invoke_cxx(token: String, done: Boolean): Unit
 }
 

package/nitrogen/generated/android/kotlin/com/margelo/nitro/dev/litert/litertlm/HybridLiteRTLMSpec.kt

@@ -10,6 +10,7 @@ package com.margelo.nitro.dev.litert.litertlm
 import androidx.annotation.Keep
 import com.facebook.jni.HybridData
 import com.facebook.proguard.annotations.DoNotStrip
+import dalvik.annotation.optimization.FastNative
 import com.margelo.nitro.core.Promise
 import com.margelo.nitro.core.HybridObject
 
@@ -97,6 +98,10 @@ abstract class HybridLiteRTLMSpec: HybridObject() {
   @Keep
   abstract fun resetConversation(): Unit
   
+  @DoNotStrip
+  @Keep
+  abstract fun resetConversationWith(messages: Array<Message>): Unit
+  
   @DoNotStrip
   @Keep
   abstract fun isReady(): Boolean
@@ -157,6 +162,7 @@ abstract class HybridLiteRTLMSpec: HybridObject() {
   @Keep
   protected open class CxxPart(javaPart: HybridLiteRTLMSpec): HybridObject.CxxPart(javaPart) {
     // C++ JHybridLiteRTLMSpec::CxxPart::initHybrid(...)
+    @FastNative
     external override fun initHybrid(): HybridData
   }
   override fun createCxxPart(): CxxPart {

package/nitrogen/generated/android/kotlin/com/margelo/nitro/dev/litert/litertlm/HybridModelStoreSpec.kt

@@ -10,6 +10,7 @@ package com.margelo.nitro.dev.litert.litertlm
 import androidx.annotation.Keep
 import com.facebook.jni.HybridData
 import com.facebook.proguard.annotations.DoNotStrip
+import dalvik.annotation.optimization.FastNative
 import com.margelo.nitro.core.Promise
 import com.margelo.nitro.core.HybridObject
 
@@ -64,6 +65,7 @@ abstract class HybridModelStoreSpec: HybridObject() {
   @Keep
   protected open class CxxPart(javaPart: HybridModelStoreSpec): HybridObject.CxxPart(javaPart) {
     // C++ JHybridModelStoreSpec::CxxPart::initHybrid(...)
+    @FastNative
     external override fun initHybrid(): HybridData
   }
   override fun createCxxPart(): CxxPart {

package/nitrogen/generated/ios/c++/HybridLiteRTLMSpecSwift.hpp

@@ -206,6 +206,12 @@ namespace margelo::nitro::litertlm {
         std::rethrow_exception(__result.error());
       }
     }
+    inline void resetConversationWith(const std::vector<Message>& messages) override {
+      auto __result = _swiftPart.resetConversationWith(messages);
+      if (__result.hasError()) [[unlikely]] {
+        std::rethrow_exception(__result.error());
+      }
+    }
     inline bool isReady() override {
       auto __result = _swiftPart.isReady();
       if (__result.hasError()) [[unlikely]] {

package/nitrogen/generated/ios/swift/HybridLiteRTLMSpec.swift

@@ -25,6 +25,7 @@ public protocol HybridLiteRTLMSpec_protocol: HybridObject {
   func sendMessageAsync(message: String, onToken: @escaping (_ token: String, _ done: Bool) -> Void) throws -> Promise<Void>
   func getHistory() throws -> [Message]
   func resetConversation() throws -> Void
+  func resetConversationWith(messages: [Message]) throws -> Void
   func isReady() throws -> Bool
   func getStats() throws -> GenerationStats
   func countTokens(text: String) throws -> Double

package/nitrogen/generated/ios/swift/HybridLiteRTLMSpec_cxx.swift

@@ -370,6 +370,17 @@ open class HybridLiteRTLMSpec_cxx {
     }
   }
   
+  @inline(__always)
+  public final func resetConversationWith(messages: bridge.std__vector_Message_) -> bridge.Result_void_ {
+    do {
+      try self.__implementation.resetConversationWith(messages: messages.map({ __item in __item }))
+      return bridge.create_Result_void_()
+    } catch (let __error) {
+      let __exceptionPtr = __error.toCpp()
+      return bridge.create_Result_void_(__exceptionPtr)
+    }
+  }
+  
   @inline(__always)
   public final func isReady() -> bridge.Result_bool_ {
     do {

package/nitrogen/generated/shared/c++/HybridLiteRTLMSpec.cpp

@@ -26,6 +26,7 @@ namespace margelo::nitro::litertlm {
       prototype.registerHybridMethod("sendMessageAsync", &HybridLiteRTLMSpec::sendMessageAsync);
       prototype.registerHybridMethod("getHistory", &HybridLiteRTLMSpec::getHistory);
       prototype.registerHybridMethod("resetConversation", &HybridLiteRTLMSpec::resetConversation);
+      prototype.registerHybridMethod("resetConversationWith", &HybridLiteRTLMSpec::resetConversationWith);
       prototype.registerHybridMethod("isReady", &HybridLiteRTLMSpec::isReady);
       prototype.registerHybridMethod("getStats", &HybridLiteRTLMSpec::getStats);
       prototype.registerHybridMethod("countTokens", &HybridLiteRTLMSpec::countTokens);

package/nitrogen/generated/shared/c++/HybridLiteRTLMSpec.hpp

@@ -90,6 +90,7 @@ namespace margelo::nitro::litertlm {
       virtual std::shared_ptr<Promise<void>> sendMessageAsync(const std::string& message, const std::function<void(const std::string& /* token */, bool /* done */)>& onToken) = 0;
       virtual std::vector<Message> getHistory() = 0;
       virtual void resetConversation() = 0;
+      virtual void resetConversationWith(const std::vector<Message>& messages) = 0;
       virtual bool isReady() = 0;
       virtual GenerationStats getStats() = 0;
       virtual double countTokens(const std::string& text) = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dr33m/react-native-litert-lm",
-  "version": "0.5.5",
+  "version": "0.6.0",
   "litertLm": {
     "version": "0.12.0",
     "androidMavenVersion": "0.12.0",

package/src/__mocks__/react-native-nitro-modules.ts

@@ -81,6 +81,7 @@ export const mockLiteRTLM = {
   ),
   getHistory: jest.fn(() => []),
   resetConversation: jest.fn(),
+  resetConversationWith: jest.fn(),
   getStats: jest.fn(() => ({
     promptTokens: 10,
     completionTokens: 20,

package/src/__tests__/modelFactory.test.ts

@@ -49,6 +49,27 @@ describe('modelFactory Security & Proxy Unit Tests', () => {
     expect(mockLiteRTLM.getMemoryUsage).toHaveBeenCalled();
   });
 
+  it('should successfully proxy resetConversationWith and record memory metrics', async () => {
+    const seed = [{ role: 'user', content: 'earlier turn' }];
+    await llm.resetConversationWith(seed as never);
+
+    expect(mockLiteRTLM.resetConversationWith).toHaveBeenCalledWith(seed);
+    expect(mockLiteRTLM.getMemoryUsage).toHaveBeenCalled();
+  });
+
+  it('should report resetConversationWith as absent on older native builds', () => {
+    // The app feature-detects this method, so the proxy must not hand back a
+    // wrapper the native side cannot service.
+    const original = mockLiteRTLM.resetConversationWith;
+    // @ts-expect-error deliberately removing the method to simulate old native
+    delete mockLiteRTLM.resetConversationWith;
+    try {
+      expect(createLLM().resetConversationWith).toBeUndefined();
+    } finally {
+      mockLiteRTLM.resetConversationWith = original;
+    }
+  });
+
   it('should successfully proxy sendMessageAsync and record memory metrics when done', async () => {
     const onToken = jest.fn();
     await llm.sendMessageAsync("Async prompt", onToken);

package/src/modelFactory.ts

@@ -130,6 +130,20 @@ export function createLLM(options?: {
         };
       }
 
+      if (prop === "resetConversationWith") {
+        // Absent on native builds older than this JS wrapper, and callers
+        // feature-detect it — so fall through rather than handing back a
+        // wrapper that would fail at the bridge.
+        if (typeof (target as any).resetConversationWith !== "function") {
+          return undefined;
+        }
+        return (messages: unknown[]) => {
+          const result = (target as any).resetConversationWith(messages);
+          recordMemorySnapshot();
+          return result;
+        };
+      }
+
       if (prop === "sendToolResponse") {
         return (responses: any[], onToken?: TokenCallback) => {
           if (onToken) {

package/src/specs/LiteRTLM.nitro.ts

@@ -364,6 +364,24 @@ export interface LiteRTLM extends HybridObject<{
    */
   resetConversation(): void;
 
+  /**
+   * Clear the conversation and re-seed it with prior turns.
+   *
+   * The engine allocates one KV cache per conversation, sized by
+   * `maxContextTokens`. Long tool-calling sessions fill it, and overflowing it
+   * aborts the process rather than raising a catchable error. Recreating the
+   * conversation frees the cache, but `resetConversation()` alone also throws
+   * away the thread.
+   *
+   * This seeds the fresh conversation with `messages` as prior context, so a
+   * caller can drop the oldest turns and keep the recent ones. The system
+   * prompt and tools configured at `loadModel` are reapplied automatically.
+   * No generation is triggered and no reply is produced.
+   *
+   * @param messages Prior turns, oldest first.
+   */
+  resetConversationWith(messages: Message[]): void;
+
   /**
    * Check if a model is loaded and ready for inference.
    */