[Android SDK] [Kotlin SDK] Add LoRA Adapter Support

[Siddhesh2377]

Summary

• Adds LoRA (Low-Rank Adaptation) adapter support to the Kotlin SDK and Android example app
• Exposes RunAnywhere+LoRA and RunAnywhere+LoRADownload extensions for loading and downloading LoRA adapters
• Adds a LoraAdapterCatalog for managing available adapters
• Implements LoRA loading/unloading in the C++ LLaMA.cpp backend via JNI
• Updates the Android demo app with a dedicated Lora screen, prompt templates, and LoRA-aware chat UI

Changes

• Kotlin SDK (sdk/runanywhere-kotlin/): New LoRA extensions, adapter catalog, bridge updates
• C++ Commons (sdk/runanywhere-commons/): LoRA support in LLaMA.cpp backend, new JNI bindings
• Android Demo (examples/android/): New LoraScreen, LoraViewModel, updated ChatScreen and ChatViewModel with LoRA context
• Docs: Updated docs/impl/lora_adapter_support.md

Test plan

• Build Kotlin SDK and verify LoRA extensions compile
• Run Android demo app and navigate to Lora screen
• Load a LoRA adapter and verify it affects model output
• Test adapter download via RunAnywhere+LoRADownload
• Verify unloading a LoRA adapter restores default behavior

🤖 Generated with Claude Code

---

Important

Adds LoRA adapter support to Kotlin SDK and Android app, including loading, unloading, compatibility checking, and downloading from URLs or a catalog.

• Behavior:
  • Adds LoRA adapter support to Kotlin SDK and Android app, enabling loading, unloading, and compatibility checking.
  • Introduces RunAnywhere+LoRA and RunAnywhere+LoRADownload extensions for managing LoRA adapters.
  • Implements LoRA loading/unloading in C++ backend via JNI.
  • Updates Android app with LoRA screen, prompt templates, and chat UI.
• Kotlin SDK:
  • Adds LoraAdapterCatalog for managing adapters.
  • Adds LoraCompatibilityResult, LoraDownloadState, and LoraDownloadProgress data classes.
  • Implements loadLoraAdapter, removeLoraAdapter, clearLoraAdapters, getLoadedLoraAdapters, and checkLoraCompatibility functions.
  • Implements downloadLoraAdapter and downloadLoraFromCatalog functions.
• JNI and C++:
  • Adds racLlmComponentCheckLoraCompat and racLlmComponentLoadLora functions in runanywhere_commons_jni.cpp.
  • Updates llamacpp_backend.cpp with check_lora_compatibility and read_gguf_metadata methods.
  • Updates rac_llm_llamacpp.cpp with rac_llm_llamacpp_check_lora_compat and rac_llm_llamacpp_read_gguf_info functions.

^{This description was created by for 07700f2. You can customize this summary. It will automatically update as commits are pushed.}

Summary by CodeRabbit

• New Features

  • LoRA adapter compatibility checking without loading weights
  • LoRA adapter downloads with progress tracking and catalog support
  • LoRA scale adjustment UI for fine-tuning loaded adapters

• Documentation

  • Added comprehensive LoRA adapter support documentation with architecture diagrams and workflow descriptions

• Chores

  • Removed deprecated example application module
  • Updated IDE and Git configurations

Greptile Summary

Adds comprehensive LoRA (Low-Rank Adaptation) adapter support across the entire SDK stack, enabling runtime model fine-tuning without reloading base models.

Implementation spans 6 architectural layers:

• C++ backend integrates llama.cpp LoRA APIs with context recreation and KV cache management
• Component layer provides vtable-based dispatch for backend-agnostic LoRA operations
• JNI bridge exposes C functions to Kotlin with proper memory management
• Kotlin SDK implements public API with compatibility checking and HTTP download support
• Android demo apps showcase LoRA loading, stacking, and catalog-based downloads

Key features:

• Load/remove/clear LoRA adapters with individual scale factors
• Stack multiple adapters simultaneously
• Pre-load compatibility check via GGUF metadata parsing (prevents incompatible loads)
• Download adapters from URLs or built-in catalog with progress tracking
• Atomic downloads using temp files with rename
• Thread-safe operations with proper locking at all layers

Documentation:

• 1000+ line implementation guide in docs/impl/lora_adapter_support.md covering all layers with C/Swift usage examples

Confidence Score: 4/5

• Safe to merge with minor documentation clarifications needed
• Well-architected implementation following established SDK patterns with proper error handling, thread safety, and comprehensive documentation. Score reflects solid engineering with a few minor areas for improvement (catalog location, test coverage documentation).
• Pay attention to sdk/runanywhere-kotlin/src/commonMain/kotlin/com/runanywhere/sdk/temp/LoraAdapterCatalog.kt - marked as temporary but may need permanent home before release

Important Files Changed

Filename	Overview
sdk/runanywhere-commons/src/backends/llamacpp/llamacpp_backend.cpp	Adds LoRA adapter loading, compatibility checking via GGUF metadata parsing, and context recreation logic
sdk/runanywhere-commons/src/jni/runanywhere_commons_jni.cpp	Adds JNI bridge functions for LoRA operations with proper error handling
sdk/runanywhere-kotlin/src/jvmAndroidMain/kotlin/com/runanywhere/sdk/public/extensions/RunAnywhere+LoRADownload.jvmAndroid.kt	Implements HTTP download with progress tracking, temp files, and atomic rename
sdk/runanywhere-kotlin/src/commonMain/kotlin/com/runanywhere/sdk/temp/LoraAdapterCatalog.kt	Hardcoded catalog of 5 LoRA adapters for Qwen model
examples/android/RunAnyWhereLora/app/src/main/java/com/runanywhere/run_anywhere_lora/LoraViewModel.kt	Dedicated LoRA demo ViewModel with download, compatibility checking, and generation

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TB
    subgraph Public["Public API Layer (Kotlin)"]
        A[RunAnywhere.loadLoraAdapter]
        A1[RunAnywhere.downloadLoraAdapter]
        A2[RunAnywhere.checkLoraCompatibility]
    end
    
    subgraph Bridge["Kotlin Bridge Layer"]
        B[CppBridgeLLM.loadLoraAdapter]
        B1[CppBridgeLLM.checkLoraCompatibility]
    end
    
    subgraph JNI["JNI Layer"]
        C[racLlmComponentLoadLora]
        C1[racLlmComponentCheckLoraCompat]
    end
    
    subgraph Component["Component C API"]
        D[rac_llm_component_load_lora]
        D1[rac_llm_component_check_lora_compat]
    end
    
    subgraph Vtable["Vtable Dispatch"]
        E[ops->load_lora]
        E1[ops->check_lora_compat]
    end
    
    subgraph Backend["LlamaCPP Backend"]
        F[rac_llm_llamacpp_load_lora]
        F1[rac_llm_llamacpp_check_lora_compat]
    end
    
    subgraph CPP["C++ Implementation"]
        G[LlamaCppTextGeneration::load_lora_adapter]
        G1[Check GGUF metadata]
        G2[Load adapter via llama.cpp]
        G3[Recreate context]
        G4[Apply all adapters]
        G5[Clear KV cache]
    end
    
    A --> B
    A1 --> HTTP[HTTP Download with<br/>progress tracking]
    A2 --> B1
    
    B --> C
    B1 --> C1
    
    C --> D
    C1 --> D1
    
    D --> E
    D1 --> E1
    
    E --> F
    E1 --> F1
    
    F --> G
    F1 --> G1
    
    G --> G1
    G1 --> G2
    G2 --> G3
    G3 --> G4
    G4 --> G5
    
    HTTP --> A
    
    style A fill:#4CAF50
    style A1 fill:#4CAF50
    style A2 fill:#4CAF50
    style G5 fill:#FF9800

Loading

_{Last reviewed commit: 07700f2}

[coderabbitai]

Important

Review skipped

Too many files!

This PR contains 261 files, which is 111 over the limit of 150.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This pull request adds comprehensive LoRA (Low-Rank Adapter) support across the entire stack—C++ backend, C APIs, JNI bindings, Kotlin SDK, and Android UI. It introduces LoRA compatibility checking (with GGUF metadata reading), download workflows with progress reporting, and catalog management. Concurrently, the RunAnyWhereLora example module is largely removed and replaced with LoRA integration in the main ChatScreen UI.

Changes

Cohort / File(s)	Summary
LoRA Implementation Documentation docs/impl/lora_adapter_support.md	Comprehensive new documentation describing LoRA adapter compatibility checking, download workflows, architecture integration, error handling, and API changes across Kotlin, JNI, and C++ layers.
C++ Backend LoRA Support sdk/runanywhere-commons/src/backends/llamacpp/llamacpp_backend.cpp, llamacpp_backend.h	Adds LoRA compatibility checking and GGUF metadata reading; includes pre-load validation comparing adapter and model architectures with error messaging.
C API Layer - LoRA Headers sdk/runanywhere-commons/include/rac/backends/rac_llm_llamacpp.h, sdk/runanywhere-commons/include/rac/features/llm/rac_llm_component.h, sdk/runanywhere-commons/include/rac/features/llm/rac_llm_service.h	Public API declarations for LoRA compatibility checking and vtable expansion; adds check_lora_compat function pointer to service ops structure.
C API Implementation sdk/runanywhere-commons/src/backends/llamacpp/rac_llm_llamacpp.cpp, rac_backend_llamacpp_register.cpp, sdk/runanywhere-commons/src/features/llm/llm_component.cpp	Implements public C APIs for LoRA checking; vtable registration and component-level wrapper with mutex-protected access and error handling.
JNI & Native Bridge sdk/runanywhere-commons/src/jni/runanywhere_commons_jni.cpp, sdk/runanywhere-kotlin/src/jvmAndroidMain/kotlin/com/runanywhere/sdk/native/bridge/RunAnywhereBridge.kt, sdk/runanywhere-kotlin/src/jvmAndroidMain/kotlin/com/runanywhere/sdk/foundation/bridge/extensions/CppBridgeLLM.kt	JNI bindings exposing LoRA compatibility check and Kotlin wrapper with component state validation.
Kotlin Public APIs - LoRA Compatibility sdk/runanywhere-kotlin/src/commonMain/kotlin/com/runanywhere/sdk/public/extensions/RunAnywhere+LoRA.kt, sdk/runanywhere-kotlin/src/jvmAndroidMain/kotlin/com/runanywhere/sdk/public/extensions/RunAnywhere+LoRA.jvmAndroid.kt	Expect/actual declarations for LoRA compatibility checking; includes LoraCompatibilityResult data class and guard checks for SDK initialization.
Kotlin Public APIs - LoRA Download sdk/runanywhere-kotlin/src/commonMain/kotlin/com/runanywhere/sdk/public/extensions/RunAnywhere+LoRADownload.kt, sdk/runanywhere-kotlin/src/jvmAndroidMain/kotlin/com/runanywhere/sdk/public/extensions/RunAnywhere+LoRADownload.jvmAndroid.kt	Expect/actual declarations for LoRA downloads via HTTP; includes LoraDownloadState enum, LoraDownloadProgress data class, Flow-based progress reporting, and atomic file operations.
LoRA Catalog sdk/runanywhere-kotlin/src/commonMain/kotlin/com/runanywhere/sdk/temp/LoraAdapterCatalog.kt	Hardcoded LoRA adapter catalog with five predefined entries and lookup utility; provides data class LoraAdapterEntry for catalog metadata.
Android Chat UI Integration examples/android/RunAnywhereAI/app/src/main/java/com/runanywhere/runanywhereai/presentation/chat/ChatScreen.kt, ChatViewModel.kt	Extends ChatTopBar with LoRA indicator, adds LoRA button to ChatInputView, introduces LoraDialog and LoraScaleDialog composables; ChatViewModel expanded with LoRA state (catalog, downloaded, download progress) and methods for catalog loading, adapter downloading/loading, and clearing.
Model Selection LoRA Support examples/android/RunAnywhereAI/app/src/main/java/com/runanywhere/runanywhereai/presentation/models/ModelSelectionBottomSheet.kt	Adds supportsLora flag to AIModel data class; detects LoRA-compatible models by name pattern and renders LoRA badge on UI.
RunAnyWhereLora Module Removal examples/android/RunAnyWhereLora/...	Complete removal of RunAnyWhereLora example module including: LoraScreen.kt, LoraViewModel.kt, MainActivity.kt, LoraApplication.kt, all theme/color/resource definitions, Gradle/IDE configurations, and build scripts.
IDE VCS Configuration .idea/vcs.xml	Updates Git VCS directory mappings from legacy dev paths to Android/WebGPU build paths (llamacpp-src, nlohmann_json-src, whispercpp-src, stable_diffusion_cpp-src).
RAGBridge Cleanup sdk/runanywhere-kotlin/src/jvmAndroidMain/kotlin/com/runanywhere/sdk/rag/RAGBridge.kt	Removes @Keep annotation from RAGBridge object and associated unused import.

Sequence Diagram(s)

sequenceDiagram
    actor User
    participant Kotlin as Kotlin SDK
    participant JNI as JNI Bridge
    participant C_API as C API (llm_component)
    participant Backend as C++ Backend
    participant GGUF as GGUF File

    User->>Kotlin: checkLoraCompatibility(loraPath)
    activate Kotlin
    Kotlin->>Kotlin: Validate SDK initialized
    Kotlin->>JNI: racLlmComponentCheckLoraCompat(handle, loraPath)
    activate JNI
    JNI->>C_API: rac_llm_component_check_lora_compat(...)
    activate C_API
    C_API->>C_API: Acquire mutex
    C_API->>Backend: llm_service->ops->check_lora_compat(...)
    activate Backend
    Backend->>GGUF: Read LoRA metadata (architecture)
    GGUF-->>Backend: GGUF data
    Backend->>Backend: Compare architectures with loaded model
    alt Architectures match
        Backend-->>C_API: RAC_SUCCESS
    else Architectures mismatch
        Backend-->>C_API: RAC_ERROR_VALIDATION_FAILED + error message
    end
    deactivate Backend
    C_API->>C_API: Release mutex
    C_API-->>JNI: result + error string
    deactivate C_API
    JNI-->>Kotlin: error message or null
    deactivate JNI
    alt Compatible
        Kotlin-->>User: LoraCompatibilityResult(isCompatible=true)
    else Incompatible
        Kotlin-->>User: LoraCompatibilityResult(isCompatible=false, error=...)
    end
    deactivate Kotlin

Loading

sequenceDiagram
    actor User
    participant Android as Android UI
    participant ViewModel as ChatViewModel
    participant Kotlin as Kotlin SDK
    participant HTTP as HTTP Server
    participant FileSystem as Local Storage

    User->>Android: Click Download LoRA
    activate Android
    Android->>ViewModel: downloadLoraFromCatalog(entry)
    activate ViewModel
    ViewModel->>Kotlin: downloadLoraAdapter(entry.url, entry.filename)
    activate Kotlin
    Kotlin->>Kotlin: Create temp file in ModelsDirectory/lora
    Kotlin->>HTTP: Open HttpURLConnection
    activate HTTP
    HTTP-->>Kotlin: contentLengthLong
    deactivate HTTP
    Kotlin->>Kotlin: Emit DOWNLOADING state with totalBytes
    Kotlin->>HTTP: Read stream data
    activate HTTP
    loop Stream chunks
        HTTP-->>Kotlin: Data chunk
        Kotlin->>FileSystem: Write to temp file
        Kotlin->>Kotlin: Update progress (~150ms interval)
        Kotlin-->>ViewModel: Progress update
        ViewModel->>Android: Update UI progress
    end
    HTTP-->>Kotlin: Stream complete
    deactivate HTTP
    Kotlin->>FileSystem: Atomic rename temp→final or copy+delete
    Kotlin->>Kotlin: Emit COMPLETED state with localPath
    Kotlin-->>ViewModel: Final progress with path
    ViewModel->>Android: Render completion
    deactivate Kotlin
    ViewModel->>ViewModel: Scan downloads & refresh adapters
    deactivate ViewModel
    Android->>User: Show downloaded adapter ready to load
    deactivate Android

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• Add lora ios #407: Implements LoRA adapter support across native backend, RAC LLM headers/vtable, and Kotlin SDKs with similar architecture changes and backend integration.
• Added Lora + Fixed Build-All-Work-Flow (#389) #406: Modifies the same LoRA code paths (llamacpp backend, C API, JNI, Kotlin bridge) and introduces overlapping LoRA compatibility and download implementations.
• feat(android): major UI refactor and production setup (v0.1.5) #331: Modifies Android sample UI components (ChatScreen.kt, ModelSelectionBottomSheet.kt) with changes to the same functions and chat behavior integration.

Suggested labels

kotlin-sdk, android-sample, enhancement

Suggested reviewers

• sanchitmonga22

Poem

🐰 Hop along the LoRA trail,
Adapters download without fail,
Compatibility checked with care,
Chat now dons a LoRA flair,
Boinc! Old modules disappear in air! 🎉

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 24.64% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title '[Android SDK] [Kotlin SDK] Add LoRA Adapter Support' accurately describes the main objective of the PR: introducing LoRA adapter support across the Kotlin SDK and Android platform.
Description check	✅ Passed	The PR description is comprehensive and covers the key aspects including summary, changes across different layers, and a test plan. However, some template sections like 'Type of Change', 'Testing' checkboxes, and 'Labels' are not filled out according to the template structure.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch siddhesh/lora-demo

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed everything up to 07700f2 in 16 seconds. Click for details.

• Reviewed 3221 lines of code in 24 files
• Skipped 0 files when reviewing.
• Skipped posting 0 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

Workflow ID: wflow_53KetZF6Bc4rq3wc

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

[greptile-apps]

_{24 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

fallback copyTo after renameTo fails could leave both files present temporarily

Suggested change

	if (destFile.exists()) destFile.delete()
	if (!tempFile.renameTo(destFile)) {
	tempFile.copyTo(destFile, overwrite = true)
	tempFile.delete()
	}
	if (!tempFile.renameTo(destFile)) {
	if (destFile.exists()) destFile.delete()
	tempFile.copyTo(destFile, overwrite = true)
	tempFile.delete()
	}

Prompt To Fix With AI

This is a comment left during a code review.
Path: sdk/runanywhere-kotlin/src/jvmAndroidMain/kotlin/com/runanywhere/sdk/public/extensions/RunAnywhere+LoRADownload.jvmAndroid.kt
Line: 106-110

Comment:
fallback `copyTo` after `renameTo` fails could leave both files present temporarily

```suggestion
                    if (!tempFile.renameTo(destFile)) {
                        if (destFile.exists()) destFile.delete()
                        tempFile.copyTo(destFile, overwrite = true)
                        tempFile.delete()
                    }
```

How can I resolve this? If you propose a fix, please make it concise.

[coderabbitai]

Actionable comments posted: 10

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

sdk/runanywhere-commons/src/backends/llamacpp/rac_backend_llamacpp_register.cpp (1)

129-147: ⚠️ Potential issue | 🟡 Minor

Return RAC_ERROR_NULL_POINTER for invalid args.
Null lora_path / out_error currently becomes RAC_ERROR_VALIDATION_FAILED, which makes API misuse look like incompatibility.

Suggested fix

 static rac_result_t llamacpp_vtable_check_lora_compat(void* impl, const char* lora_path, char** out_error) {
+    if (lora_path == nullptr || out_error == nullptr) {
+        return RAC_ERROR_NULL_POINTER;
+    }
     rac_bool_t result = rac_llm_llamacpp_check_lora_compat(impl, lora_path, out_error);
     return (result == RAC_TRUE) ? RAC_SUCCESS : RAC_ERROR_VALIDATION_FAILED;
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@sdk/runanywhere-commons/src/backends/llamacpp/rac_backend_llamacpp_register.cpp`
around lines 129 - 147, The check function llamacpp_vtable_check_lora_compat
should validate input pointers and return RAC_ERROR_NULL_POINTER for null args
instead of treating them as validation failures; update
llamacpp_vtable_check_lora_compat to first verify impl, lora_path, and out_error
are non-NULL and return RAC_ERROR_NULL_POINTER immediately if any are NULL, and
only then call rac_llm_llamacpp_check_lora_compat and map its boolean result to
RAC_SUCCESS or RAC_ERROR_VALIDATION_FAILED; keep
g_llamacpp_ops.check_lora_compat pointing to llamacpp_vtable_check_lora_compat.

🧹 Nitpick comments (8)

examples/android/RunAnyWhereLora/app/src/main/java/com/runanywhere/run_anywhere_lora/LoraScreen.kt (2)

159-167: Potential missed trigger if download path is reused.

If the user downloads the same adapter file twice (e.g., after deleting it), state.loraDownload.downloadedPath will hold the same value as before clearDownloadState() resets it to null. This should work correctly since the flow is null → path → null → path. However, there is a subtle timing concern: clearDownloadState() on line 164 sets the path back to null, which means the next LaunchedEffect recomposition will see null and skip. On the subsequent download completion, it will see the path again and trigger. This looks correct.

One concern: viewModel.clearDownloadState() and showDownloadDialog = false are both executed in sequence, but the dialog dismissal triggers recomposition which could race with the state update. Consider whether clearDownloadState should be called after setting pendingLoraPath to ensure the scale dialog appears before the download state is cleared.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@examples/android/RunAnyWhereLora/app/src/main/java/com/runanywhere/run_anywhere_lora/LoraScreen.kt`
around lines 159 - 167, Reorder the state updates in the LaunchedEffect handling
state.loraDownload.downloadedPath so the local UI state is captured before
clearing the download state: when path != null, first assign pendingLoraPath =
path, then set showDownloadDialog = false (to trigger the scale dialog UI), and
only after those UI state updates call viewModel.clearDownloadState(); this
ensures LaunchedEffect/compose recomposition shows the dialog based on
pendingLoraPath before the shared viewModel download state is reset.

---

897-914: Non-interactive SuggestionChip with empty onClick may confuse users.

These chips look tappable but do nothing. Consider either using a plain Text/surface composable instead, or wiring the onClick to pre-fill the prompt input so the user can try the sample prompt after loading the adapter.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@examples/android/RunAnyWhereLora/app/src/main/java/com/runanywhere/run_anywhere_lora/LoraScreen.kt`
around lines 897 - 914, The SuggestionChip instances in the FlowRow are
non-interactive because onClick is an empty lambda; either replace
SuggestionChip with a non-tappable composable (e.g., Text or Surface) to avoid
misleading affordance, or wire SuggestionChip's onClick to populate the prompt
input state used by this screen (i.e., update the prompt input state or call the
existing prompt handler/callback when a sample prompt from
template.samplePrompts is clicked) so tapping a chip pre-fills the input for the
user to submit.

examples/android/RunAnyWhereLora/app/src/main/java/com/runanywhere/run_anywhere_lora/LoraPromptTemplates.kt (1)

13-53: Template keys are stringly-coupled to catalog adapter IDs.

The template map keys (e.g., "chat-assistant-lora") must exactly match LoraAdapterEntry.id values in LoraAdapterCatalog. Consider referencing the catalog IDs directly to avoid silent mismatches if IDs change.

Example using catalog constants

import com.runanywhere.sdk.temp.LoraAdapterCatalog

val loraPromptTemplates: Map<String, LoraPromptTemplate> = mapOf(
    LoraAdapterCatalog.adapters[0].id to LoraPromptTemplate(
        // ...
    ),
    // or define ID constants in the catalog
)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@examples/android/RunAnyWhereLora/app/src/main/java/com/runanywhere/run_anywhere_lora/LoraPromptTemplates.kt`
around lines 13 - 53, The map loraPromptTemplates uses hard-coded string keys
(e.g., "chat-assistant-lora") that must match LoraAdapterEntry.id values in
LoraAdapterCatalog; change the keys to reference the catalog IDs instead (for
example via LoraAdapterCatalog.adapters[index].id or defined constants on
LoraAdapterCatalog) so keys stay in sync, update any usages expecting those keys
accordingly, and ensure imports for LoraAdapterCatalog are added next to
LoraPromptTemplate where loraPromptTemplates is declared.

sdk/runanywhere-commons/src/jni/runanywhere_commons_jni.cpp (1)

1184-1211: Consider surfacing the RAC error code when error is null.
Right now the fallback “Incompatible LoRA adapter” hides cases like component-not-ready or invalid argument.

Suggested tweak

     jstring jresult = nullptr;
     if (error) {
         jresult = env->NewStringUTF(error);
         rac_free(error);
     } else {
-        jresult = env->NewStringUTF("Incompatible LoRA adapter");
+        const char* msg = rac_error_message(result);
+        jresult = env->NewStringUTF(msg && *msg ? msg : "Incompatible LoRA adapter");
     }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/src/jni/runanywhere_commons_jni.cpp` around lines
1184 - 1211, The JNI function racLlmComponentCheckLoraCompat currently returns a
generic "Incompatible LoRA adapter" when rac_llm_component_check_lora_compat
fails but provides no error string; update the failure branch so when error ==
nullptr you include the numeric rac_result_t (result) in the returned message
(e.g. "Incompatible LoRA adapter (error code: %d)") by formatting into a local
buffer and calling env->NewStringUTF, and keep the existing behavior of
env->NewStringUTF(error) + rac_free(error) when error is non-null; reference
racLlmComponentCheckLoraCompat, rac_llm_component_check_lora_compat,
rac_result_t and RAC_SUCCESS to locate and modify the code.

examples/android/RunAnywhereAI/app/src/main/java/com/runanywhere/runanywhereai/presentation/models/ModelSelectionBottomSheet.kt (1)

252-260: Avoid string-based LoRA detection.
Deriving supportsLora from name is brittle and not type-safe. Prefer a structured field (e.g., ModelInfo.supportsLora or catalog metadata) and compute this upstream.

As per coding guidelines: Always use structured types and data classes instead of strings directly for type safety and consistency.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@examples/android/RunAnywhereAI/app/src/main/java/com/runanywhere/runanywhereai/presentation/models/ModelSelectionBottomSheet.kt`
around lines 252 - 260, The current supportsLora flag is computed by brittle
string checks in ModelSelectionBottomSheet (the nameLower.contains("lfm2") &&
nameLower.contains("350m") logic) — change this to read a typed property from
the model metadata instead: add a boolean supportsLora field to the model
info/data class that is populated upstream when the model catalog or parsing
logic determines Lora support, and then replace the string-based expression in
the AIModel constructor with that property (use m.supportsLora in the
AIModel(...) call). Update the code path that builds/loads m (the model metadata
factory or parser) to compute and set supportsLora based on structured criteria
rather than name substrings.

sdk/runanywhere-kotlin/src/commonMain/kotlin/com/runanywhere/sdk/public/extensions/RunAnywhere+LoRADownload.kt (1)

19-47: Consider sealed progress/error types instead of enum + nullable error.

A sealed hierarchy (e.g., Pending/Downloading/Completed/Error) would make error handling more type-safe than state + error: String?, and avoids nullable payloads.
As per coding guidelines, "Use sealed classes for type-safe error handling rather than generic exception handling".

Also applies to: 61-82

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@sdk/runanywhere-kotlin/src/commonMain/kotlin/com/runanywhere/sdk/public/extensions/RunAnywhere`+LoRADownload.kt
around lines 19 - 47, Replace the enum+nullable pattern LoraDownloadState +
LoraDownloadProgress with a sealed class hierarchy to make states and payloads
type-safe: create a sealed class LoraDownloadProgress with subclasses Pending,
Downloading(progress: Float, bytesDownloaded: Long, totalBytes: Long?),
Completed(localPath: String, bytesDownloaded: Long, totalBytes: Long?), and
Error(message: String), and update any callers that construct or inspect
LoraDownloadState/LoraDownloadProgress to use sealed-type pattern matching
instead of state+nullable fields; apply the same refactor to the other
progress/error pair in this file that follows the same pattern.

examples/android/RunAnywhereAI/app/src/main/java/com/runanywhere/runanywhereai/presentation/chat/ChatViewModel.kt (1)

747-758: Hard‑coded LoRA compatibility checks are brittle.

The lfm2 + 350m name heuristic appears in multiple spots and can silently hide LoRA for other compatible models. Consider centralizing this in a helper and/or deriving it from model metadata or backend capabilities.

Also applies to: 771-814

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@examples/android/RunAnywhereAI/app/src/main/java/com/runanywhere/runanywhereai/presentation/chat/ChatViewModel.kt`
around lines 747 - 758, The hard-coded LoRA compatibility heuristic in
ChatViewModel (the local loraCompat = nameLower.contains("lfm2") &&
nameLower.contains("350m") logic used before updating _uiState and calling
loadLoraCatalog()/scanDownloadedAdapters()) should be replaced with a
centralized helper or service: extract the check into a single function like
isModelLoraCompatible(modelName: String) or, better, consult model
metadata/backend capability (e.g., model metadata field or capability flag) and
use that result to set isLoraCompatibleModel and gate
loadLoraCatalog()/scanDownloadedAdapters(); update all other occurrences (the
other places mentioned around the 771-814 range) to call the same helper/service
so the heuristic is maintained in one place.

sdk/runanywhere-commons/src/backends/llamacpp/llamacpp_backend.cpp (1)

889-939: Prefer a structured compatibility result over raw strings.

check_lora_compatibility returns bool plus a mutable std::string& for errors. Consider returning a small struct (e.g., {bool ok; rac_error_t code; std::string message;}) to align with the structured-type rule and avoid stale error reuse.
As per coding guidelines, "Always use structured types, never use strings directly for consistency and scalability".

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/src/backends/llamacpp/llamacpp_backend.cpp` around
lines 889 - 939, check_lora_compatibility currently returns bool + an out
std::string&; change it to return a small structured result type (e.g., struct
LoraCompatResult { bool ok; rac_error_t code; std::string message; }) and remove
the mutable std::string& parameter, populate appropriate codes (e.g., RAC_OK,
RAC_ERR_NO_MODEL, RAC_ERR_READ_LORA, RAC_ERR_ARCH_MISMATCH) and messages inside
check_lora_compatibility, update all callers to use the new LoraCompatResult,
and ensure resources (like lora_ctx) and logging (LOGI/LOGE) remain the same
while filling result.message instead of using the out-string to avoid stale
error reuse and to satisfy the structured-type rule.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.idea/vcs.xml:
- Around line 5-16: Remove all machine-local VCS mapping entries in
.idea/vcs.xml that point into generated build directories and local tools (the
<mapping directory=".../_deps/..." vcs="Git" /> and the emsdk mapping); keep
only the root mapping entry (the mapping with directory="") in the file, and
commit that change. Optionally, consider removing .idea/vcs.xml from version
control or update ignore rules so only machine-agnostic IDE metadata is tracked.

In `@docs/impl/lora_adapter_support.md`:
- Around line 720-748: Update the two fenced code blocks that show the check
flow and the download flow to include a language tag (use "text") so they read
```text ... ``` instead of ``` ... ```, and fix the typo "cal" to "call" in the
trailing sentence; ensure the same changes are applied to the duplicate block at
lines noted (the second occurrence shown around RunAnywhere.downloadLoraAdapter
/ LoraDownloadProgress).

In
`@examples/android/RunAnyWhereLora/app/src/main/java/com/runanywhere/run_anywhere_lora/LoraScreen.kt`:
- Around line 793-802: The TextButton currently enables/downloads based only on
urlInput.isNotBlank(); add client-side URL validation so the button only enables
and triggers when the URL is well-formed (e.g., starts with "https://" or
matches Android's URL pattern). Create a helper like isValidUrl(url: String)
used both in the enabled expression and in the onClick guard before calling
onDownloadFromUrl(urlInput.trim(), nameInput.trim()), and return/notify the user
if invalid; reference the existing urlInput, nameInput, onDownloadFromUrl, and
the TextButton block in LoraScreen.kt when applying the change.

In
`@examples/android/RunAnyWhereLora/app/src/main/java/com/runanywhere/run_anywhere_lora/LoraViewModel.kt`:
- Around line 136-168: The filename can contain path traversal segments; in
downloadLoraFromUrl sanitize it by extracting only the basename before appending
".gguf" (e.g. use File(filename).name or
Paths.get(filename).fileName.toString()), reject or replace empty basenames with
a safe default, and then use that sanitizedFilename when calling
RunAnywhere.downloadLoraAdapter so downloads cannot escape the intended lora/
directory.

In `@sdk/runanywhere-commons/include/rac/backends/rac_llm_llamacpp.h`:
- Around line 247-275: Update the two function docblocks to instruct callers to
use rac_free instead of free(): change the "caller must free with free()" note
in rac_llm_llamacpp_check_lora_compat and the "caller must free with free()"
note in rac_llm_llamacpp_read_gguf_info to "caller must free with rac_free" so
docs correctly reflect the repository's memory-deallocation API.

In `@sdk/runanywhere-commons/include/rac/features/llm/rac_llm_component.h`:
- Around line 266-280: Update the rac_llm_component_check_lora_compat
declaration docs to explicitly list possible rac_result_t error codes (e.g.,
RAC_SUCCESS, RAC_ERROR_INVALID_ARGUMENT, RAC_ERROR_COMPONENT_NOT_READY,
RAC_ERROR_IO, etc.), state the lifecycle requirement that a model must be loaded
into the component before calling this function, and clarify ownership/cleanup
for out_error (caller must free with rac_free when non-NULL); reference the
function name rac_llm_component_check_lora_compat, parameter types rac_handle_t
and char**, return type rac_result_t, and the rac_free helper so callers know
expected states and error handling.

In `@sdk/runanywhere-commons/include/rac/features/llm/rac_llm_service.h`:
- Around line 64-67: Update the comment for the vtable function pointer
check_lora_compat to document out_error ownership: state that when
check_lora_compat(void* impl, const char* lora_path, char** out_error) returns
an error (non-RAC_SUCCESS) it allocates *out_error and the caller is responsible
for freeing it with free(), and when the function returns RAC_SUCCESS it sets
*out_error to NULL (no allocation).

In `@sdk/runanywhere-commons/src/backends/llamacpp/llamacpp_backend.cpp`:
- Around line 889-939: The method check_lora_compatibility reads shared state
(model_ and model_loaded_) without synchronization, risking races with
load_model()/unload_model(); similarly is_model_loaded() and get_model_info()
need protection. Fix by adding std::lock_guard<std::mutex> lock(mutex_) at the
start of each of these const methods (check_lora_compatibility, is_model_loaded,
get_model_info) so the body executes while holding mutex_, preventing
use-after-free when the C API wrapper rac_llm_llamacpp_check_lora_compat() is
invoked concurrently.

In
`@sdk/runanywhere-kotlin/src/commonMain/kotlin/com/runanywhere/sdk/public/extensions/RunAnywhere`+LoRA.kt:
- Around line 61-69: Make the API function suspend: change the declaration of
checkLoraCompatibility to "suspend fun
RunAnywhere.checkLoraCompatibility(loraPath: String): LoraCompatibilityResult"
and update all platform-specific actual implementations accordingly (the
JVM/native implementations that call JNI and use synchronized(lock)). Update any
callers (or ensure they still wrap with withContext(Dispatchers.IO)) to match
the new suspend signature. Keep the function body logic unchanged (GGUF metadata
read, architecture compare) but mark it suspend so blocking JNI/synchronized
calls are clearly asynchronous.

In
`@sdk/runanywhere-kotlin/src/jvmAndroidMain/kotlin/com/runanywhere/sdk/public/extensions/RunAnywhere`+LoRADownload.jvmAndroid.kt:
- Around line 26-142: The download uses filename directly which allows path
traversal and arbitrary extensions; in RunAnywhere.downloadLoraAdapter sanitize
filename by deriving a safe basename (strip any directory components, reject or
replace path separators), ensure it is non-empty, and enforce the .gguf
extension (append or replace other extensions) before creating destFile and
tempFile; use this safeFilename variable in the File(destDir, safeFilename) and
File(destDir, "$safeFilename.tmp") calls and validate the resulting path stays
under destDir.

---

Outside diff comments:
In
`@sdk/runanywhere-commons/src/backends/llamacpp/rac_backend_llamacpp_register.cpp`:
- Around line 129-147: The check function llamacpp_vtable_check_lora_compat
should validate input pointers and return RAC_ERROR_NULL_POINTER for null args
instead of treating them as validation failures; update
llamacpp_vtable_check_lora_compat to first verify impl, lora_path, and out_error
are non-NULL and return RAC_ERROR_NULL_POINTER immediately if any are NULL, and
only then call rac_llm_llamacpp_check_lora_compat and map its boolean result to
RAC_SUCCESS or RAC_ERROR_VALIDATION_FAILED; keep
g_llamacpp_ops.check_lora_compat pointing to llamacpp_vtable_check_lora_compat.

---

Nitpick comments:
In
`@examples/android/RunAnywhereAI/app/src/main/java/com/runanywhere/runanywhereai/presentation/chat/ChatViewModel.kt`:
- Around line 747-758: The hard-coded LoRA compatibility heuristic in
ChatViewModel (the local loraCompat = nameLower.contains("lfm2") &&
nameLower.contains("350m") logic used before updating _uiState and calling
loadLoraCatalog()/scanDownloadedAdapters()) should be replaced with a
centralized helper or service: extract the check into a single function like
isModelLoraCompatible(modelName: String) or, better, consult model
metadata/backend capability (e.g., model metadata field or capability flag) and
use that result to set isLoraCompatibleModel and gate
loadLoraCatalog()/scanDownloadedAdapters(); update all other occurrences (the
other places mentioned around the 771-814 range) to call the same helper/service
so the heuristic is maintained in one place.

In
`@examples/android/RunAnywhereAI/app/src/main/java/com/runanywhere/runanywhereai/presentation/models/ModelSelectionBottomSheet.kt`:
- Around line 252-260: The current supportsLora flag is computed by brittle
string checks in ModelSelectionBottomSheet (the nameLower.contains("lfm2") &&
nameLower.contains("350m") logic) — change this to read a typed property from
the model metadata instead: add a boolean supportsLora field to the model
info/data class that is populated upstream when the model catalog or parsing
logic determines Lora support, and then replace the string-based expression in
the AIModel constructor with that property (use m.supportsLora in the
AIModel(...) call). Update the code path that builds/loads m (the model metadata
factory or parser) to compute and set supportsLora based on structured criteria
rather than name substrings.

In
`@examples/android/RunAnyWhereLora/app/src/main/java/com/runanywhere/run_anywhere_lora/LoraPromptTemplates.kt`:
- Around line 13-53: The map loraPromptTemplates uses hard-coded string keys
(e.g., "chat-assistant-lora") that must match LoraAdapterEntry.id values in
LoraAdapterCatalog; change the keys to reference the catalog IDs instead (for
example via LoraAdapterCatalog.adapters[index].id or defined constants on
LoraAdapterCatalog) so keys stay in sync, update any usages expecting those keys
accordingly, and ensure imports for LoraAdapterCatalog are added next to
LoraPromptTemplate where loraPromptTemplates is declared.

In
`@examples/android/RunAnyWhereLora/app/src/main/java/com/runanywhere/run_anywhere_lora/LoraScreen.kt`:
- Around line 159-167: Reorder the state updates in the LaunchedEffect handling
state.loraDownload.downloadedPath so the local UI state is captured before
clearing the download state: when path != null, first assign pendingLoraPath =
path, then set showDownloadDialog = false (to trigger the scale dialog UI), and
only after those UI state updates call viewModel.clearDownloadState(); this
ensures LaunchedEffect/compose recomposition shows the dialog based on
pendingLoraPath before the shared viewModel download state is reset.
- Around line 897-914: The SuggestionChip instances in the FlowRow are
non-interactive because onClick is an empty lambda; either replace
SuggestionChip with a non-tappable composable (e.g., Text or Surface) to avoid
misleading affordance, or wire SuggestionChip's onClick to populate the prompt
input state used by this screen (i.e., update the prompt input state or call the
existing prompt handler/callback when a sample prompt from
template.samplePrompts is clicked) so tapping a chip pre-fills the input for the
user to submit.

In `@sdk/runanywhere-commons/src/backends/llamacpp/llamacpp_backend.cpp`:
- Around line 889-939: check_lora_compatibility currently returns bool + an out
std::string&; change it to return a small structured result type (e.g., struct
LoraCompatResult { bool ok; rac_error_t code; std::string message; }) and remove
the mutable std::string& parameter, populate appropriate codes (e.g., RAC_OK,
RAC_ERR_NO_MODEL, RAC_ERR_READ_LORA, RAC_ERR_ARCH_MISMATCH) and messages inside
check_lora_compatibility, update all callers to use the new LoraCompatResult,
and ensure resources (like lora_ctx) and logging (LOGI/LOGE) remain the same
while filling result.message instead of using the out-string to avoid stale
error reuse and to satisfy the structured-type rule.

In `@sdk/runanywhere-commons/src/jni/runanywhere_commons_jni.cpp`:
- Around line 1184-1211: The JNI function racLlmComponentCheckLoraCompat
currently returns a generic "Incompatible LoRA adapter" when
rac_llm_component_check_lora_compat fails but provides no error string; update
the failure branch so when error == nullptr you include the numeric rac_result_t
(result) in the returned message (e.g. "Incompatible LoRA adapter (error code:
%d)") by formatting into a local buffer and calling env->NewStringUTF, and keep
the existing behavior of env->NewStringUTF(error) + rac_free(error) when error
is non-null; reference racLlmComponentCheckLoraCompat,
rac_llm_component_check_lora_compat, rac_result_t and RAC_SUCCESS to locate and
modify the code.

In
`@sdk/runanywhere-kotlin/src/commonMain/kotlin/com/runanywhere/sdk/public/extensions/RunAnywhere`+LoRADownload.kt:
- Around line 19-47: Replace the enum+nullable pattern LoraDownloadState +
LoraDownloadProgress with a sealed class hierarchy to make states and payloads
type-safe: create a sealed class LoraDownloadProgress with subclasses Pending,
Downloading(progress: Float, bytesDownloaded: Long, totalBytes: Long?),
Completed(localPath: String, bytesDownloaded: Long, totalBytes: Long?), and
Error(message: String), and update any callers that construct or inspect
LoraDownloadState/LoraDownloadProgress to use sealed-type pattern matching
instead of state+nullable fields; apply the same refactor to the other
progress/error pair in this file that follows the same pattern.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check for .gitignore entries related to .idea/
echo "=== Checking .gitignore files for .idea/ entries ==="
find . -name ".gitignore" -type f | head -20 | while read f; do
  if grep -q "\.idea" "$f" 2>/dev/null; then
    echo "Found in: $f"
    grep -n "\.idea" "$f"
  fi
done

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 2011

---

🏁 Script executed:

#!/bin/bash
# View the full content of .idea/vcs.xml with line numbers
echo "=== Full content of .idea/vcs.xml ==="
if [ -f ".idea/vcs.xml" ]; then
  cat -n ".idea/vcs.xml"
else
  echo ".idea/vcs.xml not found"
fi

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 1869

---

Remove all machine-local build-artifact paths from .idea/vcs.xml.

Every entry at lines 5–16 points into generated build directories (_deps/… populated by CMake) or locally-installed tools (emsdk). These paths:

• Do not exist on any other developer's machine unless they have built the exact same way.
• Are ephemeral, architecture-specific, and differ per build directory.
• Will cause spurious "unregistered VCS root detected" warnings for teammates.

The root mapping on line 4 (directory="") already covers the entire repository. The entries below add no value and create friction.

🛠️ Proposed fix — keep only the root mapping

 <component name="VcsDirectoryMappings">
   <mapping directory="" vcs="Git" />
-  <mapping directory="$PROJECT_DIR$/sdk/runanywhere-commons/build/android/sdcpp/arm64-v8a/_deps/nlohmann_json-src" vcs="Git" />
-  <mapping directory="$PROJECT_DIR$/sdk/runanywhere-commons/build/android/sdcpp/arm64-v8a/_deps/opencl_headers-src" vcs="Git" />
-  <mapping directory="$PROJECT_DIR$/sdk/runanywhere-commons/build/android/sdcpp/arm64-v8a/_deps/stable_diffusion_cpp-src" vcs="Git" />
-  <mapping directory="$PROJECT_DIR$/sdk/runanywhere-commons/build/android/sdcpp/arm64-v8a/_deps/stable_diffusion_cpp-src/ggml" vcs="Git" />
-  <mapping directory="$PROJECT_DIR$/sdk/runanywhere-commons/build/android/unified/arm64-v8a/_deps/llamacpp-src" vcs="Git" />
-  <mapping directory="$PROJECT_DIR$/sdk/runanywhere-commons/build/android/unified/arm64-v8a/_deps/nlohmann_json-src" vcs="Git" />
-  <mapping directory="$PROJECT_DIR$/sdk/runanywhere-commons/build/android/unified/x86_64/_deps/llamacpp-src" vcs="Git" />
-  <mapping directory="$PROJECT_DIR$/sdk/runanywhere-commons/build/android/unified/x86_64/_deps/nlohmann_json-src" vcs="Git" />
-  <mapping directory="$PROJECT_DIR$/sdk/runanywhere-web/emsdk" vcs="Git" />
-  <mapping directory="$PROJECT_DIR$/sdk/runanywhere-web/wasm/build-webgpu/_deps/llamacpp-src" vcs="Git" />
-  <mapping directory="$PROJECT_DIR$/sdk/runanywhere-web/wasm/build-webgpu/_deps/nlohmann_json-src" vcs="Git" />
-  <mapping directory="$PROJECT_DIR$/sdk/runanywhere-web/wasm/build-webgpu/_deps/whispercpp-src" vcs="Git" />
 </component>

Note: .idea/vcs.xml is currently tracked (via !.idea/vcs.xml in .gitignore). Consider whether this file belongs in version control at all, or adopt a policy to exclude only machine-agnostic IDE metadata (e.g., .idea/codeStyles/, .idea/inspectionProfiles/).

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.idea/vcs.xml around lines 5 - 16, Remove all machine-local VCS mapping
entries in .idea/vcs.xml that point into generated build directories and local
tools (the <mapping directory=".../_deps/..." vcs="Git" /> and the emsdk
mapping); keep only the root mapping entry (the mapping with directory="") in
the file, and commit that change. Optionally, consider removing .idea/vcs.xml
from version control or update ignore rules so only machine-agnostic IDE
metadata is tracked.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Doc lint: add fenced code block languages + fix typo.

Two fenced blocks are missing a language tag, and “cal” should be “call”.

✍️ Proposed fix

-```
+```text
 1. Kotlin calls RunAnywhere.checkLoraCompatibility(path)
 ...
-```
+```

-```
+```text
 1. RunAnywhere.downloadLoraAdapter(url, filename) returns Flow<LoraDownloadProgress>
 ...
-```
+```

-This makes the check fast (< 1ms for typical LoRA files) and safe to cal repeatedly.
+This makes the check fast (< 1ms for typical LoRA files) and safe to call repeatedly.

Also applies to: 842-847

🧰 Tools

🪛 markdownlint-cli2 (0.21.0)

[warning] 720-720: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

[warning] 742-742: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/impl/lora_adapter_support.md` around lines 720 - 748, Update the two
fenced code blocks that show the check flow and the download flow to include a
language tag (use "text") so they read ```text ... ``` instead of ``` ... ```,
and fix the typo "cal" to "call" in the trailing sentence; ensure the same
changes are applied to the duplicate block at lines noted (the second occurrence
shown around RunAnywhere.downloadLoraAdapter / LoraDownloadProgress).

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

No URL format validation before triggering download.

The download button only checks isNotBlank() but doesn't validate that urlInput is a valid URL (e.g., starts with https://). Invalid URLs will fail at the network layer, but basic client-side validation provides better UX.

Proposed fix

 TextButton(
     onClick = {
-        if (urlInput.isNotBlank() && nameInput.isNotBlank()) {
+        val trimmedUrl = urlInput.trim()
+        if (trimmedUrl.isNotBlank() && nameInput.isNotBlank() &&
+            (trimmedUrl.startsWith("http://") || trimmedUrl.startsWith("https://"))
+        ) {
-            onDownloadFromUrl(urlInput.trim(), nameInput.trim())
+            onDownloadFromUrl(trimmedUrl, nameInput.trim())
         }
     },
-    enabled = urlInput.isNotBlank() && nameInput.isNotBlank(),
+    enabled = urlInput.isNotBlank() && nameInput.isNotBlank() &&
+        (urlInput.trim().startsWith("http://") || urlInput.trim().startsWith("https://")),
 ) {

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@examples/android/RunAnyWhereLora/app/src/main/java/com/runanywhere/run_anywhere_lora/LoraScreen.kt`
around lines 793 - 802, The TextButton currently enables/downloads based only on
urlInput.isNotBlank(); add client-side URL validation so the button only enables
and triggers when the URL is well-formed (e.g., starts with "https://" or
matches Android's URL pattern). Create a helper like isValidUrl(url: String)
used both in the enabled expression and in the onClick guard before calling
onDownloadFromUrl(urlInput.trim(), nameInput.trim()), and return/notify the user
if invalid; reference the existing urlInput, nameInput, onDownloadFromUrl, and
the TextButton block in LoraScreen.kt when applying the change.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Sanitize user‑provided filenames to prevent path traversal.

filename is only extension-sanitized, so values like ../foo can escape the lora/ dir. Normalize to a basename before appending .gguf.

🔒 Proposed fix

-        val sanitizedFilename = if (filename.endsWith(".gguf")) filename else "$filename.gguf"
+        val safeName = File(filename).name
+        val sanitizedFilename = if (safeName.endsWith(".gguf")) safeName else "$safeName.gguf"

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@examples/android/RunAnyWhereLora/app/src/main/java/com/runanywhere/run_anywhere_lora/LoraViewModel.kt`
around lines 136 - 168, The filename can contain path traversal segments; in
downloadLoraFromUrl sanitize it by extracting only the basename before appending
".gguf" (e.g. use File(filename).name or
Paths.get(filename).fileName.toString()), reject or replace empty basenames with
a safe default, and then use that sanitizedFilename when calling
RunAnywhere.downloadLoraAdapter so downloads cannot escape the intended lora/
directory.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Doc should reference rac_free, not free().
The APIs return strdup’d memory that callers typically release via rac_free in this repo.

Doc fix

- * `@param` out_error Output: error message if incompatible (caller must free with free()).
+ * `@param` out_error Output: error message if incompatible (caller must free with rac_free()).
...
- * `@param` out_json Output: JSON string (caller must free with free())
+ * `@param` out_json Output: JSON string (caller must free with rac_free())

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	/**
	* Check if a LoRA adapter is compatible with the currently loaded model.
	*
	* Reads the GGUF metadata header of the LoRA file and compares
	* general.architecture with the loaded model.
	*
	* @param handle Service handle (must have a model loaded)
	* @param lora_path Path to the LoRA adapter GGUF file
	* @param out_error Output: error message if incompatible (caller must free with free()).
	* Set to NULL if compatible.
	* @return RAC_TRUE if compatible, RAC_FALSE if not
	*/
	RAC_LLAMACPP_API rac_bool_t rac_llm_llamacpp_check_lora_compat(rac_handle_t handle,
	const char* lora_path,
	char** out_error);
	/**
	* Read GGUF metadata from a file without loading the model weights.
	*
	* Returns a JSON object containing all scalar metadata key-value pairs
	* and tensor count. Useful for inspecting LoRA adapter properties.
	*
	* @param path Path to the GGUF file
	* @param out_json Output: JSON string (caller must free with free())
	* @return RAC_SUCCESS or error code
	*/
	RAC_LLAMACPP_API rac_result_t rac_llm_llamacpp_read_gguf_info(const char* path,
	char** out_json);
	/**
	* Check if a LoRA adapter is compatible with the currently loaded model.
	*
	* Reads the GGUF metadata header of the LoRA file and compares
	* general.architecture with the loaded model.
	*
	* `@param` handle Service handle (must have a model loaded)
	* `@param` lora_path Path to the LoRA adapter GGUF file
	* `@param` out_error Output: error message if incompatible (caller must free with rac_free()).
	* Set to NULL if compatible.
	* `@return` RAC_TRUE if compatible, RAC_FALSE if not
	*/
	RAC_LLAMACPP_API rac_bool_t rac_llm_llamacpp_check_lora_compat(rac_handle_t handle,
	const char* lora_path,
	char** out_error);
	/**
	* Read GGUF metadata from a file without loading the model weights.
	*
	* Returns a JSON object containing all scalar metadata key-value pairs
	* and tensor count. Useful for inspecting LoRA adapter properties.
	*
	* `@param` path Path to the GGUF file
	* `@param` out_json Output: JSON string (caller must free with rac_free())
	* `@return` RAC_SUCCESS or error code
	*/
	RAC_LLAMACPP_API rac_result_t rac_llm_llamacpp_read_gguf_info(const char* path,
	char** out_json);

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/include/rac/backends/rac_llm_llamacpp.h` around lines
247 - 275, Update the two function docblocks to instruct callers to use rac_free
instead of free(): change the "caller must free with free()" note in
rac_llm_llamacpp_check_lora_compat and the "caller must free with free()" note
in rac_llm_llamacpp_read_gguf_info to "caller must free with rac_free" so docs
correctly reflect the repository's memory-deallocation API.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Document explicit error codes and lifecycle requirement.
The new API returns “error code if not,” but doesn’t list expected codes (e.g., component not ready, invalid argument) or state that a model must be loaded.

Doc tweak

- * `@return` RAC_SUCCESS if compatible, error code if not
+ * `@return` RAC_SUCCESS if compatible,
+ *         RAC_ERROR_COMPONENT_NOT_READY if no model is loaded,
+ *         RAC_ERROR_INVALID_ARGUMENT for null inputs,
+ *         RAC_ERROR_VALIDATION_FAILED when incompatible.

As per coding guidelines: Public C API headers in include/rac/ must document vtable operations, error codes, and lifecycle requirements.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/include/rac/features/llm/rac_llm_component.h` around
lines 266 - 280, Update the rac_llm_component_check_lora_compat declaration docs
to explicitly list possible rac_result_t error codes (e.g., RAC_SUCCESS,
RAC_ERROR_INVALID_ARGUMENT, RAC_ERROR_COMPONENT_NOT_READY, RAC_ERROR_IO, etc.),
state the lifecycle requirement that a model must be loaded into the component
before calling this function, and clarify ownership/cleanup for out_error
(caller must free with rac_free when non-NULL); reference the function name
rac_llm_component_check_lora_compat, parameter types rac_handle_t and char**,
return type rac_result_t, and the rac_free helper so callers know expected
states and error handling.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

# Find all references to check_lora_compat
rg -n "check_lora_compat" --type=cpp --type=c --type=h -B 2 -A 2

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 8117

---

🏁 Script executed:

# Find the vtable struct definition to understand the full context
rg -n "rac_llm_service_ops" --type=h -A 30

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 15611

---

🏁 Script executed:

# Search for other out_error parameters to see how they're documented
rg -n "out_error" sdk/runanywhere-commons/include/rac/ --type=h -B 2 -A 1

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 3282

---

🏁 Script executed:

# Check for implementations of LoRA functions to understand memory ownership
rg -n "load_lora|remove_lora|clear_lora" --type=cpp --type=c -A 5

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 26665

---

🏁 Script executed:

# Check the actual implementation to see which free function is used
rg -n "free.*out_error|out_error.*free" sdk/runanywhere-commons/src/backends/llamacpp/rac_llm_llamacpp.cpp -A 2 -B 2

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 56

---

🏁 Script executed:

# Check the actual implementation of check_lora_compat to see how out_error is set
sed -n '409,440p' sdk/runanywhere-commons/src/backends/llamacpp/rac_llm_llamacpp.cpp

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 1157

---

🏁 Script executed:

# Check if there's a pattern for memory allocation in the error handling
rg -n "strdup\|malloc\|new" sdk/runanywhere-commons/src/backends/llamacpp/rac_llm_llamacpp.cpp | head -20

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 56

---

Document memory ownership for out_error parameter.

The vtable operation lacks critical lifecycle documentation present in the corresponding public API headers. According to the coding guideline requiring vtable headers to document lifecycle requirements, the comment should specify that the caller is responsible for freeing *out_error (via free()), and that *out_error is only allocated when the function returns an error code (incompatible). When compatible, *out_error is set to NULL.

Suggested documentation improvement

    /** Check LoRA adapter compatibility (optional, NULL if not supported).
-    *  Returns RAC_SUCCESS if compatible. out_error is set on incompatibility. */
+    *  Returns RAC_SUCCESS if compatible.
+    *  On incompatibility, returns an error code and sets *out_error to a
+    *  heap-allocated string describing the issue (caller must free()).
+    *  *out_error is set to NULL when compatible. */
    rac_result_t (*check_lora_compat)(void* impl, const char* lora_path, char** out_error);

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/include/rac/features/llm/rac_llm_service.h` around
lines 64 - 67, Update the comment for the vtable function pointer
check_lora_compat to document out_error ownership: state that when
check_lora_compat(void* impl, const char* lora_path, char** out_error) returns
an error (non-RAC_SUCCESS) it allocates *out_error and the caller is responsible
for freeing it with free(), and when the function returns RAC_SUCCESS it sets
*out_error to NULL (no allocation).

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

# First, find the actual files in the repository
find sdk/runanywhere-commons -type f -name "*.cpp" -o -name "*.h" | grep -E "(llamacpp|llm)" | head -20

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 1449

---

🏁 Script executed:

# Look for C API wrapper files
fd -type f -name "rac_llm*.cpp" sdk/runanywhere-commons/

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 244

---

🏁 Script executed:

# Search for check_lora_compatibility usage
rg -n "check_lora_compat" sdk/runanywhere-commons/

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 2327

---

🏁 Script executed:

# Look at the LlamaCppTextGeneration class definition to find mutex
fd -type f -name "*llamacpp*.h" sdk/runanywhere-commons/ | head -5

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 244

---

🏁 Script executed:

# Examine the C API wrapper function
sed -n '400,440p' sdk/runanywhere-commons/src/backends/llamacpp/rac_llm_llamacpp.cpp

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 1418

---

🏁 Script executed:

# Check the LlamaCppTextGeneration class definition for mutex
cat sdk/runanywhere-commons/src/backends/llamacpp/llamacpp_backend.h

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 5760

---

🏁 Script executed:

# Check other method implementations that access model_ to see locking pattern
rg -n "model_\|mutex" sdk/runanywhere-commons/src/backends/llamacpp/llamacpp_backend.cpp | head -30

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 56

---

🏁 Script executed:

# Get the full implementation of check_lora_compatibility
sed -n '889,939p' sdk/runanywhere-commons/src/backends/llamacpp/llamacpp_backend.cpp

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 1771

---

🏁 Script executed:

# Check load_model and unload_model implementations to see locking pattern
rg -A 15 "bool LlamaCppTextGeneration::load_model\|bool LlamaCppTextGeneration::unload_model" sdk/runanywhere-commons/src/backends/llamacpp/llamacpp_backend.cpp | head -80

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 56

---

🏁 Script executed:

# Check generate method implementation for locking pattern
rg -A 10 "TextGenerationResult LlamaCppTextGeneration::generate" sdk/runanywhere-commons/src/backends/llamacpp/llamacpp_backend.cpp | head -40

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 475

---

🏁 Script executed:

# Check for mutex lock usage in generate and other methods
rg -B 2 -A 10 "std::lock_guard|std::unique_lock" sdk/runanywhere-commons/src/backends/llamacpp/llamacpp_backend.cpp | head -100

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 3089

---

🏁 Script executed:

# Check the complete load_model implementation
sed -n '/^bool LlamaCppTextGeneration::load_model/,/^bool LlamaCpp/p' sdk/runanywhere-commons/src/backends/llamacpp/llamacpp_backend.cpp | head -80

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 3636

---

🏁 Script executed:

# Check all const method implementations that access model_
rg -B 5 -A 15 "bool.*::check_lora_compatibility|is_model_loaded|get_model_info" sdk/runanywhere-commons/src/backends/llamacpp/llamacpp_backend.cpp | head -100

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 1920

---

🏁 Script executed:

# Check line 959 to see what context check_lora_compatibility is called from
sed -n '950,970p' sdk/runanywhere-commons/src/backends/llamacpp/llamacpp_backend.cpp

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 848

---

🏁 Script executed:

# Check is_model_loaded implementation
sed -n '/^bool LlamaCppTextGeneration::is_model_loaded/,/^}/p' sdk/runanywhere-commons/src/backends/llamacpp/llamacpp_backend.cpp

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 156

---

🏁 Script executed:

# Check if get_model_info also lacks locking (saw it doesn't lock either)
sed -n '/^nlohmann::json LlamaCppTextGeneration::get_model_info/,/^}/p' sdk/runanywhere-commons/src/backends/llamacpp/llamacpp_backend.cpp

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 739

---

🏁 Script executed:

# Check the C API wrapper context more thoroughly
sed -n '400,430p' sdk/runanywhere-commons/src/backends/llamacpp/rac_llm_llamacpp.cpp

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 1088

---

🏁 Script executed:

# Check if there's any locking in rac_llm_llamacpp.cpp at all
rg -n "lock_guard|unique_lock|mutex" sdk/runanywhere-commons/src/backends/llamacpp/rac_llm_llamacpp.cpp

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 56

---

🏁 Script executed:

# Check the JNI wrapper
cat sdk/runanywhere-commons/src/jni/runanywhere_commons_jni.cpp | sed -n '1190,1210p'

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 659

---

🏁 Script executed:

# Check if there are other const methods that read model_ and whether they lock
rg -B 3 "model_\|model_loaded_" sdk/runanywhere-commons/src/backends/llamacpp/llamacpp_backend.cpp | grep -E "const.*\{|lock_guard|model_loaded_|model_" | head -40

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 56

---

🏁 Script executed:

# Look at the full structure of rac_llm_llamacpp_handle_impl to understand what text_gen points to
rg -B 5 -A 10 "rac_llm_llamacpp_handle_impl" sdk/runanywhere-commons/src/backends/llamacpp/rac_llm_llamacpp.cpp | head -50

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 1761

---

🏁 Script executed:

# Double-check: verify if the backend mutex in rac_llm_llamacpp_handle_impl is ever used
rg -n "backend.*mutex\|backend->.*lock" sdk/runanywhere-commons/src/backends/llamacpp/rac_llm_llamacpp.cpp

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 56

---

🏁 Script executed:

# Check if any wrappers lock the backend mutex
sed -n '1,100p' sdk/runanywhere-commons/src/backends/llamacpp/rac_llm_llamacpp.cpp | grep -A 5 "rac_llm_llamacpp_create\|extern"

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 369

---

Add mutex locking to check_lora_compatibility() and other const accessors that read model_/model_loaded_.

check_lora_compatibility() reads model_ and model_loaded_ without holding mutex_, creating a race condition with concurrent load_model() and unload_model() calls. The same issue affects is_model_loaded() and get_model_info(). While internal callers like load_lora_adapter() already hold the mutex, the C API wrapper rac_llm_llamacpp_check_lora_compat() has no synchronization mechanism. Wrap these const method bodies with std::lock_guard<std::mutex> lock(mutex_) to prevent use-after-free crashes.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/src/backends/llamacpp/llamacpp_backend.cpp` around
lines 889 - 939, The method check_lora_compatibility reads shared state (model_
and model_loaded_) without synchronization, risking races with
load_model()/unload_model(); similarly is_model_loaded() and get_model_info()
need protection. Fix by adding std::lock_guard<std::mutex> lock(mutex_) at the
start of each of these const methods (check_lora_compatibility, is_model_loaded,
get_model_info) so the body executes while holding mutex_, preventing
use-after-free when the C API wrapper rac_llm_llamacpp_check_lora_compat() is
invoked concurrently.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

# Find all occurrences of checkLoraCompatibility - declaration, implementations, and call sites
rg -n "checkLoraCompatibility" -B 2 -A 2

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 12511

---

🏁 Script executed:

# Find the actual implementations in platform-specific modules
fd -t f "*.kt" | xargs grep -l "actual.*checkLoraCompatibility" | head -20

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 357

---

🏁 Script executed:

# Check the structure of the RunAnywhere+LoRA.kt file to understand context
cat -n sdk/runanywhere-kotlin/src/commonMain/kotlin/com/runanywhere/sdk/public/extensions/RunAnywhere+LoRA.kt | head -100

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 2701

---

Make checkLoraCompatibility a suspend function for consistency with other LoRA functions and to properly indicate blocking I/O.

The function performs GGUF metadata file reading via JNI and uses synchronized(lock) blocking calls. All four other LoRA functions in the same API (loadLoraAdapter, removeLoraAdapter, clearLoraAdapters, getLoadedLoraAdapters) are already suspend. Additionally, both call sites wrap this function in withContext(Dispatchers.IO), confirming it needs async handling even though the operation is relatively lightweight.

Signature update

-expect fun RunAnywhere.checkLoraCompatibility(loraPath: String): LoraCompatibilityResult
+expect suspend fun RunAnywhere.checkLoraCompatibility(loraPath: String): LoraCompatibilityResult

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	* Check if a LoRA adapter file is compatible with the currently loaded model.
	*
	* Reads GGUF metadata from the LoRA file and compares architecture
	* with the loaded model. Does not load the adapter.
	*
	* @param loraPath Path to the LoRA adapter GGUF file
	* @return Compatibility result with isCompatible flag and optional error
	*/
	expect fun RunAnywhere.checkLoraCompatibility(loraPath: String): LoraCompatibilityResult
	* Check if a LoRA adapter file is compatible with the currently loaded model.
	*
	* Reads GGUF metadata from the LoRA file and compares architecture
	* with the loaded model. Does not load the adapter.
	*
	* `@param` loraPath Path to the LoRA adapter GGUF file
	* `@return` Compatibility result with isCompatible flag and optional error
	*/
	expect suspend fun RunAnywhere.checkLoraCompatibility(loraPath: String): LoraCompatibilityResult

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@sdk/runanywhere-kotlin/src/commonMain/kotlin/com/runanywhere/sdk/public/extensions/RunAnywhere`+LoRA.kt
around lines 61 - 69, Make the API function suspend: change the declaration of
checkLoraCompatibility to "suspend fun
RunAnywhere.checkLoraCompatibility(loraPath: String): LoraCompatibilityResult"
and update all platform-specific actual implementations accordingly (the
JVM/native implementations that call JNI and use synchronized(lock)). Update any
callers (or ensure they still wrap with withContext(Dispatchers.IO)) to match
the new suspend signature. Keep the function body logic unchanged (GGUF metadata
read, architecture compare) but mark it suspend so blocking JNI/synchronized
calls are clearly asynchronous.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Sanitize filename to prevent path traversal and enforce .gguf.

filename is used directly in File(destDir, filename), so values like ../foo can escape the lora/ directory and overwrite arbitrary files. Please normalize to a basename and enforce the extension before constructing the paths.

🔒 Proposed fix

-                val destFile = File(destDir, filename)
-                val tempFile = File(destDir, "$filename.tmp")
+                val safeName = File(filename).name
+                val finalName = if (safeName.endsWith(".gguf")) safeName else "$safeName.gguf"
+                val destFile = File(destDir, finalName)
+                val tempFile = File(destDir, "$finalName.tmp")

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	actual fun RunAnywhere.downloadLoraAdapter(url: String, filename: String): Flow<LoraDownloadProgress> =
	callbackFlow {
	trySend(
	LoraDownloadProgress(
	progress = 0f,
	bytesDownloaded = 0,
	totalBytes = null,
	state = LoraDownloadState.PENDING,
	),
	)
	try {
	val destDir = File(CppBridgeModelPaths.getModelsDirectory(), "lora")
	val localPath = withContext(Dispatchers.IO) {
	destDir.mkdirs()
	val destFile = File(destDir, filename)
	val tempFile = File(destDir, "$filename.tmp")
	loraDownloadLogger.info("Downloading LoRA: $url -> ${destFile.absolutePath}")
	val connection = URL(url).openConnection() as HttpURLConnection
	connection.connectTimeout = 30_000
	connection.readTimeout = 60_000
	connection.setRequestProperty("User-Agent", "RunAnywhere-SDK/Kotlin")
	try {
	connection.connect()
	val responseCode = connection.responseCode
	if (responseCode != HttpURLConnection.HTTP_OK) {
	throw Exception("HTTP error: $responseCode")
	}
	val totalBytes = connection.contentLengthLong
	trySend(
	LoraDownloadProgress(
	progress = 0f,
	bytesDownloaded = 0,
	totalBytes = if (totalBytes > 0) totalBytes else null,
	state = LoraDownloadState.DOWNLOADING,
	),
	)
	connection.inputStream.use { input ->
	FileOutputStream(tempFile).use { output ->
	val buffer = ByteArray(8192)
	var bytesDownloaded = 0L
	var lastProgressTime = System.currentTimeMillis()
	var bytesRead: Int
	while (input.read(buffer).also { bytesRead = it } != -1) {
	output.write(buffer, 0, bytesRead)
	bytesDownloaded += bytesRead
	val now = System.currentTimeMillis()
	if (now - lastProgressTime >= 150) {
	lastProgressTime = now
	val progress = if (totalBytes > 0) {
	bytesDownloaded.toFloat() / totalBytes
	} else {
	0f
	}
	trySend(
	LoraDownloadProgress(
	progress = progress,
	bytesDownloaded = bytesDownloaded,
	totalBytes = if (totalBytes > 0) totalBytes else null,
	state = LoraDownloadState.DOWNLOADING,
	),
	)
	}
	}
	}
	}
	// Move temp to final
	if (destFile.exists()) destFile.delete()
	if (!tempFile.renameTo(destFile)) {
	tempFile.copyTo(destFile, overwrite = true)
	tempFile.delete()
	}
	loraDownloadLogger.info("LoRA downloaded: ${destFile.absolutePath} (${destFile.length()} bytes)")
	destFile.absolutePath
	} finally {
	connection.disconnect()
	}
	}
	trySend(
	LoraDownloadProgress(
	progress = 1f,
	bytesDownloaded = File(localPath).length(),
	totalBytes = File(localPath).length(),
	state = LoraDownloadState.COMPLETED,
	localPath = localPath,
	),
	)
	close()
	} catch (e: Exception) {
	loraDownloadLogger.error("LoRA download failed: ${e.message}")
	trySend(
	LoraDownloadProgress(
	progress = 0f,
	bytesDownloaded = 0,
	totalBytes = null,
	state = LoraDownloadState.ERROR,
	error = e.message ?: "Download failed",
	),
	)
	close(e)
	}
	actual fun RunAnywhere.downloadLoraAdapter(url: String, filename: String): Flow<LoraDownloadProgress> =
	callbackFlow {
	trySend(
	LoraDownloadProgress(
	progress = 0f,
	bytesDownloaded = 0,
	totalBytes = null,
	state = LoraDownloadState.PENDING,
	),
	)
	try {
	val destDir = File(CppBridgeModelPaths.getModelsDirectory(), "lora")
	val localPath = withContext(Dispatchers.IO) {
	destDir.mkdirs()
	val safeName = File(filename).name
	val finalName = if (safeName.endsWith(".gguf")) safeName else "$safeName.gguf"
	val destFile = File(destDir, finalName)
	val tempFile = File(destDir, "$finalName.tmp")
	loraDownloadLogger.info("Downloading LoRA: $url -> ${destFile.absolutePath}")
	val connection = URL(url).openConnection() as HttpURLConnection
	connection.connectTimeout = 30_000
	connection.readTimeout = 60_000
	connection.setRequestProperty("User-Agent", "RunAnywhere-SDK/Kotlin")
	try {
	connection.connect()
	val responseCode = connection.responseCode
	if (responseCode != HttpURLConnection.HTTP_OK) {
	throw Exception("HTTP error: $responseCode")
	}
	val totalBytes = connection.contentLengthLong
	trySend(
	LoraDownloadProgress(
	progress = 0f,
	bytesDownloaded = 0,
	totalBytes = if (totalBytes > 0) totalBytes else null,
	state = LoraDownloadState.DOWNLOADING,
	),
	)
	connection.inputStream.use { input ->
	FileOutputStream(tempFile).use { output ->
	val buffer = ByteArray(8192)
	var bytesDownloaded = 0L
	var lastProgressTime = System.currentTimeMillis()
	var bytesRead: Int
	while (input.read(buffer).also { bytesRead = it } != -1) {
	output.write(buffer, 0, bytesRead)
	bytesDownloaded += bytesRead
	val now = System.currentTimeMillis()
	if (now - lastProgressTime >= 150) {
	lastProgressTime = now
	val progress = if (totalBytes > 0) {
	bytesDownloaded.toFloat() / totalBytes
	} else {
	0f
	}
	trySend(
	LoraDownloadProgress(
	progress = progress,
	bytesDownloaded = bytesDownloaded,
	totalBytes = if (totalBytes > 0) totalBytes else null,
	state = LoraDownloadState.DOWNLOADING,
	),
	)
	}
	}
	}
	}
	// Move temp to final
	if (destFile.exists()) destFile.delete()
	if (!tempFile.renameTo(destFile)) {
	tempFile.copyTo(destFile, overwrite = true)
	tempFile.delete()
	}
	loraDownloadLogger.info("LoRA downloaded: ${destFile.absolutePath} (${destFile.length()} bytes)")
	destFile.absolutePath
	} finally {
	connection.disconnect()
	}
	}
	trySend(
	LoraDownloadProgress(
	progress = 1f,
	bytesDownloaded = File(localPath).length(),
	totalBytes = File(localPath).length(),
	state = LoraDownloadState.COMPLETED,
	localPath = localPath,
	),
	)
	close()
	} catch (e: Exception) {
	loraDownloadLogger.error("LoRA download failed: ${e.message}")
	trySend(
	LoraDownloadProgress(
	progress = 0f,
	bytesDownloaded = 0,
	totalBytes = null,
	state = LoraDownloadState.ERROR,
	error = e.message ?: "Download failed",
	),
	)
	close(e)
	}
	}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@sdk/runanywhere-kotlin/src/jvmAndroidMain/kotlin/com/runanywhere/sdk/public/extensions/RunAnywhere`+LoRADownload.jvmAndroid.kt
around lines 26 - 142, The download uses filename directly which allows path
traversal and arbitrary extensions; in RunAnywhere.downloadLoraAdapter sanitize
filename by deriving a safe basename (strip any directory components, reject or
replace path separators), ensure it is non-empty, and enforce the .gguf
extension (append or replace other extensions) before creating destFile and
tempFile; use this safeFilename variable in the File(destDir, safeFilename) and
File(destDir, "$safeFilename.tmp") calls and validate the resulting path stays
under destDir.

[shubhammalhotra28]

are we displaying these anywhere within the Ui so the user knows that these are th set of prompts applied ?

[Siddhesh2377]

Not yet, do u want me to display them ?

[coderabbitai]

Actionable comments posted: 4

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

examples/android/RunAnywhereAI/app/src/main/java/com/runanywhere/runanywhereai/presentation/chat/ChatViewModel.kt (1)

747-813: ⚠️ Potential issue | 🟡 Minor

Avoid hard‑coded model name heuristics for LoRA capability.

isLoraCompatibleModel is derived from nameLower.contains("lfm2") && nameLower.contains("350m"), which risks false negatives/positives as model names evolve. Prefer a capability flag from the SDK, model metadata, or an explicit allowlist in config so LoRA UI isn’t unintentionally hidden.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@examples/android/RunAnywhereAI/app/src/main/java/com/runanywhere/runanywhereai/presentation/chat/ChatViewModel.kt`
around lines 747 - 813, The current heuristic computing isLoraCompatibleModel
(nameLower.contains("lfm2") && nameLower.contains("350m")) is brittle; replace
it with a robust capability check by reading the model's metadata or an
SDK-provided flag (e.g., use RunAnywhere.availableModels() -> model.capabilities
or a hypothetical RunAnywhere.modelSupportsLora(model) call) or fall back to a
configurable allowlist, and update every place that sets isLoraCompatibleModel
(including checkModelStatus, the loaded-model branch using
RunAnywhere.currentLLMModel()/currentLLMModelId, and the chatModel branch) to
call a single helper like isModelLoraCompatible(model) instead of string
matching; ensure loadLoraCatalog() and scanDownloadedAdapters() are only invoked
when that helper returns true.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In
`@examples/android/RunAnywhereAI/app/src/main/java/com/runanywhere/runanywhereai/presentation/models/ModelSelectionBottomSheet.kt`:
- Around line 252-261: The LoRA capability check is using a brittle name-string
heuristic; update the model data and mapping to be data-driven: add a
supportsLora: Boolean property to the ModelInfo type in the SDK (default false)
and populate it from the catalog, then change the conversion in
ModelSelectionBottomSheet.toAIModel (where AIModel(...) is constructed from m)
to set isDownloaded as before but set supportsLora = m.supportsLora (or, if you
need a transitional fallback, check m.id against a maintained Set of
knownLoRACompatibleIds instead of using nameLower.contains(...)). Ensure
references: ModelInfo, toAIModel, AIModel, ModelSelectionBottomSheet, and
supportsLora are updated accordingly.

In `@sdk/runanywhere-commons/src/backends/llamacpp/rac_llm_llamacpp.cpp`:
- Around line 409-447: Both functions rac_llm_llamacpp_check_lora_compat and
rac_llm_llamacpp_read_gguf_info currently return allocated raw C strings via
char**/strdup which violates the API guideline; change their signatures and
implementations to use the project’s structured string/buffer type (the
library-wide string/buffer wrapper used for other C APIs), e.g., replace char**
out_error and char** out_json with that structured output type, populate the
structured object with the error or JSON payload and its length (do not call
strdup), and return appropriate rac_result_t/RAC_TRUE/RAC_FALSE values; update
uses of h->text_gen->check_lora_compatibility and
runanywhere::LlamaCppTextGeneration::read_gguf_metadata to fill the structured
buffer and use rac_error_set_details only for setting error metadata, ensuring
ownership and lifecycle are explicit and callers receive the structured buffer
API instead of raw strings.

In
`@sdk/runanywhere-kotlin/src/commonMain/kotlin/com/runanywhere/sdk/public/extensions/RunAnywhere`+LoRADownload.kt:
- Around line 12-13: Public APIs availableLoraAdapters() and
downloadLoraFromCatalog() currently expose
com.runanywhere.sdk.temp.LoraAdapterEntry and LoraAdapterCatalog; move these
types out of the temp package into a stable package (e.g.,
com.runanywhere.sdk.public.extensions), update their package declarations and
all imports/references (including the signatures of availableLoraAdapters and
downloadLoraFromCatalog) to the new package, and update any module/export
configuration and docs to expose the new stable package instead of
com.runanywhere.sdk.temp so consumers no longer depend on the temporary package.

In
`@sdk/runanywhere-kotlin/src/jvmAndroidMain/kotlin/com/runanywhere/sdk/public/extensions/RunAnywhere`+LoRADownload.jvmAndroid.kt:
- Around line 79-141: The catch-all exception handler currently swallows
CancellationException and must rethrow it, and the blocking IO loop around
input.read(buffer) must be made cancellation-cooperative. Change the catch block
that reads "catch (e: Exception)" to rethrow if (e is CancellationException) and
only handle/log non-cancellation errors (so the LoraDownloadState.ERROR send and
log are skipped on cancellation). Replace the direct blocking input.read(buffer)
loop (the code that runs inside withContext(Dispatchers.IO) and calls
input.read(buffer).also { bytesRead = it }) with a cancellation-aware read:
perform the blocking read inside a suspendCancellableCoroutine (or otherwise
arrange a background IO task) and register invokeOnCancellation to close the
connection/input stream so the blocking read is interrupted; after each
successful read check coroutineContext.isActive/ensureActive and then emit
progress via trySend as before. Use the existing symbols input.read(buffer),
withContext(Dispatchers.IO), trySend(LoraDownloadProgress...), and the catch
block around the download to locate and implement these changes.

---

Outside diff comments:
In
`@examples/android/RunAnywhereAI/app/src/main/java/com/runanywhere/runanywhereai/presentation/chat/ChatViewModel.kt`:
- Around line 747-813: The current heuristic computing isLoraCompatibleModel
(nameLower.contains("lfm2") && nameLower.contains("350m")) is brittle; replace
it with a robust capability check by reading the model's metadata or an
SDK-provided flag (e.g., use RunAnywhere.availableModels() -> model.capabilities
or a hypothetical RunAnywhere.modelSupportsLora(model) call) or fall back to a
configurable allowlist, and update every place that sets isLoraCompatibleModel
(including checkModelStatus, the loaded-model branch using
RunAnywhere.currentLLMModel()/currentLLMModelId, and the chatModel branch) to
call a single helper like isModelLoraCompatible(model) instead of string
matching; ensure loadLoraCatalog() and scanDownloadedAdapters() are only invoked
when that helper returns true.

---

Duplicate comments:
In @.idea/vcs.xml:
- Around line 5-16: The .idea/vcs.xml contains machine-local VCS mappings for
CMake _deps and local emsdk that should be removed; edit .idea/vcs.xml to delete
the specific <mapping> entries that reference directories containing "_deps/"
(e.g., any mapping with paths like "build/.../_deps/llamacpp-src",
"_deps/nlohmann_json-src", "_deps/stable_diffusion_cpp-src", "ggml",
"whispercpp-src") and the "sdk/runanywhere-web/emsdk" mapping, leaving only the
root <mapping directory=""/> entry; additionally, ensure .idea/vcs.xml is
ignored (add .idea/vcs.xml to .gitignore or remove any negation rule like
"!.idea/vcs.xml") so these IDE-specific mappings aren’t committed again.

In `@docs/impl/lora_adapter_support.md`:
- Around line 720-749: Add proper fenced-code block language markers and correct
the typo "cal"→"call": update the first block that documents the compatibility
check (the one starting with "1. Kotlin calls
RunAnywhere.checkLoraCompatibility(path)" and the block describing the download
flow that starts with "1. RunAnywhere.downloadLoraAdapter(url, filename) returns
Flow<LoraDownloadProgress") to use explicit language tags (e.g., ```text or
```markdown) for both fenced blocks, and change the sentence "safe to cal
repeatedly" to "safe to call repeatedly"; apply the same fenced-block language
fix to the other occurrence of the download block later in the file (the second
RunAnywhere.downloadLoraAdapter block).

In `@sdk/runanywhere-commons/include/rac/features/llm/rac_llm_component.h`:
- Around line 266-280: Update the doc comment for
rac_llm_component_check_lora_compat to explicitly list possible returned
rac_result_t error codes (e.g., RAC_SUCCESS, RAC_ERROR_INVALID_ARGUMENT,
RAC_ERROR_INCOMPATIBLE_ARCH, RAC_ERROR_IO, etc.), describe required
vtable/component operations that must be present or initialized before calling
(reference the component handle / vtable methods used by
rac_llm_component_check_lora_compat), and state lifecycle prerequisites (e.g.,
model must be loaded, component initialized, and ownership/validity of lora_path
and out_error). Also mention that out_error, when non-NULL, must be freed with
rac_free (already referenced) and clarify caller vs callee responsibility for
allocation and error string semantics.

In `@sdk/runanywhere-commons/src/backends/llamacpp/llamacpp_backend.cpp`:
- Around line 889-939: check_lora_compatibility reads model_loaded_ and model_
without synchronization and can race with load_model()/unload_model(); fix by
acquiring the backend/model mutex at the start of check_lora_compatibility
(e.g., add std::lock_guard<std::mutex> lock(model_mutex_); or the existing mutex
that load_model()/unload_model() use) so all accesses to model_loaded_ and
model_ inside this method are protected until the function returns.

In
`@sdk/runanywhere-kotlin/src/commonMain/kotlin/com/runanywhere/sdk/public/extensions/RunAnywhere`+LoRA.kt:
- Around line 59-69: The declaration for checkLoraCompatibility should be made
suspend like the other LoRA APIs: change expect fun
RunAnywhere.checkLoraCompatibility(loraPath: String): LoraCompatibilityResult to
expect suspend fun RunAnywhere.checkLoraCompatibility(loraPath: String):
LoraCompatibilityResult, and update the JVM/Android actual implementation (the
actual in RunAnywhere+LoRA.jvmAndroid.kt) to wrap the blocking JNI call
(CppBridgeLLM.checkLoraCompatibility) inside withContext(Dispatchers.IO) so the
GGUF metadata I/O runs on the IO dispatcher and returns a
LoraCompatibilityResult.

In
`@sdk/runanywhere-kotlin/src/jvmAndroidMain/kotlin/com/runanywhere/sdk/public/extensions/RunAnywhere`+LoRA.jvmAndroid.kt:
- Around line 85-96: Change the synchronous actual implementation of
RunAnywhere.checkLoraCompatibility to match the expect declaration by making it
suspend and offloading the blocking JNI/file IO to a background dispatcher;
update the expect declaration in RunAnywhere+LoRA.kt first if it’s still
non-suspending, then implement the actual function (in
RunAnywhere+LoRA.jvmAndroid.kt) as suspend and call
CppBridgeLLM.checkLoraCompatibility inside a withContext(Dispatchers.IO) (or
equivalent coroutine dispatcher) before returning the LoraCompatibilityResult so
the JNI call and GGUF file reads do not block the caller thread.

In
`@sdk/runanywhere-kotlin/src/jvmAndroidMain/kotlin/com/runanywhere/sdk/public/extensions/RunAnywhere`+LoRADownload.jvmAndroid.kt:
- Around line 43-44: The code uses the raw filename to build destFile and
tempFile (val destFile = File(destDir, filename) and val tempFile =
File(destDir, "$filename.tmp"), leaving the code vulnerable to path traversal;
sanitize and normalize the incoming filename before constructing files by
extracting only the base name (reject or strip any directory components and path
separators), validate it does not equal "." or ".." and does not contain
separators or null bytes, and then use that safeName when creating
destFile/tempFile (also resolve and validate the resulting File is within
destDir via canonical path checks) to prevent escaping the intended target
directory.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

LoRA capability determined by hardcoded name-string heuristic — will silently miss future models.

nameLower.contains("lfm2") && nameLower.contains("350m") matches only one specific model variant. Any new LoRA-compatible model added to the catalog, or a model rename, will silently produce no badge. The capability flag should be data-driven — either a supportsLora: Boolean field on ModelInfo populated by the SDK/catalog, or a set of known-compatible model IDs. As per coding guidelines, structured types should be used instead of ad-hoc string checks.

♻️ Suggested direction

In ModelInfo, expose:

// In sdk/runanywhere-kotlin commonMain
val supportsLora: Boolean = false

Then in toAIModel:

-    val nameLower = m.name.lowercase()
     return AIModel(
         ...
-        supportsLora = nameLower.contains("lfm2") && nameLower.contains("350m"),
+        supportsLora = m.supportsLora,
     )

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@examples/android/RunAnywhereAI/app/src/main/java/com/runanywhere/runanywhereai/presentation/models/ModelSelectionBottomSheet.kt`
around lines 252 - 261, The LoRA capability check is using a brittle name-string
heuristic; update the model data and mapping to be data-driven: add a
supportsLora: Boolean property to the ModelInfo type in the SDK (default false)
and populate it from the catalog, then change the conversion in
ModelSelectionBottomSheet.toAIModel (where AIModel(...) is constructed from m)
to set isDownloaded as before but set supportsLora = m.supportsLora (or, if you
need a transitional fallback, check m.id against a maintained Set of
knownLoRACompatibleIds instead of using nameLower.contains(...)). Ensure
references: ModelInfo, toAIModel, AIModel, ModelSelectionBottomSheet, and
supportsLora are updated accordingly.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Use structured return types instead of raw C strings.

These new C API functions expose char** outputs and allocate via strdup, which violates the repo requirement to avoid raw strings in commons C/C++ APIs. Please switch to the project’s structured string/buffer type (or introduce one) so ownership, length, and lifecycle are explicit.
As per coding guidelines: “Always use structured types, never use strings directly for consistency and scalability”.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/src/backends/llamacpp/rac_llm_llamacpp.cpp` around
lines 409 - 447, Both functions rac_llm_llamacpp_check_lora_compat and
rac_llm_llamacpp_read_gguf_info currently return allocated raw C strings via
char**/strdup which violates the API guideline; change their signatures and
implementations to use the project’s structured string/buffer type (the
library-wide string/buffer wrapper used for other C APIs), e.g., replace char**
out_error and char** out_json with that structured output type, populate the
structured object with the error or JSON payload and its length (do not call
strdup), and return appropriate rac_result_t/RAC_TRUE/RAC_FALSE values; update
uses of h->text_gen->check_lora_compatibility and
runanywhere::LlamaCppTextGeneration::read_gguf_metadata to fill the structured
buffer and use rac_error_set_details only for setting error metadata, ensuring
ownership and lifecycle are explicit and callers receive the structured buffer
API instead of raw strings.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Public API surface depends on temp package types.

LoraAdapterEntry from com.runanywhere.sdk.temp appears in two public function signatures (availableLoraAdapters() and downloadLoraFromCatalog()). Once this ships as part of the SDK, consumers depend on com.runanywhere.sdk.temp.LoraAdapterEntry, making the temp package sticky regardless of its intended temporary status. The type and its catalog should be promoted to a stable package (e.g., com.runanywhere.sdk.public.extensions) before this API is released.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@sdk/runanywhere-kotlin/src/commonMain/kotlin/com/runanywhere/sdk/public/extensions/RunAnywhere`+LoRADownload.kt
around lines 12 - 13, Public APIs availableLoraAdapters() and
downloadLoraFromCatalog() currently expose
com.runanywhere.sdk.temp.LoraAdapterEntry and LoraAdapterCatalog; move these
types out of the temp package into a stable package (e.g.,
com.runanywhere.sdk.public.extensions), update their package declarations and
all imports/references (including the signatures of availableLoraAdapters and
downloadLoraFromCatalog) to the new package, and update any module/export
configuration and docs to expose the new stable package instead of
com.runanywhere.sdk.temp so consumers no longer depend on the temporary package.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

CancellationException swallowed, and IO loop is not cancellation-cooperative.

Two related issues:

1. Swallowed cancellation (lines 130–141): CancellationException is a subtype of Exception. When the flow collector cancels, withContext(Dispatchers.IO) throws CancellationException, which is caught here, emitting a spurious ERROR state and logging a false "LoRA download failed" error. As a rule of thumb, CancellationException should always be rethrown, even if all other exceptions are caught.

2. Non-cooperative IO loop (lines 79–101): The while loop performs blocking Java IO with no isActive guard. When the coroutine is cancelled, the coroutine continues running until it reaches a suspension point where the suspending function checks whether it has been canceled. Because input.read(buffer) is a plain blocking call with no suspension points, the download thread continues consuming network resources until the 60-second read timeout fires.

🐛 Proposed fix

                             while (input.read(buffer).also { bytesRead = it } != -1) {
+                                if (!isActive) break
                                 output.write(buffer, 0, bytesRead)

+        } catch (e: CancellationException) {
+            throw e  // propagate cancellation; don't treat it as a download failure
         } catch (e: Exception) {
             loraDownloadLogger.error("LoRA download failed: ${e.message}")

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@sdk/runanywhere-kotlin/src/jvmAndroidMain/kotlin/com/runanywhere/sdk/public/extensions/RunAnywhere`+LoRADownload.jvmAndroid.kt
around lines 79 - 141, The catch-all exception handler currently swallows
CancellationException and must rethrow it, and the blocking IO loop around
input.read(buffer) must be made cancellation-cooperative. Change the catch block
that reads "catch (e: Exception)" to rethrow if (e is CancellationException) and
only handle/log non-cancellation errors (so the LoraDownloadState.ERROR send and
log are skipped on cancellation). Replace the direct blocking input.read(buffer)
loop (the code that runs inside withContext(Dispatchers.IO) and calls
input.read(buffer).also { bytesRead = it }) with a cancellation-aware read:
perform the blocking read inside a suspendCancellableCoroutine (or otherwise
arrange a background IO task) and register invokeOnCancellation to close the
connection/input stream so the blocking read is interrupted; after each
successful read check coroutineContext.isActive/ensureActive and then emit
progress via trySend as before. Use the existing symbols input.read(buffer),
withContext(Dispatchers.IO), trySend(LoraDownloadProgress...), and the catch
block around the download to locate and implement these changes.

To fix the problem, add an explicit permissions block that restricts the GITHUB_TOKEN to the minimum needed. This workflow performs read-only operations on the repository (checkout) and writes only to the step summary, which does not require elevated token scopes. Therefore contents: read at the workflow or job level is sufficient and aligns with the CodeQL recommendation.

The best targeted fix without changing existing functionality is to define permissions at the workflow root, just after name: and before on:. This will apply to the single publish job and any future jobs unless they override permissions. Concretely, in .github/workflows/publish-maven-central.yml, insert:

permissions:
  contents: read

below the existing name: Publish to Maven Central line. No additional imports, methods, or definitions are required because this is a configuration-only change to the GitHub Actions workflow.

In general, fix this by adding an explicit permissions section that grants only the minimal required permissions for the workflow. Since all the jobs here only read repository contents and upload artifacts (which does not require repository write permissions), contents: read at the workflow root is sufficient and will apply to all jobs.

Best concrete fix without changing existing functionality:

• Edit .github/workflows/web-sdk-release.yml.
• At the top workflow level (alongside name: and on:), add:

  permissions:
    contents: read

• This leaves all job logic intact, but ensures the GITHUB_TOKEN is restricted to read-only repository contents for all jobs in this workflow.

No imports, methods, or additional definitions are needed because this is a YAML configuration change only.

In general, the problem is fixed by explicitly specifying permissions for the GITHUB_TOKEN either at the top level of the workflow (so it applies to all jobs) or on individual jobs, and setting them to the minimum needed. For this workflow, the jobs only check out code, set up tools, build, and upload artifacts. Those operations only require read access to repository contents; they do not push commits, create releases, or modify issues/PRs. Therefore, contents: read is sufficient as a baseline.

The single best fix without changing existing functionality is to add a root-level permissions block after the on: section and before the jobs: section in .github/workflows/web-sdk-release.yml:

permissions:
  contents: read

This will apply to all three jobs (typecheck, build-wasm, and build-ts) because none of them currently declares its own permissions block. No imports or additional definitions are needed; this is purely a declarative change to the workflow YAML. No changes within the job bodies are required.

To fix the problem, explicitly restrict the GITHUB_TOKEN permissions used by this workflow to the minimum required. All jobs in this workflow only need to read repository contents (for actions/checkout) and upload artifacts, which does not require repository write scopes. The simplest and safest fix is to define a top-level permissions block setting contents: read. This applies to all jobs (typecheck, build-wasm, and build-ts) since none of them currently override permissions.

Concretely, in .github/workflows/web-sdk-release.yml, add a permissions: section near the top of the file (after the name: line and before on:) with contents: read. No additional imports or other code changes are needed, and existing functionality will remain the same except that the GITHUB_TOKEN will no longer have excess privileges if the repository default is read-write.

In general, substring checks on the full URL string should be replaced with checks on parsed URL components, typically hostname or origin, and they should be compared against a whitelist of allowed hosts or patterns. For YouTube, we want to identify when the current page is genuinely on a YouTube domain (e.g., youtube.com or regional/WWW subdomains like www.youtube.com, m.youtube.com, www.youtube.co.uk, etc.), not when youtube.com appears anywhere in the URL.

The best fix here is to parse the url string using the standard URL constructor (available in modern JS/TS runtimes) into an object, then create a small helper to decide “is this a YouTube URL?” by inspecting hostname. We then replace the existing if (url.includes('youtube.com')) with a call to this helper. Inside the same YouTube block, the checks for paths like /results and /watch can safely remain as substring checks on the path portion of the parsed URL (pathname and possibly search) instead of the entire string. This avoids false positives where youtube.com appears in query or path segments of non‑YouTube hosts.

Concretely, within navigator-agent.ts:

• Add a small helper function (e.g., isYouTubeUrl(url: string): boolean) near the top or as a private method of the class (depending on context) that:
  • Wraps new URL(url) in a try/catch; on error, returns false.
  • Normalizes hostname to lowercase.
  • Returns true if hostname === 'youtube.com' or hostname.endsWith('.youtube.com'). Optionally, we can also consider hostname === 'youtu.be' if desired, but the current behavior only checks for 'youtube.com', so we will keep behavior focused on YouTube domains, but more precise.
• In the YouTube rules section, change if (url.includes('youtube.com')) to use this helper.
• Additionally, we can parse the URL once in that block to derive pathname and search and use them instead of url.includes('/results'), etc., to avoid edge cases; that keeps functionality the same but more robust and does not require changes elsewhere.

No new external library is needed; the built-in URL is sufficient.

In general, the problem should be fixed by parsing the URL and making decisions based on its structured components (like hostname and pathname) instead of using substring checks on the raw URL string. For host checks, we should either exactly match a whitelist of allowed hostnames (e.g., www.google.com, www.google.co.uk, etc.) or, if appropriate, match well-defined suffixes in the hostname (e.g., hostname === 'google.com' or hostname.endsWith('.google.com')). This prevents arbitrary hosts from passing the check just because they contain "google.com" somewhere else in the URL.

For this specific code, the minimal, behavior-preserving change is to replace if (url.includes('google.com')) with a hostname-based check. Since this is a TypeScript project and we cannot assume surrounding code, the best approach is to use the standard URL class available in modern JavaScript/TypeScript runtimes. We will attempt to construct a URL from the url string and, if that fails (invalid URL), we simply treat it as not matching Google. Once parsed, we will inspect parsed.hostname and check whether it is equal to google.com or ends with .google.com. This keeps the original intent (“is this a Google page?”) but avoids incorrect matches like https://evil-google.com or https://google.com.attacker.net.

Concretely, within navigator-agent.ts in the block starting at line 221, we will:

• Introduce a small, localized parsing block before the Google rules:
  • Try to create new URL(url) inside a try/catch.
  • Derive a boolean isGoogleHost from parsed.hostname === 'google.com' || parsed.hostname.endsWith('.google.com').
• Replace if (url.includes('google.com')) { with if (isGoogleHost) {.
• Keep the inner logic (checking url.includes('/search'), etc.) unchanged to avoid altering behavior beyond the host identification.

This requires no new imports or external dependencies; URL is standard.

---

In general, the fix is to stop treating the entire URL as an opaque string when deciding whether it belongs to YouTube. Instead, parse the URL and check its hostname (and possibly protocol) against a whitelist or at least a strict pattern that correctly handles subdomains (e.g., www.youtube.com, m.youtube.com). That avoids misclassifying URLs where youtube.com only appears in the path, query, or as part of a different domain.

For this file, the safest, minimal-change approach is:

• Use the standard URL class to parse the URL string inside canHandle and getState.
• Extract hostname and check if it is exactly youtube.com or ends with .youtube.com. This preserves support for subdomains such as www.youtube.com and region-specific hosts like music.youtube.com, but rejects youtube.com.evil.com.
• Handle invalid or relative URLs gracefully by catching exceptions or falling back to conservative behavior (e.g., treat as non‑YouTube).

Concretely:

• In canHandle(url, task), replace url.includes('youtube.com') with a small helper that:
  • Tries to construct new URL(url).
  • Returns true if the hostname is youtube.com or ends with .youtube.com, false otherwise.
• In getState(dom, history), where const url = dom.url || '', use the same helper to decide whether “Not on YouTube yet” instead of !url.includes('youtube.com').
• Implement this helper as a private method on YouTubeStateMachine (e.g., private isYouTubeUrl(rawUrl: string): boolean) so both methods share the same logic.
• No new imports are needed; URL is available in modern browser and Node runtimes. If the environment might not support URL globally, the project would need a polyfill, but we won’t edit anything outside this file.

In general, the fix is to stop checking for youtube.com as a substring of the entire URL, and instead parse the URL and verify that its hostname is either youtube.com or a recognized subdomain (such as www.youtube.com, m.youtube.com, etc.). This avoids accidentally matching occurrences in the path, query string, or in attacker‑controlled hostnames such as evil-youtube.com.

The best way to fix this without changing existing functionality is:

• Introduce a small helper inside YouTubeStateMachine that, given a URL string, safely parses it (using the standard URL constructor) and checks the hostname against an explicit allowlist or suffix match.
• Replace the substring checks url.includes('youtube.com') in both canHandle (line 36) and getState (line 55) with calls to this helper, such as this.isYouTubeUrl(url).

Implementation details for Playground/on-device-browser-agent/src/background/agents/state-machines/youtube.ts:

1. Add a private method inside YouTubeStateMachine (e.g., just below private searchQuery: string = '';):

   private isYouTubeUrl(url: string): boolean {
     try {
       const parsed = new URL(url);
       const hostname = parsed.hostname.toLowerCase();
       return (
         hostname === 'youtube.com' ||
         hostname.endsWith('.youtube.com')
       );
     } catch {
       // If URL constructor throws (e.g., relative URL), fall back to simple checks
       const lower = url.toLowerCase();
       return lower.startsWith('https://youtube.com') ||
              lower.startsWith('http://youtube.com') ||
              lower.includes('://www.youtube.com') ||
              lower.includes('://m.youtube.com');
     }
   }

   This keeps behavior broadly similar (recognizing main and common subdomains) while being much safer about host checks.

2. In canHandle, line 36, change url.includes('youtube.com') to this.isYouTubeUrl(url).

3. In getState, line 55, change the negated YouTube check from if (!url.includes('youtube.com')) to if (!this.isYouTubeUrl(url)).

No additional imports are needed because URL is available in modern TypeScript/JavaScript runtimes that support the DOM or standard web APIs, which is consistent with code that already works with browser DOM state.

In general, the problem should be fixed by making the URL scheme validation comprehensive: when deciding whether to auto-navigate to an href, reject not just javascript: but also other executable schemes such as data: and vbscript:. Ideally, this is done by normalizing the URL (trimming whitespace, lowercasing the scheme part) and checking it against a denylist, or conversely, by only allowing a safe list like http:, https:, and mailto:. To minimize behavioral change, we should keep the current logic and just expand the disallowed schemes.

For this specific file, the best minimal change is to adjust the condition on line 261 so that it refuses to navigate when el.href starts with any of the dangerous schemes. Because el.href is a fully resolved URL string and startsWith is case-sensitive, we should normalize case via toLowerCase() before checking; this avoids breaking existing behavior where a site might use JavaScript: or mixed-case schemes. We can do that inline in the condition by deriving a lowercase version of el.href and checking it against "javascript:", "data:", and "vbscript:". No new imports or helper methods are required; a one-line change to the if condition is sufficient.

Concretely, in Playground/on-device-browser-agent/src/content/action-executor.ts, locate the if (el instanceof HTMLAnchorElement && el.href && !el.href.startsWith('javascript:')) { block and replace the !el.href.startsWith('javascript:') part with a more complete check that lowercases the href and rejects any of the three schemes.

To fix this, we should ensure that any untrusted text (message passed to showToast) is not interpreted as HTML. Instead of interpolating message directly into a string assigned to innerHTML, we should build the DOM tree explicitly: keep the SVG icon as HTML (trusted, static) and attach the user-controlled message as textContent of a <span>. This preserves existing visuals and behavior while preventing injected HTML from being executed.

Concretely, in examples/web/RunAnywhereAI/src/components/dialogs.ts, in showToast, replace:

toast.innerHTML = `${TOAST_ICONS[variant]}<span>${message}</span>`;

with code that:

1. Sets the icon using innerHTML from the trusted TOAST_ICONS string.
2. Creates a span element.
3. Sets span.textContent = message;.
4. Appends the span to the toast.

Because we are only manipulating DOM APIs already in use (createElement, appendChild) we do not need any new imports or dependencies. No changes are required to storage.ts; its use of showToast remains the same, but the sink is now safe.

In general, the problem is that showConfirmDialog accepts a plain message string and interpolates it directly into innerHTML, and callers compose that message string using potentially tainted values plus HTML markup. To fix this without changing visible behavior, we should either: (a) make showConfirmDialog build the DOM using textContent for all dynamic pieces (and non-string attributes for buttons), or (b) ensure that any dynamic parts included in the message string are HTML-escaped before interpolation. Since we already have a use case that needs <strong> styling, the best robust approach is to restructure showConfirmDialog to create DOM nodes programmatically and only allow a simple, well-defined subset of markup, or to pass the untrusted data separately and inject it as textContent into the appropriate places.

The minimal, clean fix within the shown snippets is: introduce a small escapeHtml helper in examples/web/RunAnywhereAI/src/components/dialogs.ts and use it to escape the interpolated message (and title, confirmLabel, cancelLabel) before assigning to backdrop.innerHTML, and separately escape any untrusted portions before including them in the message string in storage.ts. In storage.ts, we can reuse the already-defined escapeHtml to sanitize modelName both when constructing the confirmation message and when passing modelName to showToast. Because the confirmation message uses <strong>...</strong>, we can preserve that markup by only escaping the interpolated modelName, not the whole message, like: `Remove <strong>${escapeHtml(modelName)}</strong> ...`. In dialogs.ts, escaping message before embedding it will double-escape <strong> from trusted callers, so instead we should only escape title, confirmLabel, and cancelLabel, and treat message as already-encoded HTML from the caller; then in our tainted call site we ensure modelName is escaped inside that HTML. That keeps existing rich-text capability while ensuring tainted data is encoded before reaching innerHTML.

Concretely:

• In examples/web/RunAnywhereAI/src/views/storage.ts, update the modelName usages:
  • At line 280, change the message argument to escape modelName via the existing escapeHtml helper.
  • At line 288, also escape modelName before passing it to showToast, since showToast uses innerHTML.
• In examples/web/RunAnywhereAI/src/components/dialogs.ts, harden showConfirmDialog by HTML-escaping title, confirmLabel, and cancelLabel when building backdrop.innerHTML, using a new local escapeHtml helper. Leave message as-is to allow the caller to provide limited markup, and rely on the caller (storage.ts) to escape any untrusted fragments before composing the message string.

No behavior visible to users changes other than preventing HTML injection through modelName and other parameters that might be untrusted.

In general terms, the problem comes from constructing a large HTML string with innerHTML that directly interpolates untrusted values (${settings.apiKey}, ${settings.baseURL}). To fix this, we should avoid interpreting those values as HTML by either (1) escaping/encoding them before inserting into the string, or (2) building the DOM with document.createElement / property assignment and setting input values via .value rather than HTML text. Given the existing code, the smallest non-breaking change is to remove the interpolation of these untrusted values from the template literal and instead set them after the DOM is created via .value assignments, which are not parsed as HTML.

Concretely:

• In initSettingsTab, change the container.innerHTML template so that the value attributes for #settings-api-key and #settings-base-url are empty (no ${settings.*} interpolation).
• Right after the DOM has been created and the inputs queried (apiKeyInput and baseURLInput), explicitly assign their .value from settings.apiKey and settings.baseURL. This ensures those values are inserted as plain text properties, not re-parsed HTML.
• Leave loadSettings as-is, since it already uses .value assignments and does not rely on initial value="..." attributes.

All of these changes are in examples/web/RunAnywhereAI/src/views/settings.ts. No new imports or helper methods are needed.

In general, the problem is that the sensitive apiKey is being stored in cleartext inside localStorage as part of the serialized settings object. To fix this, we should avoid persisting the API key alongside non-sensitive settings, and instead keep it only in memory or, if persistence is truly required, store an encrypted form or use a more secure mechanism. Given the constraints and the code shown, the most straightforward and least invasive fix is: (1) stop persisting apiKey to localStorage, and (2) stop restoring it from localStorage. This preserves all existing non-sensitive functionality while removing the insecure cleartext storage.

Concretely, in saveSettings, before serializing and writing to localStorage, we can construct a shallow copy of settings with apiKey removed (or explicitly set to an empty string) and serialize that copy instead of the original settings object. This ensures the in-memory settings.apiKey still works for current usage, but it is not written to disk. In loadSettings, after parsing the saved JSON, we should explicitly ignore any stored apiKey value (in case older data exists) and avoid populating either settings.apiKey or the #settings-api-key input with data from storage. This means users will need to re-enter their API key on each reload, which is the secure behavior implied by the recommendation to avoid cleartext storage. No external libraries are needed; we only adjust object copying and assignment logic in saveSettings and loadSettings, and remove the UI update that injects a stored key into the input field.

---

In general, to fix this class of vulnerability, any string that may contain user-controlled or otherwise untrusted content must not be written directly into the DOM using innerHTML (or similar APIs) unless it is properly escaped for the HTML context. Instead, either (a) use text-only setters like textContent, or (b) sanitize/escape the content before inserting as HTML.

Here, the best fix is to refactor showErrorView in examples/web/RunAnywhereAI/src/main.ts so that the DOM structure is still built via innerHTML for the static HTML fragment, but the dynamic message value is inserted as text via textContent. Specifically:

• Change the app.innerHTML = \...`block so that the

  has no${message}interpolation and instead includes an empty

  with the same classes and perhaps anid` or data attribute.

• After setting innerHTML, query that <p> element and set its textContent = message.
• Keep the rest of the structure and behavior (including the retry button and event listener) unchanged.

No new external libraries are required; we only use standard DOM APIs.