Merge branch 'stage' into bugfix/ADFA-6199-kotlin-indexer-analysis-failures

Author: hal-eisen-adfa

.github/workflows/spotless-apply.yml

@@ -0,0 +1,73 @@
+name: Spotless apply
+
+# For contributors without a shell (e.g. editing in the GitHub web UI): runs spotlessApply on a
+# branch and appends the result as a standalone commit. The push uses GITHUB_TOKEN, so it does not
+# start other workflows.
+
+permissions:
+  contents: write
+
+on:
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: 'Branch to format (not stage or main)'
+        required: true
+        type: string
+
+concurrency:
+  group: spotless-apply-${{ inputs.branch }}
+  cancel-in-progress: false
+
+jobs:
+  spotless_apply:
+    name: Run spotlessApply and commit
+    runs-on: self-hosted
+    timeout-minutes: 30
+    env:
+      BRANCH: ${{ inputs.branch }}
+
+    steps:
+      - name: Refuse protected branches
+        run: |
+          case "$BRANCH" in
+            stage|main)
+              echo "::error::Refusing to push to '$BRANCH'."
+              exit 1
+              ;;
+          esac
+
+      # fetch-depth 0: the Spotless ratchet compares against origin/stage.
+      - name: Checkout branch
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.branch }}
+          fetch-depth: 0
+
+      - name: Check if Nix is installed
+        run: |
+          if command -v nix >/dev/null 2>&1; then
+            echo "nix_installed=true" >> $GITHUB_ENV
+          else
+            echo "nix_installed=false" >> $GITHUB_ENV
+          fi
+
+      - name: Install Flox
+        if: env.nix_installed == 'false'
+        uses: flox/install-flox-action@v2
+
+      - name: Run spotlessApply
+        run: |
+          flox activate -d flox/base -- ./gradlew spotlessApply --no-daemon
+
+      - name: Commit and push
+        run: |
+          if git diff --quiet; then
+            echo "::notice::Already formatted. Nothing to commit."
+            exit 0
+          fi
+          git config user.name "ADFA"
+          git config user.email "dev-team@appdevforall.org"
+          git commit -am "style: spotless reformat, no functional change"
+          git push origin "HEAD:refs/heads/$BRANCH"
+          echo "::notice::Pushed $(git rev-parse --short HEAD) to $BRANCH."

app/proguard-rules.pro

@@ -256,6 +256,7 @@
 -keep class com.google.android.material.** { *; }
 -keep class io.noties.markwon.** { *; }
 -keep class com.google.gson.** { *; }
+-keep class org.snakeyaml.engine.** { *; }
 
 -keep class com.google.firebase.** { *; }
 -keep class com.google.android.gms.** { *; }

docs/PLUGIN_API_CHANGELOG.md

@@ -35,7 +35,41 @@ need a source change, a recompile, or both · `tooling` = API-stability
 milestone. **[verified]** = read from the checked-in ABI dump. **[reconstructed]**
 = diffed from `plugin-api/src` history (predates the dump; symbol-accurate).
 
-### 26.40 — unreleased
+### 26.41 — unreleased
+- **added — The AI prompt config engine and settings-pane helpers** _(ADFA-6281)_ **[verified]**
+  Every AI plugin carried its own copy of the code that reads and renders its prompt
+  config, and the credential screens their own copy of the reveal toggle and pane
+  styling, so a fix had to be repeated per plugin and a missed copy made the plugins
+  drift. The host now ships one copy.
+  `com.itsaky.androidide.plugins.ai.prompt`: `PromptTemplateEngine` and `PromptText`
+  (the `{{NAME}}` / `{{#NAME}}` / `{{^NAME}}` renderer; names may be in any case and hold
+  dots, e.g. `{{fileName}}` or `{{item.name}}`, `{{{{` writes a literal `{{`, and config text keeps its whitespace as YAML
+  parsed it); `PromptConfigLoader.load(source,
+  parser)`, which reads `agent.yml` and its `include` list off the main thread;
+  `PromptConfigDocument` and `PromptConfigObject`, the strict key-by-key reader a parser
+  maps the merged YAML through; `PromptConfigSource` / `AssetPromptConfigSource`;
+  `PromptConfigException`; and `PromptConfigStore<T>`, the per-activation cache, behind
+  `PromptConfigProvider<T>`. Loader and store are generic over the plugin's config type:
+  a plugin supplies only a `PromptConfigParser<T>` and keeps one store, e.g.
+  `val shared = PromptConfigStore(MyParser)`, and calls `shared.reload(source, onLoaded, onFailed)`
+  from `activate()` and `shared.clear()` from `deactivate()`. The YAML library (snakeyaml-engine 2.10)
+  is on the host side, so a plugin using the loader no longer bundles it.
+  `com.itsaky.androidide.plugins.ai.ui`: `SecretRevealController`, whose two states are
+  each a `RevealToggle` (icon and content description), and
+  `View.applyPaneStyling(PaneStyle, outlinedButtonIds)`, with `PaneStyle` grouping a
+  `ButtonColors` per emphasis and a `FieldColors`. Both take the plugin's own resource ids
+  rather than shipping any: they resolve against the view's context, which carries the
+  plugin's resources, not the host's.
+  Additive to the ABI (185 added lines in the dump, none removed), but no longer unused:
+  AI-Core and the Gemini, Local and OpenAI agents now load and render their prompt config
+  through `ai.prompt` and drop their private copies, and the Gemini, OpenAI and MCP
+  settings screens use `ai.ui`. `LlmInferenceService.WebSearchBackend` (`canSearchWeb()`)
+  lets a backend say whether a `web_search` request would be searched now; ai-core forces
+  and offers its `web_search` tool only when it does. The `extraParams` keys both sides
+  read are defined once, as `WebSearchBackend.EXTRA_PARAM_WEB_SEARCH` and
+  `ToolCallingBackend.EXTRA_PARAM_REQUIRED_TOOL`. Floor
+  `plugin.min_ide_version` at `26.41` to use any of it; an older IDE has none of these
+  classes, and the plugin fails with `NoClassDefFoundError` on first use.
 - **added — Read-only App Logs and IDE Logs** _(ADFA-6267)_ **[verified]**
   Plugins could read build output (`IdeBuildService.getBuildOutput()`) but not the App Logs
   or IDE Logs tabs, so an agent diagnosing a runtime crash had to ask the user to paste them.
@@ -50,7 +84,8 @@ milestone. **[verified]** = read from the checked-in ABI dump. **[reconstructed]
   `LogReadResult.EMPTY`, never a throw. The service has no clear or write method, and needs
   no permission: plugins run in-process under the IDE's uid, so a gate would disclose log
   access, not enforce it. Purely additive (the ABI dump diff is additions only). Floor
-  `plugin.min_ide_version` at `26.40` to use it; an older IDE has no such service.
+  `plugin.min_ide_version` at `26.41` to use it; an older IDE has no such service.
+### 26.40 — 2026-09-29
 - **added — An embedding capability a backend can declare** _(ADFA-6053)_ **[verified]**
   A backend that has an embedding model can now say so. The only embedding entry point
   before this was `LlmInferenceService.getEmbeddings(String, String)`, which addresses a

docs/adr/0002-on-device-builds-via-gradle-tooling-api.md

@@ -20,6 +20,8 @@ Run builds with the **Gradle Tooling API in a separate JVM process**, and have t
 
 The app streams progress/events back from this process and renders them (e.g. `BuildState`, build output). The process runs on a **full out-of-process JDK** — the `java` binary from our terminal bootstrap packages (`appdevforall/terminal-packages`), launched by `ToolingServerRunner` — **not** the composite-build toolchains from [ADR 0003](0003-vendored-forked-desktop-toolchain.md), which are a separate, in-IDE-runtime concern.
 
+**Scope:** this covers every build that produces an installable artifact, including Quick Build's own proxy-app provisioning. Quick Build's incremental per-save step is the one exception — it compiles outside Gradle, and the trade-offs are recorded in [ADR 0016](0016-quick-build-compiles-outside-gradle.md).
+
 ## Consequences
 
 **Positive**

docs/adr/0016-quick-build-compiles-outside-gradle.md

@@ -0,0 +1,61 @@
+# 0016. Quick Build's live reload path compiles incrementally outside Gradle
+
+- **Status:** Proposed
+- **Date:** 2026-08-12
+- **Deciders:** Code On The Go team
+
+## Context
+
+[ADR 0002](0002-on-device-builds-via-gradle-tooling-api.md) builds on device through real Gradle so results match a desktop build, and rejects a custom build engine. That still holds for anything a user installs or ships.
+
+Quick Build (ADFA-4128) does a different job: fast live reload, so a developer can iterate while writing code. A standard incremental Gradle build of a single app-module edit medians 4.7 s on a Galaxy A56 and 18.4 s on an A06, against 1.1 s and 2.8 s for Quick Build `[measured on a56, a06]`.
+
+Most of that time is not spent on the edit. A one-line Kotlin edit takes 7.8 s to build incrementally on an A06:
+
+- launch and configuration, 3.9 s - paid whatever the edit touched
+- packaging and install, 1.1 s - to make an APK a running app does not need
+- dex and resource link, 1.4 s - on outputs the edit did not change
+- kotlinc, 1.2 s - the only stage the edit created
+
+The first three cannot be sped up or skipped.
+
+## Decision
+
+**Quick Build's live reload path does not use Gradle.** `:quickbuild:daemon`, a JVM child process of CoGo, compiles Kotlin with the Kotlin Build Tools API and Java with javac, then dexes with d8 and relinks resources with aapt2, using the SDK already on the device. No AGP, no r8.
+
+**Gradle handles what live reload cannot.** It still provisions the proxy app through the existing Tooling API path, and still builds every edit the classifier declines. Nothing a user installs or ships comes out of the daemon.
+
+**One compiler, not two.** Quick Build needs Kotlin 2.3.x for faster, more robust incremental compilation. Until the rest of CoGo moves up, the APK carries two Kotlin compilers. The move is in review as ADFA-2602; unifying them is ADFA-4931.
+
+## Consequences
+
+**Positive**
+
+- The edit loop is 4-6x faster, measured in the 2026-09-05 to 09-07 benchmarking run against the initial experimental Quick Build release.
+- The compiler stays warm between edits - the biggest single latency lever, and something Gradle cannot do.
+- A compiler crash kills the daemon, not the IDE, and the daemon can be shut down to give Gradle its memory back.
+
+**Negative - inherent to the decision**
+
+- Output is not identical to Gradle's. That is deliberate: close enough on the cases that matter beats full compatibility.
+- A second build pipeline to maintain. It will drift from AGP, and we cannot use Gradle as ground truth, so it needs its own ongoing testing - which is slow, because builds on low-spec devices are slow.
+
+**Negative - solvable with more work**
+
+- No annotation processing. kapt and KSP edits go to Gradle; KSP looks tractable, see [ksp-kapt-feasibility.md](../../quickbuild/docs/ksp-kapt-feasibility.md).
+- Live reload covers a narrow set of edits today; the rest fall back to Gradle. Conservative defaults, not hard limits.
+- Memory is not tuned. Gradle and Quick Build share it, and idle timeouts are all that keeps them out of each other's way.
+
+## Alternatives considered
+
+- **Gradle with fewer tasks** — rejected: the cost is mostly configuration and task-graph work, which fewer tasks do not remove, and it still builds an APK rather than a deployable payload.
+- **Compile in-process inside the IDE** — rejected for ADR 0002's own reason: a compiler OOM would take the editor with it.
+- **Replace the proxy-app build too** — rejected: it would drift from AGP on the one artifact where that is unacceptable.
+- **ART hot-swap (Apply Changes)** — rejected: needs an attached debugger and replaces only method bodies.
+- **Patch the android.jar** — rejected as infeasible; see [why not android.jar](../../quickbuild/docs/why-not-android-jar.md).
+
+## Related
+
+- [ADR 0002](0002-on-device-builds-via-gradle-tooling-api.md) — still governs full builds and Quick Build's provisioning.
+- [ADR 0004](0004-embedded-termux-runtime.md) — the daemon runs on the bundled JDK.
+- [`quickbuild/README.md`](../../quickbuild/README.md) — design and measured numbers.

docs/adr/README.md

@@ -29,3 +29,4 @@ Format is lightweight **MADR / Nygard**: Context → Decision → Consequences 
 | [0013](0013-refactoring-ui-lives-in-the-owning-lsp-module.md) | Refactoring UI lives in the owning LSP module | Proposed |
 | [0014](0014-refactorings-decline-rather-than-rewrite.md) | Interactive refactorings decline rather than rewrite unselected code | Proposed |
 | [0015](0015-one-pinned-ktfile-per-analysis.md) | One pinned live KtFile per analysis, enforced by the type system | Proposed |
+| [0016](0016-quick-build-compiles-outside-gradle.md) | Quick Build's per-save path compiles incrementally outside Gradle | Proposed |

docs/plugin-api.md

@@ -13,7 +13,7 @@ The surface a plugin binds to is broader than one module. All of the following a
   - Extension interfaces plugins **implement**: `UIExtension`, `EditorExtension`, `EditorTabExtension`, `DocumentationExtension`, `BuildActionExtension`, `SnippetExtension`, `ProjectExtension`, `FileOpenExtension`, `SettingsExtension`.
   - IDE service interfaces plugins **call** (via `ServiceRegistry.get(X::class.java)`): `IdeProjectService`, `IdeEditorService`, `IdeFileService`, `IdeEnvironmentService`, `IdeArchiveService`, `IdeBuildService`, `IdeLogService`, `IdeUIService`, `IdeEditorTabService`, `IdeTooltipService`, `IdeThemeService`, `IdeFeatureFlagService`, `IdeCommandService`, `IdeTemplateService`, `IdeSnippetService`, `IdeSidebarService`.
   - Cross-plugin service interfaces, where **one plugin implements what another calls** (via `SharedServices`): `LlmInferenceService` — implemented by ai-core, called by every AI plugin — together with the types nested in it that a *backend* plugin implements (`LlmBackend`, `HistoryCapableBackend`, `ToolCallingBackend`, `CancellableBackend`, `ConfigurableBackend`, `EmbeddingBackend`) and the value types either side constructs (`ChatMessage`, `LlmConfig`, `LlmResponse`, `SystemPromptRequest`, `ToolDefinition`, `ToolCallRequest`). Also `ToolSourceRegistry` — implemented by ai-core, called by any plugin contributing tools to the agent — with `ToolSource` and `ToolSpec`, which a *contributing* plugin implements, `ToolInvocation`, which ai-core constructs and passes to `ToolSource.invoke`, and `ToolOutcome`, which the source returns.
-  - Utility classes plugins **instantiate**: `KeystoreSecretStore` (AES/GCM over the Android Keystore, alias supplied by the caller). Host-side implementation rather than an interface, so plugins share one copy in the process instead of compiling their own.
+  - Utility classes plugins **instantiate**: `KeystoreSecretStore` (AES/GCM over the Android Keystore, alias supplied by the caller); the AI prompt config engine in `ai.prompt` (`PromptTemplateEngine`, `PromptConfigLoader`, `PromptConfigStore`, `PromptConfigDocument`, `PromptConfigObject`, `AssetPromptConfigSource`), generic over a plugin's own config type through `PromptConfigParser` and `PromptConfigProvider`, which a plugin implements; and the settings-pane helpers in `ai.ui` (`SecretRevealController` with `RevealToggle`, `applyPaneStyling` with `PaneStyle`, `ButtonColors` and `FieldColors`). Host-side implementations rather than interfaces, so plugins share one copy in the process instead of compiling their own.
   - Data classes plugins **construct** (e.g. `MenuItem`, `TabItem`, `EditorTabItem`, `NavigationItem`, `ToolbarAction`, `FabAction`, `PluginBuildAction`, `SnippetContribution`, `PluginTooltipEntry`, `PluginSettingsEntry`).
   - Enums / sealed types plugins **reference**: `PluginPermission`, `ShowAsAction`, `ArchiveFormat`, `BuildActionCategory`, `ToolbarActionIds`, `CommandSpec`, `CommandResult`, `ExtractResult`, `KeystoreSecretStore.Stored`. Sealed, so a plugin `when`s over the cases exhaustively — adding one is a **breaking** change, not an additive one.
 - **Wire/format contracts outside the module:**

gradle/libs.versions.toml

@@ -299,6 +299,8 @@ tooling-agp = { module = "com.android.tools.build:gradle", version.ref = "agp-to
 tooling-builderModel = { module = "com.android.tools.build:builder-model", version.ref = "agp-tooling" }
 tooling-gradleApi = { module = "com.itsaky.androidide.gradle:gradle-tooling-api", version.ref = "gradle-tooling" }
 tooling-slf4j = { module = "org.slf4j:slf4j-api", version = "2.0.12" }
+# 2.x targets Java 8; 3.x needs 11. Match the AI plugins' copy, which the app shadows parent-first.
+snakeyaml-engine = { module = "org.snakeyaml:snakeyaml-engine", version = "2.10" }
 
 # Classpaths
 android-gradle-plugin = { module = "com.android.tools.build:gradle", version.ref = "agp" }