[PR #3840] feat(android): add boot wait and resource-id to code tracing #5939

Open
opened 2026-10-31 01:10:35 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/3840
Author: @FabioLima77
Created: 10/15/2026
Status: 🔄 Open

Base: main ← Head: feat/android-dynamic-pipeline


📝 Commits (10+)

  • 7f1f3d0 feat(adb): add boot wait, UI state capture, and input injection tools
  • 4eb284c feat(android): map UI resource ids to DEX code sites
  • 23be1d6 fix(android): address review findings in the dynamic pipeline
  • 052174a fix(adb): fail send-adb-input when its actions cannot be read
  • c608231 fix(cli): let Ctrl-C stop reading send-adb-input actions
  • 3a4a030 refactor(adb): defer UI capture and input to the UI Automator lane
  • 05f3972 docs(android): point resource-id source at uiautomator dump
  • 752915e fix(android): address Codex review on resource tracing and boot wait
  • 8d07db6 fix(android): size resource scans for the MCP frame and expose lookup class names
  • e154a1e Merge origin/main into feat/android-dynamic-pipeline

📊 Changes

36 files changed (+1248 additions, -16 deletions)

View changed files

📝 .github/workflows/real-android-metadata.yml (+1 -0)
📝 bridge/android/ReaJadxBridge.java (+245 -2)
📝 docs/adb-device-analysis.md (+1 -0)
📝 docs/android-analysis.md (+30 -0)
📝 scripts/verify/android/metadata.mjs (+8 -0)
📝 src/adb/AdbCommand.test.ts (+18 -1)
📝 src/adb/AdbCommand.ts (+7 -0)
📝 src/adb/AdbProvider.test.ts (+103 -0)
📝 src/adb/AdbProvider.ts (+121 -0)
📝 src/android/JadxAnalysis.ts (+69 -1)
📝 src/android/JadxProtocol.ts (+40 -0)
📝 src/catalogIdentity.ts (+4 -2)
📝 src/cli/adbCommands.ts (+26 -0)
📝 src/cli/androidCommands.ts (+34 -0)
📝 src/cliCommandNames.ts (+2 -0)
📝 src/contracts/adb/adbToolContracts.ts (+15 -0)
📝 src/contracts/android/androidToolContracts.ts (+20 -0)
📝 src/contracts/toolEffects.ts (+10 -0)
📝 src/cutter/CutterBridgeClient.ts (+6 -2)
📝 src/domain/adb/adbDeviceAnalysis.ts (+36 -0)

...and 16 more files

📄 Description

Requested by Fabio Lima

Summary

Adds two Android analysis tools that complement the UI Automator lane in
#3004:

  • wait_adb_boot: waits until a device reports sys.boot_completed=1.
  • trace_android_resource_references: maps UI resource-id values (for
    example those #3004 discovers) to their integer IDs, R declarations and
    every DEX instruction that loads them.

Scope was narrowed after the #3004/#3840 comparison: UI capture and input
actions are left to #3004's UI Automator backend. The removed tools remain on
FabioLima77:backup/android-ui-input-3840 for reference.

Problem and expected behavior

  • Dynamic workflows start an emulator outside REA and need a reliable readiness
    signal before installing or launching apps. wait_adb_boot polls
    sys.boot_completed, dev.bootcomplete and init.svc.bootanim, tolerates a
    device that is still offline or not yet listed, fails fast on unauthorized,
    and probes once more at the deadline instead of stopping a full interval
    early. It returns boot_completed or timed_out with the last observed
    properties.
  • A resource-id seen on screen (com.example:id/login, android:id/title) had
    no static link to code. trace_android_resource_references resolves it
    through the APK resource table (or JADX's bundled framework map for
    android:) and scans every method's raw DEX instructions once for
    const_literal loads (findViewById), switch_case keys (click dispatch on
    getId()) and r_field_read reads of non-final library R fields.

Change and scope

  • wait_adb_boot is an AdbProvider operation beside the existing adb tools.
  • rea_resource_references in ReaJadxBridge.java, normalized in
    JadxAnalysis.ts. Sites and R declarations share the bridge's 8 MiB
    transport budget; total_sites and total_r_fields stay exact and bounded
    results report coverage: "partial". R declarations carry origin
    (dex | jadx_generated) because JADX synthesizes an app R class when the
    APK has none. Unresolved names stay explicit, not reported as unused.
  • Not included: UI capture or input (see #3004), layout-XML, data-binding or
    reflection (getIdentifier) mapping, emulator lifecycle (REA still never
    starts or manages emulators).

Contract and boundary impact

  • Semantic owner and earliest changed stage: ADB and Android domain schemas.
  • Contribution scope fit and linked maintainer decision: read-only tools; none linked.
  • CLI and MCP/tool-catalog contract: two new tools and CLI commands
    (wait-adb-boot, trace-android-resource-references); existing contracts unchanged.
  • Provider, bridge, target-format, or platform compatibility: JADX bridge gains
    one tool; verified with jadx-headless-mcp 0.7.1.
  • Evidence, artifact, provenance, or reconstruction contract: inline Evidence
    with explicit partial coverage and unresolved states.
  • Target selection, authority, upstream behavior, and cleanup details: no device mutation.
  • Generated metadata: catalog regenerated by docs:check, not committed.

Expected effects:

  • Read existing files or captured data.
  • Launch or attach to a process.
  • Inject instrumentation or run scripts/code.
  • Change process memory, registers, files, or configuration.
  • Contact network services.
  • Recover protected code or work around protections.
  • Documentation or usability only; no target interaction.
  • Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

  • Tests added or updated: real-JAR regression
    tests/conformance/android/ReaJadxMetadataRegression.java over the smali
    fixture tests/fixtures/android/resource-references/ (const, packed and sparse
    switch, library R-field read); tests/boundary/android/JadxAnalysis.test.ts;
    src/adb/AdbProvider.test.ts (boot completion, deadline probe, unreachable
    device; POSIX adb stub); tests/boundary/mcp/adbMcp.test.ts.
  • Real workflow (executed, Windows 11, emulator 37.2.12 + WHPX, Android 14
    google_apis x86_64, adb 37.0.1, jadx-headless-mcp 0.7.1):
    • wait-adb-boot → boot_completed after 36–81 s; with a 1000 ms timeout and
      2000 ms interval it probes again at the deadline.
    • SettingsGoogle.apk (16,954 classes, 98,791 methods, ~17 s incl. load):
      com.android.settings:id/search_action_bar → 0x7f0c0523 →
      SettingsHomepageActivity.initSearchBarView, confirmed by
      inspect-android-method (findViewById(R.id.search_action_bar));
      android:id/title → 0x01020016, 37 sites; unknown id → unresolved.
    • Termux v0.118.3 x86_64: com.termux:id/terminal_view → 0x7f080191 →
      TermuxActivity.setTermuxTerminalViewAndClients; R$id origin dex.
  • Remaining proof gaps: AdbProvider.test.ts stub tests run only on
    Linux/macOS CI.

Validation performed

  • Resource regression (verifyResourceReferences via a local driver against
    jadx-headless-mcp 0.7.1) — RESOURCE_REFERENCE_REGRESSION_PASS title_sites=3 switch=packed,sparse r_field=dex.
  • npm run check:fast — pass.
  • npm run docs:check — pass.
  • npx vitest run tests/boundary/mcp/adbMcp.test.ts tests/boundary/android/JadxAnalysis.test.ts tests/acceptance/tools/localToolContracts.test.ts tests/boundary/cli/adbCli.test.ts — 29 passed, 6 skipped.
  • npm run test:local -- src/contracts/toolEffects.test.ts src/adb/AdbProvider.test.ts — passed (provider stub suite skipped on Windows).

Compatibility, safety, and release

  • Breaking changes or migration steps: none.
  • Real Hopper/Ghidra, browser, or OS coverage: Windows 11 only; Linux/macOS via CI.
  • Package or release metadata impact: two new tools in the catalog.
  • Security, privacy, process, or containment review: both tools are read-only;
    adb arguments stay positional and shell-quoted at the adb boundary.

Author readiness

Human owner: @FabioLima77

  • I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
  • I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
  • I declare this PR ready for initial maintainer review.

Before merge

  • This PR addresses a concrete problem or an agreed enhancement.
  • Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
  • The PR has one focused outcome and the title follows type(scope): outcome.
  • Related issue is linked, or the reason for not linking one is stated above.
  • Tests cover changed observable behavior and meaningful failure paths.
  • Owning docs, contracts, and generated metadata are updated where needed.
  • User-visible CLI/MCP changes include representative output.
  • I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

🤖 Generated with Claude Code


🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/3840 **Author:** [@FabioLima77](https://github.com/FabioLima77) **Created:** 10/15/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `feat/android-dynamic-pipeline` --- ### 📝 Commits (10+) - [`7f1f3d0`](https://github.com/morluto/rea/commit/7f1f3d06e0afe95a3522bd2bbc9c0cae37d238fd) feat(adb): add boot wait, UI state capture, and input injection tools - [`4eb284c`](https://github.com/morluto/rea/commit/4eb284c447aac7849ffaca00b9c2f2c41ec66489) feat(android): map UI resource ids to DEX code sites - [`23be1d6`](https://github.com/morluto/rea/commit/23be1d6f5d6fc055ac82a375c7347931ae04099e) fix(android): address review findings in the dynamic pipeline - [`052174a`](https://github.com/morluto/rea/commit/052174a8085e467a2e70ced42e203515d3c28c3f) fix(adb): fail send-adb-input when its actions cannot be read - [`c608231`](https://github.com/morluto/rea/commit/c608231b87160286ff32b170eb023e12f4e6cafe) fix(cli): let Ctrl-C stop reading send-adb-input actions - [`3a4a030`](https://github.com/morluto/rea/commit/3a4a0306f868fe3b6c9032c78de11b1604bcca79) refactor(adb): defer UI capture and input to the UI Automator lane - [`05f3972`](https://github.com/morluto/rea/commit/05f397221d41deda1de8908f80e27a3be4a0e129) docs(android): point resource-id source at uiautomator dump - [`752915e`](https://github.com/morluto/rea/commit/752915eadd980b14744977a6d7408ed7ee002cbb) fix(android): address Codex review on resource tracing and boot wait - [`8d07db6`](https://github.com/morluto/rea/commit/8d07db6dfaec9e1e406a6eec0012ff43e5b38ece) fix(android): size resource scans for the MCP frame and expose lookup class names - [`e154a1e`](https://github.com/morluto/rea/commit/e154a1e3f793f95bc3fd3a0b6ecee9948d44da8d) Merge origin/main into feat/android-dynamic-pipeline ### 📊 Changes **36 files changed** (+1248 additions, -16 deletions) <details> <summary>View changed files</summary> 📝 `.github/workflows/real-android-metadata.yml` (+1 -0) 📝 `bridge/android/ReaJadxBridge.java` (+245 -2) 📝 `docs/adb-device-analysis.md` (+1 -0) 📝 `docs/android-analysis.md` (+30 -0) 📝 `scripts/verify/android/metadata.mjs` (+8 -0) 📝 `src/adb/AdbCommand.test.ts` (+18 -1) 📝 `src/adb/AdbCommand.ts` (+7 -0) 📝 `src/adb/AdbProvider.test.ts` (+103 -0) 📝 `src/adb/AdbProvider.ts` (+121 -0) 📝 `src/android/JadxAnalysis.ts` (+69 -1) 📝 `src/android/JadxProtocol.ts` (+40 -0) 📝 `src/catalogIdentity.ts` (+4 -2) 📝 `src/cli/adbCommands.ts` (+26 -0) 📝 `src/cli/androidCommands.ts` (+34 -0) 📝 `src/cliCommandNames.ts` (+2 -0) 📝 `src/contracts/adb/adbToolContracts.ts` (+15 -0) 📝 `src/contracts/android/androidToolContracts.ts` (+20 -0) 📝 `src/contracts/toolEffects.ts` (+10 -0) 📝 `src/cutter/CutterBridgeClient.ts` (+6 -2) 📝 `src/domain/adb/adbDeviceAnalysis.ts` (+36 -0) _...and 16 more files_ </details> ### 📄 Description <!-- claude-projects-attribution --> _Requested by **Fabio Lima**_ ## Summary Adds two Android analysis tools that complement the UI Automator lane in #3004: - `wait_adb_boot`: waits until a device reports `sys.boot_completed=1`. - `trace_android_resource_references`: maps UI `resource-id` values (for example those #3004 discovers) to their integer IDs, `R` declarations and every DEX instruction that loads them. Scope was narrowed after the #3004/#3840 comparison: UI capture and input actions are left to #3004's UI Automator backend. The removed tools remain on `FabioLima77:backup/android-ui-input-3840` for reference. ## Problem and expected behavior - Dynamic workflows start an emulator outside REA and need a reliable readiness signal before installing or launching apps. `wait_adb_boot` polls `sys.boot_completed`, `dev.bootcomplete` and `init.svc.bootanim`, tolerates a device that is still offline or not yet listed, fails fast on `unauthorized`, and probes once more at the deadline instead of stopping a full interval early. It returns `boot_completed` or `timed_out` with the last observed properties. - A resource-id seen on screen (`com.example:id/login`, `android:id/title`) had no static link to code. `trace_android_resource_references` resolves it through the APK resource table (or JADX's bundled framework map for `android:`) and scans every method's raw DEX instructions once for `const_literal` loads (`findViewById`), `switch_case` keys (click dispatch on `getId()`) and `r_field_read` reads of non-final library `R` fields. ## Change and scope - `wait_adb_boot` is an `AdbProvider` operation beside the existing adb tools. - `rea_resource_references` in `ReaJadxBridge.java`, normalized in `JadxAnalysis.ts`. Sites and `R` declarations share the bridge's 8 MiB transport budget; `total_sites` and `total_r_fields` stay exact and bounded results report `coverage: "partial"`. `R` declarations carry `origin` (`dex` | `jadx_generated`) because JADX synthesizes an app `R` class when the APK has none. Unresolved names stay explicit, not reported as unused. - Not included: UI capture or input (see #3004), layout-XML, data-binding or reflection (`getIdentifier`) mapping, emulator lifecycle (REA still never starts or manages emulators). ## Contract and boundary impact - Semantic owner and earliest changed stage: ADB and Android domain schemas. - Contribution scope fit and linked maintainer decision: read-only tools; none linked. - CLI and MCP/tool-catalog contract: two new tools and CLI commands (`wait-adb-boot`, `trace-android-resource-references`); existing contracts unchanged. - Provider, bridge, target-format, or platform compatibility: JADX bridge gains one tool; verified with jadx-headless-mcp 0.7.1. - Evidence, artifact, provenance, or reconstruction contract: inline Evidence with explicit partial coverage and unresolved states. - Target selection, authority, upstream behavior, and cleanup details: no device mutation. - Generated metadata: catalog regenerated by `docs:check`, not committed. Expected effects: - [x] Read existing files or captured data. - [x] Launch or attach to a process. - [ ] Inject instrumentation or run scripts/code. - [ ] Change process memory, registers, files, or configuration. - [ ] Contact network services. - [ ] Recover protected code or work around protections. - [ ] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage - Tests added or updated: real-JAR regression `tests/conformance/android/ReaJadxMetadataRegression.java` over the smali fixture `tests/fixtures/android/resource-references/` (const, packed and sparse switch, library R-field read); `tests/boundary/android/JadxAnalysis.test.ts`; `src/adb/AdbProvider.test.ts` (boot completion, deadline probe, unreachable device; POSIX adb stub); `tests/boundary/mcp/adbMcp.test.ts`. - Real workflow (executed, Windows 11, emulator 37.2.12 + WHPX, Android 14 google_apis x86_64, adb 37.0.1, jadx-headless-mcp 0.7.1): - `wait-adb-boot` → `boot_completed` after 36–81 s; with a 1000 ms timeout and 2000 ms interval it probes again at the deadline. - SettingsGoogle.apk (16,954 classes, 98,791 methods, ~17 s incl. load): `com.android.settings:id/search_action_bar` → `0x7f0c0523` → `SettingsHomepageActivity.initSearchBarView`, confirmed by `inspect-android-method` (`findViewById(R.id.search_action_bar)`); `android:id/title` → `0x01020016`, 37 sites; unknown id → `unresolved`. - Termux v0.118.3 x86_64: `com.termux:id/terminal_view` → `0x7f080191` → `TermuxActivity.setTermuxTerminalViewAndClients`; `R$id` origin `dex`. - Remaining proof gaps: `AdbProvider.test.ts` stub tests run only on Linux/macOS CI. ## Validation performed - Resource regression (`verifyResourceReferences` via a local driver against jadx-headless-mcp 0.7.1) — `RESOURCE_REFERENCE_REGRESSION_PASS title_sites=3 switch=packed,sparse r_field=dex`. - `npm run check:fast` — pass. - `npm run docs:check` — pass. - `npx vitest run tests/boundary/mcp/adbMcp.test.ts tests/boundary/android/JadxAnalysis.test.ts tests/acceptance/tools/localToolContracts.test.ts tests/boundary/cli/adbCli.test.ts` — 29 passed, 6 skipped. - `npm run test:local -- src/contracts/toolEffects.test.ts src/adb/AdbProvider.test.ts` — passed (provider stub suite skipped on Windows). ## Compatibility, safety, and release - Breaking changes or migration steps: none. - Real Hopper/Ghidra, browser, or OS coverage: Windows 11 only; Linux/macOS via CI. - Package or release metadata impact: two new tools in the catalog. - Security, privacy, process, or containment review: both tools are read-only; adb arguments stay positional and shell-quoted at the adb boundary. ## Author readiness Human owner: @FabioLima77 - [x] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. ## Before merge - [ ] This PR addresses a concrete problem or an agreed enhancement. - [ ] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [ ] The PR has one focused outcome and the title follows `type(scope): outcome`. - [ ] Related issue is linked, or the reason for not linking one is stated above. - [ ] Tests cover changed observable behavior and meaningful failure paths. - [ ] Owning docs, contracts, and generated metadata are updated where needed. - [ ] User-visible CLI/MCP changes include representative output. - [ ] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
morluto/rea#5939
No description provided.