Skip to content

v0.6.1

Latest

Choose a tag to compare

@github-actions github-actions released this 22 Nov 01:56
· 14 commits to main since this release

pilotdroid v0.6.1 — release notes draft

Paste into the v0.6.1 GitHub Release body. Source of truth for the
publish step; keep in sync with main until the tag lands.

Device-side UiAutomation agent for Android: single-jar dex under
app_process + pilotdroid-cli (agent.jar embedded — one binary does
setup/serve/bench) + import pilotdroid uiautomator2 drop-in shim +
stdio MCP server (27 tools).

What's new in 0.6.1 (M14–M19)

u2shim API 面补齐 — openatx 官方套件 verbatim 0/27 → 8/30 pass

  • Ran the pinned upstream mobile_tests suite (openatx/uiautomator2
    @96f581d, vendored under spike/e2e/u2suite/ with a serial-pin-only
    seam): 8 pass / 14 fail / 8 skip. All 14 fails attributed — 9
    xpath (explicitly unsupported), 1 G6 jsonrpc, 1 G8 session object
    model, 3 G10 settings semantics (documented defers in
    compat/SUPPORTED.md).
  • New shim surface (zero protocol changes): settings transparent
    dict, uiautomator2.exceptions stubs (SessionBrokenError,
    UiObjectNotFoundError), Session, watch_context ctx-mgr,
    _Selector.get_text, app_start front-wait + stop=, click
    implicit wait, swipe host-side duration sleep, push/pull
    (BytesIO), wlan_ip, app_list_running,
    app_auto_grant_permissions, app_current.pid, _WhenCtx.call,
    Device ctx-mgr.
  • Three real bugs the suite exposed, fixed: watcher exited instantly
    with zero rules (keep-alive until explicit stop); a long
    _Selector.wait starved the single control connection (sliced to
    ≤1s polls); _WhenCtx.call was arming a device-side click instead
    of staying observation-only (now action:"none", callbacks invoked
    host-side).

pip install pilotdroid now ships a working CLI

  • New pilotdroid-cli/pilotdroid console scripts lazy-download the
    matching release binary on first run — sha256-verified against
    SHA256SUMS.txt (cache-hit re-verified; refuses unverified bytes),
    cached under ~/.cache/pilotdroid/<tag>/, os.execv passthrough.
    Unblocks the MCP registry uvx pilotdroid path.
  • PILOTDROID_SERIAL env var as device fallback when -s is absent.

Supply-chain & CI hardening

  • agent-jar-repro CI job rebuilds agent.jar from source
    (javac 25 + build-tools 37.0.0 + android-34) and asserts byte-identity
    with the committed jar — dex provenance is now verifiable, not just
    commit-ordering.
  • CodeQL scanning (python + java) on push/PR/weekly.
  • adb_client 2.1.15 → 4.0.0; shell exit codes preserved via
    __PD_EXIT_ marker + subshell wrap.

Docs & compat honesty

  • Selector environment-sensitivity documented (zh-locale text/desc,
    first-launch flow-state, MIUI app-lock FLAG_SECURE gates).
  • README live-view demo GIF; MCP registry manifest draft
    (docs/mcp/, schema-validated, submit after PyPI).

Fixed

  • verify-agent deterministic shot_scale failure: batch tap could open
    a MIUI app-lock gate → FLAG_SECURE → screenshot error payload; now
    backs out after batch + readable agent error instead of KeyError.
  • u2shim failure hint no longer points at a pilotdroid setup command
    that doesn't exist in the wheel.

Base release (v0.6.0, M10–M13, agent 0.7.0 / caps 0x7ff)

Async WATCH — event-driven watchers that don't block (CAP_WATCH_ASYNC)

  • WATCH_ARM/WATCH_DISARM; hits arrive as WATCH_HIT on the media
    channel — control ops stay fully usable while armed. Measured: 40 ops
    during an armed watcher, op p50 = 43ms (same magnitude as unarmed).
  • Shim d.watcher.when(...).click() now uses device-async semantics on
    agent ≥0.7.0 (u2 watcher-equivalent); older agents fall back to
    blocking WATCH, then host polling.
  • MCP serve: watch_arm/watch_disarm/watch_events tools. Limits:
    max 8 armed watchers (ERR_LIMIT), watch_events returns
    {type:"timeout"} instead of an error on quiet media.

Multi-pointer gestures (CAP_MULTI_PTR)

  • pinch_in/pinch_out in shim and serve. Shim clamps to display and
    rejects fully off-screen bounds (MIUI ghost bounds → LookupError).

conn-side APP_INFO (CAP_APP_INFO)

  • app_current/app_wait resolve the foreground app over the agent
    conn — ~51ms vs ~96ms adb spawn (~2×, low variance, no fork).

Near-complete u2 compat surface

  • SUPPORTED.md ❌ is down to xpath only (explicitly out of scope).
    New this release: app_wait/session/send_keys/open_notification/
    open_quick_settings/freeze_rotation, instance alias, host
    post-filter keys (*Contains/*StartsWith/*Matches, attr filters,
    .count/.wait_gone, relative .left/.right/.up/.down/.child/.sibling),
    u2-parity index (XML child-position) vs instance (Nth-match).
    Real-script re-run: 23 ok / 1 unsupported(xpath) / 0 error.

Resilience & ops

  • Dead/replaced control conn self-heals (lazy reconnect, ADR-007);
    conn-replaced events warn on stderr (stdout stays pure JSON-RPC).
    One serve per device — two instances ping-pong conn ownership.
  • verify-agent.sh: lockscreen-proof runs (screen_off_timeout pinned +
    restore), transition-stall settle, hijack retry — 37/37 green.

Benchmarks (ba0d072d, USB)

scenario pilotdroid u2
watcher popup auto-heal (appear→dismiss, same-arm) ~680ms ~1790ms 2.6×
detect+act floor, hot conn 39ms — device-side WATCH
same-script e2e (M7) — — 8.8× USB / 4.7–7.4× TCP

Assets

pilotdroid-cli-linux-x86_64 · pilotdroid-cli-macos-arm64 ·
pilotdroid-cli-windows-x86_64.exe · agent.jar ·
pilotdroid-0.6.1-py3-none-any.whl + sdist · SHA256SUMS.txt

  • macOS: unsigned — xattr -d com.apple.quarantine pilotdroid-cli,
    or brew install mofanx/pilotdroid/pilotdroid
  • Windows: unsigned — SmartScreen "More info → Run anyway", or
    Unblock-File in PowerShell. Compile-verified only — the build
    passes CI but hasn't run on a real Windows machine; report issues.
  • PyPI: pip install pilotdroid

Full Changelog: v0.6.0...v0.6.1