feat(replay): accept --test-ime on test and replay so flow-owned Android opens opt into the test IME

[thymikee]

Summary

Closes #2997. test and replay now accept --test-ime / --no-test-ime, so a flow that owns its session can opt a real Android device into the bundled test IME that Maestro eraseText (backspace = control char) and non-ASCII fill need. The real-device default stays off (#1198); emulator default-on and open --no-test-ime forcing are untouched.

The opt-in rides the request flags envelope end to end — CLI readers/schemas, the test→replay fan-out, the Maestro runtime device flags, and the parent-flag inheritance shared with batch — arriving at the unchanged shouldActivateAndroidTestIme decision. Absent the flag, nothing is written anywhere, so the defaults still decide. The shell-text refusal now states only the channel limit, carries typed reason android_shell_text_unsupported, and keeps the open recovery in details; the replay failure boundary rewrites the hint to the flow-owned flag off that reason, never on message text. projectConfig: true was already on the declaration (no credential exposure; the restore-on-close safety is local), so testIme in agent-device.json now works for flow runs too — the issue's alternative ask.

Validation

• pnpm check:affected --run green at head 3bcd1860dd8380a5036651aced3208f4ebf7b9fd (unit suites, layering, eager-closure budgets, test-file-size ratchet, fallow, admission gates).
• Regression proofs verified by targeted reverts: the router-level IME-activation test, the Maestro envelope test, the .ad inheritance test, and the batch inheritance test all fail without the fix.
• Router test proves a flow-owned Android device open receives the opt-in through production routing (createRequestHandler → replay → dispatched open → lifecycle host activateAndroidTestIme seam).

Live emulator evidence (API 35 AVD ReactNative_API_35, test --maestro / replay --maestro on a Settings flow with inputText + eraseText)

• (a) test … --no-test-ime → fails at step 5 with REPLAY_DIVERGENCE, and the printed hint is the flow-owned one: "pass --test-ime to this test/replay run … for the sessions the flow opens" — it never says open --test-ime. Same shape on replay --no-test-ime (top-level Hint: line).
• (b) test … (no flag) → passes: the emulator default-on activated the test IME and eraseText's backspaces went through.
• (c) test … --test-ime → passes, and adb shell settings get secure default_input_method shows com.google.android.inputmethod.latin/...LatinIME (the original IME) restored after the run; it also reads back Latin between runs, so the close-time restore holds.
• Outstanding: the reporter's physical Pixel 8 / Android 17 run could not be measured (no physical device available); (a)/(b)/(c) above cover the flag reaching the flow-owned open in both directions per the review's fallback.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-10-06 05:34 UTC

[github-actions]

Size Report

Metric	Base	Current	Diff
Installed (including dependencies)	5.07 MB	5.07 MB	-3.0 kB
Package (unpacked)	5.07 MB	5.07 MB	-3.0 kB
Package (download)	1.52 MB	1.52 MB	-1.3 kB

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	18.6 ms	18.8 ms	+0.1 ms
CLI --help	53.8 ms	54.0 ms	+0.2 ms

[cubic-dev-ai]

All reported issues were addressed across 21 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[thymikee]

Reviewed 22889e7. The change itself looks right, but two Coverage checks fail because of this diff and the Android test IME route has no live run yet.

The Coverage failures come from this diff. The new @agent-device/contracts/android-text-input import in platform-android/src/text-input.ts and in the replay failure-response module adds one module to several eager closures (mechanics, native-command, test-command and the maestro entries). Separately, the +18 lines push src/cli/parser/__tests__/args-parse-session.test.ts from 988 to 1006 lines, over the file-size limit. Smoke Tests was still running, so I have no result to attribute. No conflicts.

Open the live run first: session-replay-maestro-runtime.ts#L353 changes which Android device open switches to the test IME during test/replay. The only evidence is unit and router tests that mock activateAndroidTestIme. Nothing shows a real eraseText flow passing under test/replay with the opt-in, or the rewritten hint reaching the CLI user. Please attach live output from an Android emulator, or a real device if you have one, for three runs. (a) agent-device test --maestro <flow with eraseText> --no-test-ime should fail with REPLAY_DIVERGENCE, and the hint should name --test-ime on test/replay, not open --test-ime. (b) The same flow with no flag should pass, since the emulator default is on. (c) On a real device, test --test-ime should pass, and adb shell settings get secure default_input_method should show the real keyboard restored after the run. Without a real device, (a) and (b) on an emulator are enough to show the flag reaches the flow-owned open in both directions.

Could the new contracts subpath packages/contracts/src/android-text-input.ts go away? It is the whole eager-closure growth. Each hint could live with its only user: ANDROID_TEST_IME_OPEN_HINT in platform-android/src/text-input.ts, and ANDROID_TEST_IME_FLOW_HINT in the replay-port failure-response module. Only the reason literal needs a shared home, and a contracts module both closures already load (for example input-validation.ts) would do. Then there is no new subpath, no snapshot entry and no growth, and nothing else has to change first. Please move the --test-ime parser test into a split file that mirrors the replay/test parser module.

The cubic-dev-ai P2 thread on test strength still applies: #3235 (comment)

Not blocking: adding testIme to INHERITED_PARENT_FLAG_KEYS in batch-policy.ts#L52 also changes batch, but batch's CLI schema does not accept --test-ime, so no caller can set it there and the batch test pins an unreachable path. You can either document that batch is not a surface for this flag and drop that test, or accept the flag on batch and document it. Take it or leave it.

Before merge, fix the two Coverage checks, then attach the live Android run.

[thymikee]

The code change looks sound at c453e0e, but no live Android run backs it yet, and Coverage fails because of this PR. No conflicts.

The change alters which Android session opens switch the device IME during test and replay, and it changes the hint users see on REPLAY_DIVERGENCE. The only proof is unit and router tests that mock activateAndroidTestIme, so no run reaches adb ime set or the Maestro eraseText backspace path (https://github.com/callstack/agent-device/blob/c453e0e/packages/replay-port/src/daemon-port/session-replay-maestro-runtime.ts#L353). Nothing shows the failure reported in #2997 now passing, or the real keyboard coming back after the flow-owned session closes. Please attach live output from an Android emulator. First, agent-device test --maestro <flow with eraseText> --no-test-ime should fail with REPLAY_DIVERGENCE, and the top-level hint should name --test-ime on test/replay, not open --test-ime. Second, the same flow with no flag should pass. If a physical device is available, test --test-ime should pass, and adb shell settings get secure default_input_method should show the original IME after the run.

Coverage fails in eager-closure-budgets on six entries, and each one is +1 from packages/contracts/src/android-text-input.ts, which this PR adds. The test-file-size-ratchet also fails, because the 18 new lines take src/cli/parser/__tests__/args-parse-session.test.ts from 988 to 1006 lines. Both look related to this PR. Smoke Tests was still running when I reviewed, so I attribute nothing to it.

Could the same plumbing work without the new contracts subpath? A shared symbol should live in a contracts module that every closure it reaches already evaluates. So ANDROID_SHELL_TEXT_UNSUPPORTED_REASON could go in contracts/src/input-validation.ts, each hint could stay in its only consumer, and the parser test could move to a split file that mirrors the replay/test parser module. Threading the flag through INHERITED_PARENT_FLAG_KEYS and the Maestro device flags already looks like the smallest owning route, and I found no smaller one.

On the review threads, the cubic-dev-ai P2 thread on the failure-response test is fixed at this head, so you can resolve it: #3235 (comment).

I did not trace whether project config or AGENT_DEVICE_TEST_IME is filtered by each command's allowedFlags before it reaches test and replay, so I cannot confirm that config now works for flow runs. I also did not read the test-to-replay suite fan-out code beyond the PR's nested-flags test.

Before merge, please attach the two live emulator runs, remove the contracts/android-text-input subpath, and split the --test-ime parser test out of args-parse-session.test.ts.

[thymikee]

All review items addressed at 3bcd186:

• Coverage / eager closures — the @agent-device/contracts/android-text-input subpath is gone. The typed reason moved to contracts/src/input-validation.ts, which every affected closure already evaluates (exposed via the contracts/command facade re-export plus the module subpath); the two hints now live with their only consumers (platform-android/src/text-input.ts and the replay failure-response module). eager-closure-budgets is green locally.
• Coverage / test-file-size ratchet — the --test-ime parser cases split into src/cli/parser/__tests__/args-parse-test-ime.test.ts; args-parse-session.test.ts is back under the tripwire (970 lines).
• Live Android run — attached as the "Live emulator evidence" section of the PR body: (a) --no-test-ime fails with REPLAY_DIVERGENCE naming --test-ime on this run (not open --test-ime) on both test --maestro and replay --maestro; (b) no flag passes on the emulator via default-on; (c) --test-ime passes and default_input_method reads the original Latin IME after the run. The physical Pixel 8 run stays declared as not-measured.
• cubic P2 thread — fixed at c453e0e (fixture carries the hoisted open-route hint) and the thread is resolved.
• Batch inheritance (not-blocking) — kept: it is reachable through raw daemon envelopes and the SDK (buildFlags maps options.testIme for every command), so the batch test pins real reachable behavior, and the comment in batch-policy.ts states the shared-list tradeoff rather than claiming replay-only.

pnpm check:affected --run green at head 3bcd186.

[thymikee]

The PR is ready at 3bcd186. The two Coverage failures from c453e0e (eager-closure-budgets and test-file-size-ratchet) are fixed. The delta removes the contracts subpath and moves the parser cases into a new test file. All 21 checks now pass.

Not blocking: the fixture in session-replay-runtime-failure-response.test.ts (https://github.com/callstack/agent-device/blob/3bcd186/packages/replay-port/src/daemon-port/__tests__/session-replay-runtime-failure-response.test.ts#L85) now writes the open-route hint as a literal, because replay-port cannot import the Android package. If ANDROID_TEST_IME_OPEN_HINT changes, the literal can drift silently, but the test still passes since the rewrite keys on details.reason. You could shorten it to a stable stand-in, or leave it as is.

The cubic-dev-ai P2 thread on the failure-response test fixture is fixed at this head, so you can resolve it: #3235 (comment)

I did not reproduce the live emulator runs from the PR body. I did not rerun eager-closure-budgets or the full gate, and relied on the passing checks. I did not trace whether AGENT_DEVICE_TEST_IME or project config reaches test and replay through the allowedFlags filter. The PR body claims it, and the flag declares projectConfig true with both schemas listing it. Physical-device behavior is unmeasured. Nothing else stands in the way, so the merge is a maintainer decision.