Aligning / upstream update for dev (#442)

* chore: add AGENTS.md with Cursor Cloud specific instructions

* chore: update AGENTS.md with Linux backend build and voice assistant instructions

* minor fixes

* fix: Android app UI improvements, SDK concurrency bug fixes, and LoRA download support

Android App:
- Redesign intro screen with minimal layout and linear progress bar
- Improve VLM screen: use shared ModelRequiredOverlay, theme-consistent colors,
  fix button clipping (replace IconButton with clickable Column)
- Fix keyboard handling: hide bottom bar when keyboard open, apply imePadding correctly
- Add scrollable auto-scroll prompt suggestions in ChatScreen
- Add shimmer typing indicator with "Thinking..." label
- Fix 9 app-level bugs: think tag leak, CancellationException handling,
  VoiceAssistant lifecycle, ConversationStore ANR, TTS sample rate parsing,
  LoRA download mutex deadlock

KMP SDK (10 bug fixes):
- Fix cancel() deadlock: move JNI calls outside synchronized(lock) in CppBridgeLLM
- Fix orphaned CoroutineScope leak in generateStream using callbackFlow
- Fix initializeServices() holding lock across network I/O
- Fix loraDownloadDir lazy val caching wrong path before pathProvider set
- Fix setBaseDirCallback TOCTOU race condition
- Add @volatile to DownloadTask mutable fields for thread visibility
- Fix unescapeJson() replacement order (process \\\\ before \\n)
- Add downloadLock for atomic cancel/pause/resume operations
- Fix checkNativeLibrary() to actually call native method
- Add ensureServicesReady() to generateStream
- Add LoRA adapter download/delete/path SDK functions

Known issue: Tool-calling may show unexpected behavior when a LoRA adapter is
applied — the model detects the tool call but responds with "I can assist with
this" instead of executing it. Tested with Qwen 2.5 0.5B. This only occurs
when the model has a LoRA adapter loaded.

* fix(tts): scan WAV data chunk instead of hardcoding 44-byte header offset

WAV files with extra chunks (LIST, fact, bext) had metadata bytes fed
into AudioTrack as PCM, causing distorted playback. Now walks the chunk
structure to find the actual "data" chunk start.

* fix: Android app UI bug fixes, responsive dimensions, LoRA example prompts, and darker dark mode

- Fix nested verticalScroll inside LazyColumn (ThinkingToggle) causing broken scroll
- Fix weight(1f) + verticalScroll overflow in VLMScreen DescriptionPanel
- Add verticalScroll to MoreHubScreen to prevent clipping on small screens
- Add imePadding to ConversationListSheet so keyboard doesn't cover search
- Fix auto-scroll wrap logic in EmptyStateView using canScrollForward
- Replace collectAsState with collectAsStateWithLifecycle in 3 screens
- Replace deprecated STTMode.values() with .entries
- Replace hardcoded Color.Gray with AppColors.statusGray for dark mode contrast
- Remove redundant Color.White inside buttons with contentColor set
- Replace hardcoded 300.dp bubble width with responsive Dimensions.messageBubbleMaxWidth
- Add accessibility semantics role to VLMScreen clickable Column
- Disable Image Generation card (placeholder feature)
- Add responsive rDp/rSp utilities and convert Dimensions/AppSpacing to use them
- Add LoRA example prompts with copy button to adapter picker and manager screens
- Darken dark mode background colors

* fix: Android app bug fixes - race conditions, ANR, pixel corruption, scroll, and memory safety

- VoiceAssistantViewModel: replace runBlocking with GlobalScope.launch in onCleared to prevent ANR
- VoiceAssistantViewModel: add synchronized audioBufferLock for thread-safe ByteArrayOutputStream access
- VoiceAssistantViewModel: scan WAV data chunk instead of hardcoding 44-byte header offset
- ConversationStore: use MutableStateFlow.update {} for atomic compare-and-set on all mutations
- ToolSettingsViewModel: clear static singleton in onCleared to prevent stale references
- VLMViewModel: advance rgbIdx by 3 in else branch to prevent pixel corruption on out-of-bounds skip
- ChatViewModel: use CopyOnWriteArrayList for tokensPerSecondHistory thread safety
- VoiceAssistantParticleView: remove wasted transparent drawPoints call
- RunAnywhereApplication: capture volatile initializationError to local val before null check
- VLMScreen: add verticalScroll to description panel for long text overflow
- ResponsiveUtils: add designWidth <= 0 guard to prevent division by zero in rDp/rSp

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Sanchit Monga <sanchitmonga22@gmail.com>
Co-authored-by: Sanchit Monga <sm3468@g.rit.edu>
Co-authored-by: Siddhesh2377 <siddheshsonar2377@gmail.com>
Co-authored-by: RunAnywhere <>

Author: 4 people

AGENTS.md

@@ -0,0 +1,53 @@
+# AGENTS.md
+
+## Cursor Cloud specific instructions
+
+### Environment Overview
+
+This is a cross-platform SDK monorepo. On a Linux cloud VM, the buildable services are:
+
+| Component | Build | Test | Lint | Notes |
+|-----------|-------|------|------|-------|
+| Kotlin SDK (Android target) | `./gradlew :runanywhere-kotlin:compileDebugKotlinAndroid -Prunanywhere.testLocal=false` | Android unit tests require device/emulator | `./gradlew :runanywhere-kotlin:runKtlintCheckOverCommonMainSourceSet` | JVM target has a known issue: `RAGBridge.kt` in `jvmAndroidMain` imports `@Keep` from `androidx.annotation` which is unavailable for JVM compilation |
+| Web SDK (TypeScript) | `npm run build -w packages/core` (from `sdk/runanywhere-web/`) | N/A | `npm run typecheck -w packages/core` | `llamacpp` package has a pre-existing duplicate index signature TS error |
+| Web Example App | `npm run dev` (from `examples/web/RunAnywhereAI/`) | Manual browser testing at `localhost:5173` | N/A | Full Vite app, works in demo mode without WASM |
+| C++ Commons (core) | `cmake -B build ... && cmake --build build` (from `sdk/runanywhere-commons/`) | `./build/tests/test_core --run-all` (13 tests, no models needed) | N/A | Must use `gcc`/`g++` via `CC=gcc CXX=g++` (clang lacks C++ stdlib headers). Pass `-DRAC_BUILD_PLATFORM=OFF` on Linux |
+| C++ Commons (full backends) | `CC=gcc CXX=g++ bash scripts/build-linux.sh --shared` | Backend tests need downloaded models | N/A | Builds onnx+llamacpp. RAG backend has pre-existing zero-size array bug; use `-DRAC_BACKEND_RAG=OFF`. Sherpa-ONNX v1.12.23 URL changed: use `sherpa-onnx-v{VER}-linux-x64-shared.tar.bz2` (no `-cpu` suffix) |
+| Linux Voice Assistant | `cmake -B build && cmake --build build` (from `Playground/linux-voice-assistant/`) | `./build/test-pipeline <audio.wav>` runs full VAD→STT→LLM→TTS pipeline | N/A | Requires: ALSA headers (`libasound2-dev`), built commons with backends, downloaded models (`./scripts/download-models.sh`). Audio capture needs real hardware; `test-pipeline` works headless |
+| iOS/Swift SDK | Not buildable | Not buildable | Not available | Requires macOS + Xcode |
+| Android emulator | Not runnable | Not runnable | N/A | No KVM support in cloud VM |
+
+### Key Gotchas
+
+- **Android SDK**: Installed at `/opt/android-sdk`. `ANDROID_HOME` and `JAVA_HOME` are set in `~/.bashrc`.
+- **JDK 17**: Required by Gradle JVM toolchain. Both JDK 17 and JDK 21 are installed.
+- **`testLocal` flag**: Set to `true` in `gradle.properties`. Pass `-Prunanywhere.testLocal=false` to Gradle to avoid needing Android NDK (downloads pre-built JNI libs from GitHub releases instead of building locally).
+- **C++ compiler**: Default clang on this VM lacks `libc++` headers. Use `gcc`/`g++` via `-DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++`.
+- **`local.properties`**: Auto-created at root, `sdk/runanywhere-kotlin/`, and `examples/android/RunAnywhereAI/` with `sdk.dir=/opt/android-sdk`.
+- **pre-commit hooks**: Installed via `pre-commit install`. Requires `git config --unset-all core.hooksPath` first if `core.hooksPath` is set.
+
+### Linux Voice Assistant Quick Start
+
+```bash
+# 1. Build commons with backends
+cd sdk/runanywhere-commons
+CC=gcc CXX=g++ cmake -B build-linux-x86_64 -DCMAKE_BUILD_TYPE=Release \
+  -DRAC_BUILD_BACKENDS=ON -DRAC_BACKEND_ONNX=ON -DRAC_BACKEND_LLAMACPP=ON \
+  -DRAC_BACKEND_RAG=OFF -DRAC_BUILD_SHARED=ON -DRAC_BUILD_PLATFORM=OFF
+cmake --build build-linux-x86_64 -j$(nproc)
+
+# 2. Copy libs to dist
+# (see build-linux.sh for full dist copy steps)
+
+# 3. Build voice assistant
+cd Playground/linux-voice-assistant
+CC=gcc CXX=g++ cmake -B build && cmake --build build
+
+# 4. Run test pipeline (headless, no mic needed)
+export LD_LIBRARY_PATH="../../sdk/runanywhere-commons/dist/linux/x86_64:../../sdk/runanywhere-commons/third_party/sherpa-onnx-linux/lib"
+./build/test-pipeline /path/to/audio.wav
+```
+
+### Standard commands
+
+See `CLAUDE.md` for comprehensive build/test/lint commands for all SDK platforms. See `CONTRIBUTING.md` for contributor setup flow.

examples/android/RunAnywhereAI/app/src/main/AndroidManifest.xml

@@ -40,7 +40,7 @@
         <activity
             android:name=".MainActivity"
             android:exported="true"
-            android:windowSoftInputMode="adjustResize"
+            android:windowSoftInputMode="adjustNothing"
             android:theme="@style/Theme.RunAnywhereAI">
             <intent-filter>
                 <action android:name="android.intent.action.MAIN" />

examples/android/RunAnywhereAI/app/src/main/java/com/runanywhere/runanywhereai/RunAnywhereApplication.kt

@@ -208,11 +208,12 @@ class RunAnywhereApplication : Application() {
         isSDKInitialized = RunAnywhere.isInitialized
 
         // Update observable state for Compose UI
+        val error = initializationError
         if (isSDKInitialized) {
             _initializationState.value = SDKInitializationState.Ready
             Timber.i("🎉 App is ready to use!")
-        } else if (initializationError != null) {
-            _initializationState.value = SDKInitializationState.Error(initializationError!!)
+        } else if (error != null) {
+            _initializationState.value = SDKInitializationState.Error(error)
         } else {
             // SDK reported not initialized but no error - treat as ready for offline mode
             _initializationState.value = SDKInitializationState.Ready

examples/android/RunAnywhereAI/app/src/main/java/com/runanywhere/runanywhereai/data/ConversationStore.kt

@@ -6,9 +6,14 @@ import timber.log.Timber
 import com.runanywhere.runanywhereai.domain.models.ChatMessage
 import com.runanywhere.runanywhereai.domain.models.Conversation
 import com.runanywhere.runanywhereai.domain.models.MessageRole
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.flow.update
+import kotlinx.coroutines.launch
 import kotlinx.serialization.decodeFromString
 import kotlinx.serialization.encodeToString
 import kotlinx.serialization.json.Json
@@ -42,6 +47,7 @@ class ConversationStore private constructor(context: Context) {
     val currentConversation: StateFlow<Conversation?> = _currentConversation.asStateFlow()
 
     private val conversationsDirectory: File
+    private val ioScope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
     private val json =
         Json {
             prettyPrint = true
@@ -53,7 +59,7 @@ class ConversationStore private constructor(context: Context) {
         if (!conversationsDirectory.exists()) {
             conversationsDirectory.mkdirs()
         }
-        loadConversations()
+        ioScope.launch { loadConversations() }
     }
 
     // MARK: - Public Methods
@@ -74,9 +80,7 @@ class ConversationStore private constructor(context: Context) {
                 performanceSummary = null,
             )
 
-        val updated = _conversations.value.toMutableList()
-        updated.add(0, conversation)
-        _conversations.value = updated
+        _conversations.update { list -> listOf(conversation) + list }
         _currentConversation.value = conversation
 
         saveConversation(conversation)
@@ -88,31 +92,36 @@ class ConversationStore private constructor(context: Context) {
      * If not present (by id), adds it at the front so it appears in history.
      */
     fun ensureConversationInList(conversation: Conversation) {
-        val index = _conversations.value.indexOfFirst { it.id == conversation.id }
-        if (index == -1) {
-            val list = _conversations.value.toMutableList()
-            list.add(0, conversation)
-            _conversations.value = list
-            saveConversation(conversation)
+        var wasAdded = false
+        _conversations.update { list ->
+            if (list.any { it.id == conversation.id }) {
+                list
+            } else {
+                wasAdded = true
+                listOf(conversation) + list
+            }
         }
+        if (wasAdded) saveConversation(conversation)
     }
 
     /**
      * Update an existing conversation
      */
     fun updateConversation(conversation: Conversation) {
         val updated = conversation.copy(updatedAt = System.currentTimeMillis())
-
-        val index = _conversations.value.indexOfFirst { it.id == conversation.id }
-        if (index != -1) {
-            val list = _conversations.value.toMutableList()
-            list[index] = updated
-            _conversations.value = list
-
+        var found = false
+        _conversations.update { list ->
+            list.map {
+                if (it.id == conversation.id) {
+                    found = true
+                    updated
+                } else it
+            }
+        }
+        if (found) {
             if (_currentConversation.value?.id == conversation.id) {
                 _currentConversation.value = updated
             }
-
             saveConversation(updated)
         }
     }
@@ -121,16 +130,18 @@ class ConversationStore private constructor(context: Context) {
      * Delete a conversation
      */
     fun deleteConversation(conversation: Conversation) {
-        _conversations.value = _conversations.value.filter { it.id != conversation.id }
+        _conversations.update { list -> list.filter { it.id != conversation.id } }
 
         if (_currentConversation.value?.id == conversation.id) {
             _currentConversation.value = _conversations.value.firstOrNull()
         }
 
-        // Delete file
-        val file = conversationFileURL(conversation.id)
-        if (file.exists()) {
-            file.delete()
+        // Delete file off main thread
+        ioScope.launch {
+            val file = conversationFileURL(conversation.id)
+            if (file.exists()) {
+                file.delete()
+            }
         }
     }
 
@@ -176,9 +187,7 @@ class ConversationStore private constructor(context: Context) {
             try {
                 val jsonString = file.readText()
                 val loaded = json.decodeFromString<Conversation>(jsonString)
-                val list = _conversations.value.toMutableList()
-                list.add(loaded)
-                _conversations.value = list
+                _conversations.update { list -> list + loaded }
                 _currentConversation.value = loaded
                 return loaded
             } catch (e: Exception) {
@@ -246,12 +255,14 @@ class ConversationStore private constructor(context: Context) {
      * Save a conversation to disk
      */
     private fun saveConversation(conversation: Conversation) {
-        try {
-            val file = conversationFileURL(conversation.id)
-            val jsonString = json.encodeToString(conversation)
-            file.writeText(jsonString)
-        } catch (e: Exception) {
-            Timber.e(e, "Failed to save conversation")
+        ioScope.launch {
+            try {
+                val file = conversationFileURL(conversation.id)
+                val jsonString = json.encodeToString(conversation)
+                file.writeText(jsonString)
+            } catch (e: Exception) {
+                Timber.e(e, "Failed to save conversation")
+            }
         }
     }
 

examples/android/RunAnywhereAI/app/src/main/java/com/runanywhere/runanywhereai/data/LoraExamplePrompts.kt

@@ -0,0 +1,36 @@
+package com.runanywhere.runanywhereai.data
+
+/**
+ * Example prompts for each LoRA adapter, keyed by adapter filename.
+ * These are shown in the active LoRA card so users can quickly test the adapter.
+ */
+object LoraExamplePrompts {
+
+    private val promptsByFilename: Map<String, List<String>> = mapOf(
+        "code-assistant-Q8_0.gguf" to listOf(
+            "Write a Python function to reverse a linked list",
+            "Explain the difference between a stack and a queue with code examples",
+        ),
+        "reasoning-logic-Q8_0.gguf" to listOf(
+            "If all roses are flowers and some flowers fade quickly, can we conclude some roses fade quickly?",
+            "A farmer has 17 sheep. All but 9 die. How many are left?",
+        ),
+        "medical-qa-Q8_0.gguf" to listOf(
+            "What are the common symptoms of vitamin D deficiency?",
+            "Explain the difference between Type 1 and Type 2 diabetes",
+        ),
+        "creative-writing-Q8_0.gguf" to listOf(
+            "Write a short story about a robot discovering emotions for the first time",
+            "Describe a sunset over the ocean using vivid sensory language",
+        ),
+    )
+
+    /**
+     * Get example prompts for a loaded adapter by its file path.
+     * Extracts the filename from the path and looks up prompts.
+     */
+    fun forAdapterPath(path: String): List<String> {
+        val filename = path.substringAfterLast("/")
+        return promptsByFilename[filename] ?: emptyList()
+    }
+}

examples/android/RunAnywhereAI/app/src/main/java/com/runanywhere/runanywhereai/data/ModelList.kt

@@ -32,15 +32,15 @@ object ModelList {
         AppModel(id = "qwen2.5-0.5b-instruct-q6_k", name = "Qwen 2.5 0.5B Instruct Q6_K",
             url = "https://huggingface.co/Triangle104/Qwen2.5-0.5B-Instruct-Q6_K-GGUF/resolve/main/qwen2.5-0.5b-instruct-q6_k.gguf",
             framework = InferenceFramework.LLAMA_CPP, category = ModelCategory.LANGUAGE,
-            memoryRequirement = 600_000_000),
+            memoryRequirement = 600_000_000, supportsLoraAdapters = true),
         AppModel(id = "lfm2-350m-q4_k_m", name = "LiquidAI LFM2 350M Q4_K_M",
             url = "https://huggingface.co/LiquidAI/LFM2-350M-GGUF/resolve/main/LFM2-350M-Q4_K_M.gguf",
             framework = InferenceFramework.LLAMA_CPP, category = ModelCategory.LANGUAGE,
-            memoryRequirement = 250_000_000, supportsLoraAdapters = true),
+            memoryRequirement = 250_000_000),
         AppModel(id = "lfm2-350m-q8_0", name = "LiquidAI LFM2 350M Q8_0",
             url = "https://huggingface.co/LiquidAI/LFM2-350M-GGUF/resolve/main/LFM2-350M-Q8_0.gguf",
             framework = InferenceFramework.LLAMA_CPP, category = ModelCategory.LANGUAGE,
-            memoryRequirement = 400_000_000, supportsLoraAdapters = true),
+            memoryRequirement = 400_000_000),
         AppModel(id = "lfm2-1.2b-tool-q4_k_m", name = "LiquidAI LFM2 1.2B Tool Q4_K_M",
             url = "https://huggingface.co/LiquidAI/LFM2-1.2B-Tool-GGUF/resolve/main/LFM2-1.2B-Tool-Q4_K_M.gguf",
             framework = InferenceFramework.LLAMA_CPP, category = ModelCategory.LANGUAGE,
@@ -81,46 +81,46 @@ object ModelList {
             )),
     )
 
-    // LoRA Adapters (from Void2377/Qwen on HuggingFace — real standalone LoRA GGUF files)
+    // LoRA Adapters
     private val loraAdapters = listOf(
         LoraAdapterCatalogEntry(
-            id = "chat-assistant-lora",
-            name = "Chat Assistant",
-            description = "Enhances conversational chat ability",
-            downloadUrl = "https://huggingface.co/Void2377/Qwen/resolve/main/lora/chat_assistant-lora-Q8_0.gguf",
-            filename = "chat_assistant-lora-Q8_0.gguf",
-            compatibleModelIds = listOf("lfm2-350m-q4_k_m", "lfm2-350m-q8_0"),
-            fileSize = 690_176,
+            id = "code-assistant-lora",
+            name = "Code Assistant",
+            description = "Enhances code generation and programming assistance",
+            downloadUrl = "https://huggingface.co/Void2377/Qwen/resolve/main/lora/code-assistant-Q8_0.gguf",
+            filename = "code-assistant-Q8_0.gguf",
+            compatibleModelIds = listOf("qwen2.5-0.5b-instruct-q6_k"),
+            fileSize = 765_952,
             defaultScale = 1.0f,
         ),
         LoraAdapterCatalogEntry(
-            id = "summarizer-lora",
-            name = "Summarizer",
-            description = "Specialized for text summarization tasks",
-            downloadUrl = "https://huggingface.co/Void2377/Qwen/resolve/main/lora/summarizer-lora-Q8_0.gguf",
-            filename = "summarizer-lora-Q8_0.gguf",
-            compatibleModelIds = listOf("lfm2-350m-q4_k_m", "lfm2-350m-q8_0"),
-            fileSize = 690_176,
+            id = "reasoning-logic-lora",
+            name = "Reasoning Logic",
+            description = "Improves logical reasoning and step-by-step problem solving",
+            downloadUrl = "https://huggingface.co/Void2377/Qwen/resolve/main/lora/reasoning-logic-Q8_0.gguf",
+            filename = "reasoning-logic-Q8_0.gguf",
+            compatibleModelIds = listOf("qwen2.5-0.5b-instruct-q6_k"),
+            fileSize = 765_952,
             defaultScale = 1.0f,
         ),
         LoraAdapterCatalogEntry(
-            id = "translator-lora",
-            name = "Translator",
-            description = "Improves translation between languages",
-            downloadUrl = "https://huggingface.co/Void2377/Qwen/resolve/main/lora/translator-lora-Q8_0.gguf",
-            filename = "translator-lora-Q8_0.gguf",
-            compatibleModelIds = listOf("lfm2-350m-q4_k_m", "lfm2-350m-q8_0"),
-            fileSize = 690_176,
+            id = "medical-qa-lora",
+            name = "Medical QA",
+            description = "Enhances medical question answering and health-related responses",
+            downloadUrl = "https://huggingface.co/Void2377/Qwen/resolve/main/lora/medical-qa-Q8_0.gguf",
+            filename = "medical-qa-Q8_0.gguf",
+            compatibleModelIds = listOf("qwen2.5-0.5b-instruct-q6_k"),
+            fileSize = 765_952,
             defaultScale = 1.0f,
         ),
         LoraAdapterCatalogEntry(
-            id = "sentiment-lora",
-            name = "Sentiment Analysis",
-            description = "Fine-tuned for sentiment analysis tasks",
-            downloadUrl = "https://huggingface.co/Void2377/Qwen/resolve/main/lora/sentiment-lora-Q8_0.gguf",
-            filename = "sentiment-lora-Q8_0.gguf",
-            compatibleModelIds = listOf("lfm2-350m-q4_k_m", "lfm2-350m-q8_0"),
-            fileSize = 690_176,
+            id = "creative-writing-lora",
+            name = "Creative Writing",
+            description = "Improves creative writing, storytelling, and literary style",
+            downloadUrl = "https://huggingface.co/Void2377/Qwen/resolve/main/lora/creative-writing-Q8_0.gguf",
+            filename = "creative-writing-Q8_0.gguf",
+            compatibleModelIds = listOf("qwen2.5-0.5b-instruct-q6_k"),
+            fileSize = 765_952,
             defaultScale = 1.0f,
         ),
     )