adb-ready 0.2.0 → 0.3.0

package/docs/agent-integration.md

@@ -129,14 +129,21 @@ Ask the agent to follow this sequence:
 1. Call `doctor` when host or ADB health is unknown.
 2. Call `ensure_ready`; provide an exact device serial, configured alias, or
    transport ID when more than one ready target exists.
-3. Resolve the project app with `resolve_app`.
-4. Use `inspect_app` or `inspect_ui` for bounded current evidence.
-5. Perform one typed action, then inspect again instead of assuming success.
-6. Use `get_session_problems` or `compile_debug_context` for an existing
+3. Start the configured stack with `start_dev_session` when it is not already
+   running; retain its task handle and poll `get_dev_session` without holding a
+   tool call open.
+4. Resolve the project app with `resolve_app`.
+5. Use `inspect_app` or `inspect_ui` for bounded current evidence.
+6. Perform one typed action, then inspect again instead of assuming success.
+7. Use `get_session_problems` or `compile_debug_context` for an existing
    development session.
 
-The first successful `ensure_ready` binds one target to that MCP connection.
-Later tools cannot silently switch to another target.
+The first successful `ensure_ready` binds one target to that MCP connection and
+returns a `targetHandle`. Pass that handle to later target-bound calls when the
+client supports workflow state. A stale or cross-connection handle is rejected,
+and later tools cannot silently switch targets. When no ready target exists,
+`ensure_ready` may reconnect an explicit network endpoint or the single
+unambiguous paired service; it never guesses among multiple devices.
 
 Tool calls within one MCP connection are executed in submission order. This
 prevents parallel agent requests from interleaving target binding, UI snapshots,
@@ -147,10 +154,11 @@ or device mutations. Separate MCP connections remain independent.
 | Capability | MCP tools |
 | --- | --- |
 | Host and target readiness | `doctor`, `list_targets`, `ensure_ready` |
+| Durable development lifecycle | `start_dev_session`, `get_dev_session`, `stop_dev_session` |
 | App identity and lifecycle | `resolve_app`, `install_app`, `launch_app`, `restart_app`, `open_url` |
 | Current evidence | `inspect_app`, `inspect_ui`, `capture_screenshot` |
-| Safe UI actions | `tap_ui`, `long_press_ui`, `swipe_ui`, `type_text_ui`, `press_key_ui`, `wait_for_ui` |
-| Saved diagnostics | `get_session_problems`, `compile_debug_context` |
+| Safe UI queries and actions | `audit_ui`, `get_ui`, `find_ui`, `assert_ui`, `compare_ui`, `tap_ui`, `long_press_ui`, `scroll_ui`, `swipe_ui`, `fill_ui`, `clear_ui`, `type_text_ui`, `press_key_ui`, `wait_for_ui` |
+| Saved diagnostics | `list_sessions`, `get_session_problems`, `compile_debug_context` |
 
 MCP resources keep larger read-only context outside tool calls:
 
@@ -162,12 +170,20 @@ MCP resources keep larger read-only context outside tool calls:
 | `adb-ready://sessions/{sessionId}/events/{offset}/{limit}` | a page of up to 200 redacted events |
 | `adb-ready://sessions/{sessionId}/context` | a bounded redacted Markdown context document |
 
-Tool results contain the same structured success, problem, evidence, and
-verification data used by CLI JSON output.
+Every tool advertises an output schema and returns the same versioned result
+envelope used by CLI JSON output. Screenshot capture additionally returns MCP
+`image` content so a vision-capable agent can inspect the pixels directly; the
+verified project-local PNG remains the evidence source of record.
 
 The npm package also ships `schema/agent-tools-v1.json`, generated from the
 server's real `tools/list` response during every build. Integrations can inspect
-version-matched input schemas and safety annotations without starting ADB.
+version-matched input and output schemas plus safety annotations without
+starting ADB.
+
+`list_sessions` is project-scoped by default and supports status, preset,
+recency, and result-count filters. When more matches remain, pass its opaque
+`nextCursor` back as `cursor`; an expired cursor fails explicitly instead of
+silently restarting the list.
 
 ## Safety boundary
 
@@ -181,6 +197,8 @@ version-matched input schemas and safety annotations without starting ADB.
 - Data clearing and uninstall are intentionally absent from the agent surface.
 - Tool annotations help clients request approval, but ADB Ready enforces its
   own target, path, and destructive-action rules.
+- Durable development handles are random, project-scoped, heartbeat-checked,
+  and can signal only the owned managed process recorded for that handle.
 - Nothing is uploaded by ADB Ready. The selected AI client controls what tool
   results it sends to its model provider.
 
@@ -191,8 +209,8 @@ the complete trust model.
 ## Runtime alternatives
 
 The published bundle is smoke-tested as an MCP stdio server under Node.js, Bun,
-and Deno. Replace the command and arguments when Node.js is not your chosen
-runtime:
+and Deno against the legacy 2025-11-25 and modern 2026-07-28 protocol eras.
+Replace the command and arguments when Node.js is not your chosen runtime:
 
 ```text
 Bun:  bun  ./node_modules/adb-ready/dist/cli.js mcp

package/docs/apps-and-evidence.md

@@ -48,14 +48,21 @@ User packages are the default. Enumeration and machine output are bounded.
 
 ```bash
 adb-ready app install ./android/app/build/outputs/apk/debug/app-debug.apk --replace
+adb-ready app install ./splits/base.apk ./splits/config.arm64_v8a.apk ./splits/config.en.apk
 adb-ready app launch
 adb-ready app restart
 adb-ready app stop
 adb-ready open 'myapp://orders/42' --package com.example.app
 ```
 
-- Installation currently accepts one ordinary APK. Split APK sets, `.apks`,
-  `.aab`, and implicit downloads are not accepted.
+Pass all files from one split APK set together; ADB Ready uses Android's
+`install-multiple` operation and verifies the installed package afterward.
+Android App Bundles (`.aab`) and APK Set archives (`.apks`) are not directly
+installable. Generate device-specific APKs with the Android build tool that
+created them, then pass those `.apk` files explicitly.
+
+- Installation accepts one ordinary APK or an explicit complete split APK set.
+  `.apks`, `.aab`, and implicit downloads are not accepted yet.
 - Install, launch, stop, restart, and explicit deep-link handlers are checked
   after ADB accepts the request.
 - `restart` is a verified stop followed by a verified launch.

package/docs/automation.md

@@ -19,6 +19,14 @@ adb-ready logs --format ndjson --non-interactive
 | `ndjson` | one versioned event per line, followed by the command result where applicable; saved timelines end with an event-count summary instead of duplicating the full event array |
 | `markdown` | bounded diagnostic context; only valid for `context` |
 
+Calling the root with `--json` returns a small product/capability overview. It
+does not probe ADB or load project configuration, which makes it safe for an
+agent or integration to identify the installed CLI first:
+
+```bash
+adb-ready --json
+```
+
 Machine data is written to `stdout`. Human progress and diagnostics are written
 to `stderr`. `--quiet` hides successful human output without hiding failures.
 
@@ -46,8 +54,8 @@ schema version.
 The npm package includes two versioned public artifacts:
 
 - `schema/config-v1.schema.json` validates project configuration; and
-- `schema/agent-tools-v1.json` catalogs every MCP tool's generated input schema
-  and safety annotations for the matching package version.
+- `schema/agent-tools-v1.json` catalogs every MCP tool's generated input and
+  output schemas plus safety annotations for the matching package version.
 
 ## Event envelope
 
@@ -117,6 +125,39 @@ adb-ready dev --port 8081 --dry-run --json
 Plan steps declare their risk. A dry run performs no pairing, connection,
 mapping, hook, or child-process mutation.
 
+## Run one bounded verification
+
+Use `run` when CI or an agent must prove a workflow and then exit instead of
+leaving a development server open:
+
+```bash
+adb-ready run --preset expo --run-timeout 10m -- \
+  maestro '--device={target.serial}' test .maestro/smoke.yaml
+```
+
+ADB Ready selects and exclusively leases one target, prepares the configured
+ports and development command, waits for every readiness assertion, runs the
+exact command after `--`, and cleans only the resources it created. It never
+retries a failed product assertion as if it were an infrastructure failure.
+
+The literal `{target.serial}` inside a verification argument is replaced only
+after ADB Ready selects and leases the target. The child also receives the
+same value as `ANDROID_SERIAL` and `ADB_READY_TARGET_SERIAL`. This keeps tools
+such as Maestro pinned explicitly without invoking a shell; tools that already
+honor `ANDROID_SERIAL`, including common Gradle/ADB workflows, need no placeholder.
+
+Every executed run prints the path to a project-local evidence directory under
+`.adb-ready/artifacts/`. Its manifest references the structured result,
+timeline, problems, focused logcat, bounded AI context, JUnit XML, and a concise
+GitHub Actions summary. The evidence remains available when readiness or the
+verification command fails.
+
+Preview the complete project plan before a device is allocated:
+
+```bash
+adb-ready run --preset expo --dry-run --json -- npm run test:e2e
+```
+
 ## CI example
 
 ```yaml

package/docs/configuration.md

@@ -65,7 +65,7 @@ existing file unless `--force` is explicit. Use `--dry-run` first.
 
 | Field | Values or shape |
 | --- | --- |
-| `preset` | `expo`, `react-native`, `gradle`, or `custom` |
+| `preset` | `expo`, `react-native`, `flutter`, `capacitor`, `gradle`, or `custom` |
 | `packageManager` | `npm`, `pnpm`, `yarn`, or `bun` |
 | `command` | `{ "executable": string, "args": string[], "cwd"?: string }` |
 | `reversePorts` | integers or `{ "device": number, "host"?: number }` objects |

package/docs/dev-sessions.md

@@ -10,6 +10,8 @@ local diagnostic record.
 | --- | --- | --- | --- |
 | Expo | `expo` dependency | project `start` script with `--android`, otherwise Expo CLI | `8081` |
 | React Native | `react-native` dependency | project `android` script, otherwise React Native CLI | `8081` |
+| Flutter | `pubspec.yaml` | `flutter run -d <selected-target>` | none |
+| Capacitor | `@capacitor/android` or `@capacitor/core` dependency | Capacitor CLI for the selected target | none |
 | Gradle | wrapper or Gradle build file | wrapper `installDebug` | none |
 | Custom | explicit config or `--` | exact executable and argument array | none |
 
@@ -18,6 +20,8 @@ Select a preset when detection is intentionally unavailable or ambiguous:
 ```bash
 adb-ready dev --preset expo
 adb-ready dev --preset react-native --package-manager pnpm
+adb-ready dev --preset flutter
+adb-ready dev --preset capacitor
 adb-ready dev --preset gradle --device emulator-5554
 ```
 

package/docs/logs-and-context.md

@@ -57,6 +57,18 @@ adb-ready sessions events SESSION_ID --format ndjson
 adb-ready problems SESSION_ID
 ```
 
+Find the useful run without scanning a long global list:
+
+```bash
+adb-ready sessions list --status failed --since 24h --limit 5
+adb-ready sessions list --preset expo
+adb-ready sessions list --all-projects
+```
+
+History is scoped to the current project by default. Status, time, preset, and
+count filters apply before output; `--all-projects` is an explicit escape hatch
+for a machine-wide audit.
+
 When the ID is omitted, the latest saved session is selected. Default retention
 keeps at most 30 finalized sessions, 14 days, and 20 MiB. Active sessions are
 not pruned as finalized history.
@@ -88,6 +100,9 @@ Available filters are `problems`, `recovery`, `logs`, `child`, `state`, `target`
 and `ports`. The compiler prioritizes structured problems, failures, warnings,
 recovery, and nearby diagnostic output within the requested character budget.
 It reports how many events were filtered or omitted.
+Repeated successful health checks are represented once with their count and
+final timestamp. The stored NDJSON remains complete, so compact AI context does
+not discard diagnostic evidence.
 
 Use JSON when another local tool should consume the result envelope:
 

package/docs/troubleshooting.md

@@ -31,6 +31,7 @@ adb-ready context --since 5m --only problems,recovery,logs
 | `MULTIPLE_WIRELESS_ENDPOINTS` | Discovery returned ambiguous services | Pass one exact `HOST:PORT` |
 | `PORT_MAPPING_CONFLICT` | Another mapping owns the requested listen port | Inspect `ports ... list`; remove or change it explicitly |
 | `LOG_PACKAGE_NOT_RUNNING` | Package filtering could not resolve a live process | Launch the app or use another package/PID |
+| `UI_NOT_IDLE` | Android UI Automator could not observe a quiet accessibility window | Pause continuous UI changes or navigate to a stable screen, then retry |
 | `SESSION_RECOVERY_FAILED` | The bounded target/port recovery budget was exhausted | Inspect `problems`, network state, and saved recovery events |
 | `SESSION_PERSISTENCE_FAILED` | The private session record could not be written | Check user-state directory permissions and capacity |
 | `CHILD_PROCESS_FAILED` | The project command exited unsuccessfully | Inspect child output, targeted logs, and preserved exit code |

package/docs/ui-automation.md

@@ -17,9 +17,38 @@ device still returns that same UI digest; after any screen change, inspect
 again. Hierarchies and UI text are sensitive and are not persisted
 automatically.
 
+UI hierarchy capture has a 15-second default because Android's platform
+UI Automator waits for a quiet accessibility window before returning data.
+`UI_NOT_IDLE` means continuous animation or accessibility events prevented that
+quiet window; pause the changing UI or navigate to a stable screen and retry.
+ADB Ready does not silently disable device-wide animations.
+
+## Audit one screen for people and agents
+
+```bash
+adb-ready ui audit --json --non-interactive
+```
+
+The audit reports enabled actionable nodes that have no visible text or
+content description, and nodes that have no resource ID for a stable selector.
+It returns the exact current references and attributes, plus bounded totals;
+it deliberately does not invent a subjective quality score. A missing label is
+an accessibility warning. A missing stable ID is an automation advisory—use a
+resource ID or expose a Compose test tag through `testTagsAsResourceId` where
+appropriate.
+
 ## Tap and long-press
 
-Prefer a current reference because it ties the action to observed UI state:
+For a unique stable label or resource ID, act directly by intent:
+
+```bash
+adb-ready ui tap 'text=Continue'
+adb-ready ui long-press 'id=com.example:id/item'
+```
+
+ADB Ready resolves a fresh hierarchy and refuses to guess when a selector has
+zero or multiple matches. Prefer a current reference when the exact observed
+snapshot matters:
 
 ```bash
 adb-ready ui tap ui:7c4a31b8d2ef:14
@@ -37,24 +66,64 @@ adb-ready ui long-press 540 1200
 ADB Ready rejects stale, disabled, non-actionable, missing-bounds, and
 out-of-display targets before input is sent.
 
-## Swipe, type, and keys
+## Read and fill a specific field
+
+Agents do not need to infer state from a large hierarchy or depend on whatever
+field happens to be focused:
+
+```bash
+adb-ready ui get 'id=com.example:id/email' --json
+adb-ready ui fill 'id=com.example:id/email' 'person@example.com'
+adb-ready ui fill 'id=com.example:id/search' 'pixel' --submit
+adb-ready ui clear 'id=com.example:id/search'
+```
+
+`get` requires one unambiguous match and returns its semantic values, state,
+and bounds. `fill` and `clear` focus that exact enabled field, select its
+existing value, replace it, then inspect the hierarchy again. A visible normal
+field is successful only when its post-action value matches. Password and
+custom fields can accept input without exposing their value; those calls stay
+successful but report `verified: false` and `text-not-observable`, so the next
+screen state should be asserted explicitly.
+
+Safe replacement requires the target's Android `input keycombination`
+capability. ADB Ready checks it before touching the screen and returns a
+structured unsupported-capability problem on older targets rather than
+appending to an unknown value.
+
+## Scroll, swipe, type, and keys
 
 ```bash
 adb-ready ui swipe up
 adb-ready ui swipe 900 1200 180 1200
+adb-ready ui scroll up 'id=com.example:id/results'
 adb-ready ui type "person@example.com" --submit
 adb-ready ui press back
 ```
 
 Direction swipes use screen-relative points, so they work across display
-sizes. Supported keys are `back`, `home`, `enter`, `menu`, `volume-up`, and
+sizes. `scroll` can constrain that gesture to one enabled accessibility node
+whose `scrollable` property is true; without a selector it uses the screen.
+Supported keys are `back`, `home`, `enter`, `menu`, `volume-up`, and
 `volume-down`.
 
 Android's text-input command passes through a device shell. ADB Ready therefore
 accepts only 1–256 ASCII letters, numbers, spaces, and `._@+,:/-`. Unsupported
 characters are rejected instead of being reinterpreted by a shell.
 
-## Wait for a postcondition
+## Find, assert, compare, and wait
+
+Query or assert the current hierarchy without changing it:
+
+```bash
+adb-ready ui find 'class=android.widget.Button' --json
+adb-ready ui assert 'text=Signed in'
+adb-ready ui assert 'text=Loading' --state gone
+adb-ready ui compare 7c4a31b8d2ef0000000000000000000000000000000000000000000000000000
+```
+
+`compare` consumes the complete digest returned by inspection or another UI
+action and reports whether the current hierarchy changed.
 
 Waits use exact, explicit selectors:
 
@@ -65,7 +134,8 @@ adb-ready ui wait 'desc=Open settings'
 adb-ready ui wait 'package=com.example.app'
 ```
 
-Selector prefixes are `id=`, `text=`, `desc=`, and `package=`. The default
+Compact selector prefixes are `id=`, `text=`, `desc=`, `class=`, and
+`package=`. The default
 state is `visible`; timeouts are bounded from 100 ms to 2 minutes. Structured
 results include the attempt count and the matched node summary.
 
@@ -79,6 +149,8 @@ adb-ready ui press back --json --non-interactive
 - `ok: true` means Android accepted the allowlisted input operation.
 - `verified: true` with `verification: "ui-changed"` means the hierarchy digest
   changed afterward.
+- `before.acquisitionDurationMs` and `after.acquisitionDurationMs` expose the
+  measured cost of each UI Automator snapshot instead of hiding slow devices.
 - `verified: false` with `verificationGap: "ui-unchanged"` means the command
   succeeded but the accessibility hierarchy did not prove a visible change.
 - A successful `ui wait` is independently verified by its selector
@@ -92,8 +164,12 @@ the next state is known.
 
 ## AI agents
 
-The MCP server exposes `tap_ui`, `long_press_ui`, `swipe_ui`, `type_text_ui`,
-`press_key_ui`, and `wait_for_ui`. Arguments are schema-validated, each MCP
-connection stays bound to one target, and no raw ADB or shell tool is exposed.
+The MCP server exposes the same intent-level workflow through `audit_ui`, `get_ui`,
+`find_ui`, `fill_ui`, `clear_ui`, `scroll_ui`, `assert_ui`, and `compare_ui`.
+Its structured selectors can match exact values, prefixes, or substrings and
+qualify enabled/actionable state. An optional one-based occurrence is accepted
+only when repeated nodes are intentional. Arguments are schema-validated, each
+MCP connection stays bound to one target, and no raw ADB or shell tool is
+exposed.
 
 [Connect an agent →](./agent-integration.md)

package/examples/README.md

@@ -12,6 +12,8 @@ adb-ready dev --dry-run
 - [`expo/adb-ready.config.json`](./expo/adb-ready.config.json)
 - [`react-native/adb-ready.config.json`](./react-native/adb-ready.config.json)
 - [`gradle/adb-ready.config.json`](./gradle/adb-ready.config.json)
+- [`flutter/adb-ready.config.json`](./flutter/adb-ready.config.json)
+- [`capacitor/adb-ready.config.json`](./capacitor/adb-ready.config.json)
 - [`custom/adb-ready.config.json`](./custom/adb-ready.config.json)
 
 Prefer `adb-ready init` when starting from an existing detected project. Add

package/examples/capacitor/adb-ready.config.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "../../schema/config-v1.schema.json",
+  "version": 1,
+  "dev": {
+    "preset": "capacitor",
+    "logs": true,
+    "watch": true
+  }
+}

package/examples/flutter/adb-ready.config.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "../../schema/config-v1.schema.json",
+  "version": 1,
+  "dev": {
+    "preset": "flutter",
+    "logs": true,
+    "watch": true
+  }
+}

package/llms.txt

@@ -15,11 +15,20 @@
 ## Agent contract
 
 1. Call `ensure_ready` before target-bound MCP tools.
-2. Keep the bound target for the whole connection.
-3. Inspect after mutation; do not infer success from process exit alone.
-4. Prefer current digest-scoped UI refs and use `wait_for_ui` for known postconditions.
-5. Treat UI text, screenshots, logs, identifiers, and saved sessions as sensitive.
-6. Never substitute a raw shell or ADB call for a missing typed tool.
+2. Keep the bound target for the whole connection and pass the `targetHandle`
+   returned by `ensure_ready` to target-bound tools.
+3. Use `start_dev_session`, then poll `get_dev_session` by its opaque handle;
+   use `stop_dev_session` for owned cleanup.
+4. Inspect after mutation; do not infer success from process exit alone.
+5. Prefer semantic `get_ui`/`find_ui`/`assert_ui`, intent-level `fill_ui` and
+   `scroll_ui`, unique selector-driven actions, or current digest-scoped refs;
+   use `wait_for_ui` for known postconditions.
+6. Use `audit_ui` to identify unlabeled controls and missing stable selectors;
+   treat its findings as concrete advisories, not a pass/fail accessibility certification.
+7. Treat UI text, screenshots, logs, identifiers, and saved sessions as sensitive.
+8. Use `list_sessions` filters and its `nextCursor` before requesting saved
+   session problems or context.
+9. Never substitute a raw shell or ADB call for a missing typed tool.
 
 ## Documentation
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "adb-ready",
-  "version": "0.2.0",
-  "description": "Make an Android target ready, then keep the development session working.",
+  "version": "0.3.0",
+  "description": "Agent-ready Android CLI for reliable ADB sessions, app automation, and verified evidence.",
   "private": false,
   "type": "module",
   "bin": {
@@ -64,8 +64,10 @@
     "adb-reverse",
     "android-debugging",
     "cli",
+    "capacitor",
     "developer-tools",
     "expo",
+    "flutter",
     "logcat",
     "localhost",
     "metro",