deepadb 1.0.8 → 1.1.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Jason
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 Jason
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,8 +1,8 @@
 # DeepADB
 
-MCP (Model Context Protocol) server providing full Android Debug Bridge (ADB) integration with Claude. Enables Claude to directly interact with connected Android devices — inspecting state, running commands, managing apps, capturing logs, controlling device settings, analyzing UI hierarchies, recording screens, managing emulators, running structured test sessions, orchestrating multi-device operations, capturing network traffic, running CI pipelines, auditing accessibility, detecting performance regressions, executing cloud device farm tests, debugging over WiFi, building projects, and managing community plugins.
+MCP (Model Context Protocol) server providing full Android Debug Bridge (ADB) integration for AI agents. Enables MCP clients to directly interact with connected Android devices — inspecting state, running commands, managing apps, capturing logs, controlling device settings, analyzing UI hierarchies, recording screens, managing emulators, running structured test sessions, orchestrating multi-device operations, capturing network traffic, running CI pipelines, auditing accessibility, detecting performance regressions, executing cloud device farm tests, debugging over WiFi, building projects, and managing community plugins.
 
-**174 tools, 4 resources, and 4 prompts across 43 modules** — the most comprehensive ADB MCP server available, with triple transport (stdio + HTTP/SSE + WebSocket), optional GraphQL API, defense-in-depth security, modem firmware analysis, workflow marketplace, AT command interface with multi-chipset support, RIL message interception, device profiling, baseband/modem integration, automated test generation, OTA update monitoring, SELinux auditing, thermal/power profiling, network device discovery, visual regression detection, workflow orchestration, accessibility auditing, and contextual truncation.
+**180 tools, 4 resources, and 4 prompts across 43 modules** — the most comprehensive ADB MCP server available, with triple transport (stdio + HTTP/SSE + WebSocket), optional GraphQL API, defense-in-depth security, modem firmware analysis, workflow marketplace, AT command interface with multi-chipset support, RIL message interception, device profiling, baseband/modem integration, automated test generation, OTA update monitoring, SELinux auditing, thermal/power profiling, network device discovery, visual regression detection, workflow orchestration, accessibility auditing, and contextual truncation.
 
 ## Architecture
 
@@ -16,7 +16,7 @@ MCP (Model Context Protocol) server providing full Android Debug Bridge (ADB) in
 │               DeepADB Server                     │
 │                                                  │
 │  ┌─────────────────────────────────────────────┐ │
-│  │           Tool Modules (41)                 │ │
+│  │           Tool Modules (43)                 │ │
 │  │  device │ shell │ packages │ files │ logs   │ │
 │  │  diagnostics │ ui │ build │ health          │ │
 │  │  wireless │ control │ logcat-watch          │ │
@@ -78,15 +78,15 @@ DeepADB operates in two modes, auto-detected at startup:
 ```
 AI Agent (PC) ←→ MCP ←→ DeepADB (PC) ←→ ADB (USB) ←→ Android Device
 ```
-Standard mode: DeepADB runs on a PC/Mac/Linux host and communicates with the device over USB via ADB. All 174 tools work through the ADB bridge with automatic retry on transient failures.
+Standard mode: DeepADB runs on a PC/Mac/Linux host and communicates with the device over USB via ADB. All 180 tools work through the ADB bridge with automatic retry on transient failures.
 
 ### On-Device Mode — direct local execution
 ```
 AI Agent (Termux) ←→ MCP (stdio/HTTP) ←→ DeepADB (Termux) ←→ sh/su (local)
 ```
-When DeepADB runs directly on the Android device (e.g., inside Termux), it auto-detects the environment and switches to `LocalBridge`. Commands execute directly via `sh`/`su` — no ADB server, no USB, no serialization overhead. All 174 tools work identically, with significantly lower latency.
+When DeepADB runs directly on the Android device (e.g., inside Termux), it auto-detects the environment and switches to `LocalBridge`. Commands execute directly via `sh`/`su` — no ADB server, no USB, no serialization overhead. All 180 tools work identically, with significantly lower latency.
 
-**Validated on hardware:** 235/235 tests pass on-device (Pixel 6a, Android 16, Termux + Magisk + QEMU 10.2.1). Includes 27 QEMU/KVM virtualization tests covering setup detection, disk image lifecycle, resource budget reporting, Alpine Linux VM boot with KVM acceleration, big.LITTLE CPU topology detection, guest ADB connectivity error handling, and clean VM shutdown. QEMU tests auto-skip in ADB mode (207 passed, 5 skipped).
+**Validated on hardware:** 257/257 tests pass on Pixel 6a (Android 16, Termux + Magisk + QEMU 10.2.1) in on-device mode with DA_TEST_PIN. Includes QEMU/KVM virtualization tests covering setup detection, disk image lifecycle, resource budget reporting, Alpine Linux VM boot with KVM acceleration, big.LITTLE CPU topology detection, guest ADB connectivity error handling, and clean VM shutdown. In ADB mode: 235 total (230 passed with DA_TEST_PIN, 5 QEMU tests auto-skip).
 
 **Privilege escalation:** In ADB mode, all shell commands run as uid=2000 (the `shell` user) which has system-level permissions. In Termux, commands run as a regular app user. LocalBridge automatically elevates privileged commands through `su` when root (Magisk) is available:
 - **Command allowlist:** 16 system commands (`settings`, `dumpsys`, `am`, `input`, `screencap`, `screenrecord`, `uiautomator`, `app_process`, `getenforce`, `setenforce`, `cmd`, `pm`, `wm`, `svc`, `ip`, `ifconfig`) are routed through `su -c` to match ADB-mode behavior.
@@ -136,7 +136,7 @@ DA_GRAPHQL_PORT=4000 npm start
 }
 ```
 
-## Available Tools (174)
+## Available Tools (180)
 
 ### Health (1 tool)
 - `adb_health_check` — Comprehensive toolchain validation: ADB binary, server, device connection, authorization, root access, and storage writability
@@ -150,13 +150,15 @@ DA_GRAPHQL_PORT=4000 npm start
 - `adb_shell` — Execute arbitrary shell commands with configurable timeout (security-checked)
 - `adb_root_shell` — Execute commands as root via su (requires rooted device, security-checked)
 
-### Packages (10 tools)
+### Packages (12 tools)
 - `adb_install` — Install APK with replace/downgrade options
 - `adb_uninstall` — Remove package with optional data retention
 - `adb_list_packages` — List packages filtered by name or type (all/system/third-party)
 - `adb_package_info` — Detailed package info (version, permissions, paths)
 - `adb_clear_data` — Clear all app data and cache
-- `adb_grant_permission` — Grant runtime permissions
+- `adb_grant_permission` — Grant a runtime permission to a package
+- `adb_revoke_permission` — Revoke a runtime permission from a package (reset permission state for testing denial flows)
+- `adb_list_permissions` — List all declared and granted permissions for a package, filterable by granted/denied
 - `adb_force_stop` — Force-stop an app immediately
 - `adb_start_app` — Launch an app by package name (resolves launcher activity)
 - `adb_restart_app` — Force-stop then re-launch in one call (configurable delay)
@@ -190,13 +192,15 @@ DA_GRAPHQL_PORT=4000 npm start
 - `adb_crash_logs` — ANR traces and tombstone crash dumps from /data/anr/ and /data/tombstones/
 - `adb_heap_dump` — Capture heap dump (.hprof) from a running process for memory analysis
 
-### UI (8 tools)
+### UI (10 tools)
 - `adb_screencap` — Take screenshot with filename sanitization, saves locally
+- `adb_screencap_annotated` — Screenshot with UI element bounding boxes and numbered labels composited onto the PNG. Returns annotated image path plus a text legend. Ideal for LLM workflows that reference elements by number
 - `adb_current_activity` — Get focused activity and top window stack
 - `adb_input` — Send tap, swipe, text, or keyevent input
 - `adb_start_activity` — Launch activities by intent or component name
-- `adb_ui_dump` — Dump full UI hierarchy with parsed element data, coordinates, and interaction flags
+- `adb_ui_dump` — Dump full UI hierarchy. Supports three output formats: `text` (default, human-readable), `tsv` (compact tab-separated for token-efficient automation loops), `xml` (raw uiautomator XML)
 - `adb_ui_find` — Search UI hierarchy by text, resource-id, or content-description (returns tap coordinates)
+- `adb_screen_state` — Combined screen state in one call: foreground activity, screen dimensions and density, orientation, battery level, and a TSV list of interactive elements. Replaces 3–4 separate tool calls
 - `adb_screenrecord_start` — Start recording the device screen (1-180s, stored on device)
 - `adb_screenrecord_stop` — Stop recording and pull the mp4 video file locally
 
@@ -206,7 +210,7 @@ DA_GRAPHQL_PORT=4000 npm start
 - `adb_wifi` — Enable or disable WiFi
 - `adb_mobile_data` — Enable or disable mobile data
 - `adb_location` — Set location mode (off/sensors/battery/high)
-- `adb_screen` — Wake, sleep, toggle, or unlock (swipe) the screen
+- `adb_screen` — Wake, sleep, toggle, lock, or unlock the screen. Lock verifies keyguard state via `dumpsys window`. Unlock uses `wm dismiss-keyguard` (works for swipe keyguards); supply `pin` to perform the full PIN entry sequence: wakes screen, swipes up to reveal keypad, types PIN, confirms, and verifies the keyguard sleep token was released
 - `adb_settings_get` — Read any Android setting from system/secure/global namespace
 - `adb_settings_put` — Write any Android setting with read-back verification
 - `adb_reboot` — Reboot device (normal, recovery, or bootloader mode)
@@ -248,20 +252,22 @@ DA_GRAPHQL_PORT=4000 npm start
 - `adb_multi_compare` — Run a command on all devices and highlight output differences
 - `adb_multi_test` — Comparative test workflow: run predefined diagnostic profiles (firmware/security/network/identity/full) or custom command lists across all devices including QEMU guests, compare per-check, report matches and differences
 
-### Input Gestures & UI Automation (13 tools)
+### Input Gestures & UI Automation (15 tools)
 - `adb_input_drag` — Drag from point A to point B (uses `draganddrop` with swipe fallback for older Android)
+- `adb_input_fling` — High-velocity fling gesture for momentum-scrolling through lists and paged views (configurable duration 20-200ms)
 - `adb_input_long_press` — Long press at coordinates with configurable hold duration
 - `adb_input_double_tap` — Double tap with configurable interval between taps
 - `adb_input_text` — Dedicated text input with space/special character handling
 - `adb_open_url` — Open a URL on the device via VIEW intent
 - `adb_orientation` — Get or set screen orientation (auto/portrait/landscape/reverse)
 - `adb_clipboard` — Read or write device clipboard
+- `adb_input_pinch` — Multi-touch pinch (zoom out) or spread (zoom in) gesture. Two fingers move symmetrically around a center point. Layered injection: parallel `input swipe` (universal, no root) or raw `sendevent` MT Type B protocol (true multi-touch, root required). Auto-detects touchscreen device and capabilities via `getevent -p`. Configurable center, radius, duration, angle, and interpolation steps
 - `adb_tap_element` — Find element by text/resource-id/content-description and tap its center
 - `adb_wait_element` — Poll UI hierarchy until an element appears or disappears (configurable timeout/poll interval)
 - `adb_wait_stable` — Poll until consecutive UI dumps match (screen stabilization after transitions)
 - `adb_scroll_until` — Scroll repeatedly until a target element is found, with optional auto-tap
 - `adb_screenshot_compressed` — Capture screenshot with size/quality metadata for token-efficient workflows
-- `adb_batch_actions` — Execute multiple input actions (tap/swipe/long_press/double_tap/keyevent/text/drag/back/home/sleep) in a single tool call with security validation
+- `adb_batch_actions` — Execute multiple input actions (tap/swipe/fling/long_press/double_tap/keyevent/text/drag/pinch/back/home/sleep) in a single tool call with security validation
 
 ### Device Awareness (3 tools)
 - `adb_screen_size` — Screen resolution, display density (DPI), aspect ratio, and DP width in one call
@@ -437,7 +443,7 @@ Full view tree capture via `uiautomator dump` with parsed XML extraction. Return
 Multi-layered security activated via `DA_SECURITY=true`. Provides command blocklist/allowlist filtering, rate limiting (commands per minute), and audit logging with automatic credential redaction. Security checks are integrated into `adb_shell`, `adb_root_shell`, `adb_multi_shell`, `adb_multi_compare`, `adb_input`, `adb_batch_actions`, and `adb_start_activity`. Configurable via environment variables for different deployment scenarios.
 
 ### Input Sanitization
-All tools that interpolate user-supplied parameters into shell command strings validate inputs against shell metacharacters before execution. Package names, property keys, service names, setting keys, test identifiers, network interface names, and tcpdump filters are all validated through a centralized `validateShellArg()` function that rejects `;`, `|`, `&`, `$`, backticks, parentheses, and other injection vectors. File paths use single-quoted shell escaping to prevent `$()` command substitution. The `adb_input` tool applies type-specific validation: `tap`/`swipe` accept only numeric coordinates, `keyevent` accepts only alphanumeric keycodes, and `text` is shell-escaped for literal delivery. The `adb_batch_actions` tool enforces the same per-action-type validation (digits-only for coordinates, alphanumeric for keycodes, shell-escape for text) and routes every assembled command through the security middleware. Deserialized JSON from snapshot files is validated before shell interpolation. Every `z.number()` parameter across all 174 tools has explicit `.min()/.max()` Zod bounds to prevent resource exhaustion from extreme values. The LocalBridge has explicit handlers for every ADB subcommand used by tool modules, preventing unquoted fallthrough to the default shell handler. In on-device mode, privilege escalation uses a frozen 16-command allowlist and restricted-path regex — the elevation set is `ReadonlySet` + `Object.freeze`, not configurable at runtime. The HTTP/SSE transport denies cross-origin requests by default (configurable via `DA_HTTP_CORS_ORIGIN`), the plugin registry verifies SHA-256 integrity hashes and prevents path traversal via directory containment checks, and the workflow engine enforces step count (200), sleep duration (5 min), and repeat iteration (100) limits. Fetch helpers enforce a 5 MB response body limit. Getprop output parsing handles Windows `\r\n` line endings via `.trim()` before regex matching, and dual SIM slot counts are capped at 4 to prevent resource exhaustion from corrupted device properties.
+All tools that interpolate user-supplied parameters into shell command strings validate inputs against shell metacharacters before execution. Package names, property keys, service names, setting keys, test identifiers, network interface names, and tcpdump filters are all validated through a centralized `validateShellArg()` function that rejects `;`, `|`, `&`, `$`, backticks, parentheses, and other injection vectors. File paths use single-quoted shell escaping to prevent `$()` command substitution. The `adb_input` tool applies type-specific validation: `tap`/`swipe` accept only numeric coordinates, `keyevent` accepts only alphanumeric keycodes, and `text` is shell-escaped for literal delivery. The `adb_batch_actions` tool enforces the same per-action-type validation (digits-only for coordinates, alphanumeric for keycodes, shell-escape for text) and routes every assembled command through the security middleware. Deserialized JSON from snapshot files is validated before shell interpolation. Every `z.number()` parameter across all 180 tools has explicit `.min()/.max()` Zod bounds to prevent resource exhaustion from extreme values. The LocalBridge has explicit handlers for every ADB subcommand used by tool modules, preventing unquoted fallthrough to the default shell handler. In on-device mode, privilege escalation uses a frozen 16-command allowlist and restricted-path regex — the elevation set is `ReadonlySet` + `Object.freeze`, not configurable at runtime. The HTTP/SSE transport denies cross-origin requests by default (configurable via `DA_HTTP_CORS_ORIGIN`), the plugin registry verifies SHA-256 integrity hashes and prevents path traversal via directory containment checks, and the workflow engine enforces step count (200), sleep duration (5 min), and repeat iteration (100) limits. Fetch helpers enforce a 5 MB response body limit. Getprop output parsing handles Windows `\r\n` line endings via `.trim()` before regex matching, and dual SIM slot counts are capped at 4 to prevent resource exhaustion from corrupted device properties.
 
 ### Multi-Device Orchestration
 Run commands, install APKs, and compare outputs across multiple connected devices in parallel. Essential for comparative testing across Android versions and device models.
@@ -527,7 +533,7 @@ Scans the local network for ADB-enabled devices via ARP table queries and option
 On-device virtual machine management using QEMU with KVM hardware acceleration. Enables running guest Android VMs directly on the physical device — a capability unique to DeepADB. Dynamic resource allocation auto-detects host CPU cores and physical RAM, reserving 1 core and 35% of memory for the host OS to prevent starvation. Multi-VM support tracks resource consumption across concurrent VMs, refusing new VMs when the pool is exhausted rather than degrading host performance. Disk image management with qcow2 (sparse, snapshot-capable) and raw formats. ADB port forwarding to guest VMs enables DeepADB's full tool suite to target both host and guest devices simultaneously. Process lifecycle tracked via the centralized cleanup registry with SIGTERM/SIGKILL shutdown. Path containment verification on all image operations prevents directory traversal.
 
 ### ToolContext Architecture
-All 41 tool modules receive a unified `ToolContext` dependency bundle containing server, bridge, deviceManager, logger, security, and config. Adding new cross-cutting dependencies requires no module signature changes.
+All 43 tool modules receive a unified `ToolContext` dependency bundle containing server, bridge, deviceManager, logger, security, and config. Adding new cross-cutting dependencies requires no module signature changes.
 
 ## Environment Variables
 
@@ -580,20 +586,20 @@ DeepADB/
 │   │   ├── health.ts           # Toolchain health check (1 tool)
 │   │   ├── device.ts           # Device info and properties (3 tools)
 │   │   ├── shell.ts            # Shell and root command execution (2 tools)
-│   │   ├── packages.ts         # App lifecycle, install, permissions, intents (10 tools)
+│   │   ├── packages.ts         # App lifecycle, install, permissions, intents (12 tools)
 │   │   ├── files.ts            # Push, pull, ls, cat (4 tools)
 │   │   ├── logs.ts             # Logcat snapshots — filtered (3 tools)
 │   │   ├── logcat-watch.ts     # Persistent logcat with ring buffer and poll (4 tools)
 │   │   ├── diagnostics.ts      # dumpsys, telephony, battery, network, perf, bugreport, crash logs, heap dump (9 tools)
-│   │   ├── ui.ts               # Screenshots, input, activity, UI hierarchy (6 tools)
+│   │   ├── ui.ts               # Screenshots, input, activity, UI hierarchy, annotated screencap, screen state (8 tools)
 │   │   ├── screen-record.ts    # Screen video recording start/stop (2 tools)
 │   │   ├── control.ts          # Airplane, WiFi, data, location, screen, settings, reboot (9 tools)
 │   │   ├── wireless.ts         # WiFi pairing, connect, disconnect, TCP/IP (4 tools)
 │   │   ├── forwarding.ts       # Port forwarding and reverse forwarding (3 tools)
 │   │   ├── emulator.ts         # AVD list, start, stop with on-device KVM/QEMU detection (3 tools)
-│   │   ├── qemu.ts             # QEMU/KVM VM management — setup, images, start, stop, status (5 tools)
+│   │   ├── qemu.ts             # QEMU/KVM VM management — setup, images, start, stop, status, guest ADB connect/disconnect/shell (8 tools)
 │   │   ├── testing.ts          # Structured test sessions with numbered steps (3 tools)
-│   │   ├── multi-device.ts     # Multi-device shell, install, compare (3 tools)
+│   │   ├── multi-device.ts     # Multi-device shell, install, compare, comparative testing (4 tools)
 │   │   ├── snapshot.ts         # Device state capture, compare, restore (3 tools)
 │   │   ├── network-capture.ts  # tcpdump start/stop, network connections (3 tools)
 │   │   ├── ci.ts               # CI wait-boot, device-ready, run-tests (3 tools)
@@ -603,7 +609,7 @@ DeepADB/
 │   │   ├── regression.ts       # Performance baseline and regression detection (3 tools)
 │   │   ├── device-farm.ts      # Firebase Test Lab integration via gcloud (3 tools)
 │   │   ├── registry.ts         # Community plugin registry search/install (3 tools)
-│   │   ├── at-commands.ts      # AT command modem interface, multi-chipset (4 tools)
+│   │   ├── at-commands.ts      # AT command modem interface, multi-chipset, cross-validation (5 tools)
 │   │   ├── screenshot-diff.ts  # Visual regression — screenshot baseline/diff (3 tools)
 │   │   ├── workflow.ts         # Declarative workflow orchestration engine (3 tools)
 │   │   ├── split-apk.ts        # App bundles, split APKs, APEX modules (4 tools)
@@ -628,6 +634,7 @@ DeepADB/
 │   │   ├── sanitize.ts         # Shell injection prevention — validateShellArg/validateShellArgs/shellEscape
 │   │   ├── chipset.ts          # Shared chipset family detection, modem path mapping, SIM config detection
 │   │   ├── fetch-utils.ts      # Shared HTTP helpers with 5 MB streaming response size limit
+│   │   ├── png-utils.ts        # Zero-dependency PNG decode/encode/draw primitives for screenshot annotation and diffing
 │   │   ├── ui-dump.ts          # Shared uiautomator XML capture with concurrent-safe paths, on-device /data/local/tmp routing, and cleanup
 │   │   ├── cleanup.ts          # Centralized process cleanup registry for SIGINT/SIGTERM/exit
 │   │   └── logger.ts           # stderr-safe logging (MCP-compliant)
@@ -635,6 +642,7 @@ DeepADB/
 │       └── config.ts           # Configuration, env vars, startup validation
 ├── package.json
 ├── tsconfig.json
+├── server.json                  # MCP Registry metadata (io.github.fullread/deepadb)
 ├── .gitignore
 ├── README.md
 ├── SECURITY.md                  # Threat model, security architecture, deployment hardening, vulnerability reporting
@@ -642,14 +650,14 @@ DeepADB/
 ├── LICENSE                      # MIT license
 ├── tests/
 │   ├── run-all.mjs              # Run all test suites sequentially with summary (tracks skipped counts)
-│   ├── test-hw.mjs              # Hardware core: health, identity, baseband, thermal, profiles, wireless firmware (33 tests)
+│   ├── test-hw.mjs              # Hardware core: health, identity, baseband, thermal, profiles, wireless firmware, crash analysis (34 tests)
 │   ├── test-shell-files.mjs     # Shell, filesystem, packages, diagnostics (24 tests)
-│   ├── test-ui-control.mjs      # UI hierarchy, screenshots, settings, input gestures, UI automation, device awareness, accessibility (31 tests)
+│   ├── test-ui-control.mjs      # UI hierarchy, screenshots, settings, input gestures, UI automation, device awareness, accessibility, screen lock/unlock, multi-touch (46 tests)
 │   ├── test-monitoring.mjs      # Logcat watchers, snapshots, OTA, regression, workflows (25 tests)
 │   ├── test-security.mjs        # Input sanitization, shell injection, AT command safety (25 tests)
 │   ├── test-lifecycle.mjs       # App lifecycle, file push/pull, input, port forwarding, screen recording, test sessions (22 tests)
-│   ├── test-analysis.mjs        # Thermal/snapshot/regression comparison, firmware diff, screenshot diff, test gen, RIL intercept, AT cross-validation (19 tests)
-│   ├── test-boundaries.mjs      # Zod bounds enforcement, input injection, error paths, sensitive data protection (28 tests)
+│   ├── test-analysis.mjs        # Thermal/snapshot/regression comparison, firmware diff, screenshot diff, test gen, RIL intercept, AT cross-validation, permission management (23 tests)
+│   ├── test-boundaries.mjs      # Zod bounds enforcement, input injection, error paths, sensitive data protection (31 tests)
 │   ├── test-qemu.mjs            # QEMU/KVM setup, image management, VM status, guest connectivity errors (13 on-device tests)
 │   ├── test-qemu-boot.mjs       # QEMU Alpine VM boot, KVM acceleration, topology detection, guest ADB connectivity (14 on-device tests)
 │   └── lib/

package/build/index.d.ts

@@ -3,7 +3,7 @@
  * DeepADB — MCP Server for Android Debug Bridge
  *
  * Entry point. Supports three transport modes (mutually exclusive):
- *   - stdio (default) — JSON-RPC over stdin/stdout for Claude Code
+ *   - stdio (default) — JSON-RPC over stdin/stdout for MCP clients (Claude Code, etc.)
  *   - HTTP/SSE — Set DA_HTTP_PORT to enable browser-based MCP clients
  *   - WebSocket — Set DA_WS_PORT to enable bidirectional streaming (requires `ws` package)
  *

package/build/index.js

@@ -3,7 +3,7 @@
  * DeepADB — MCP Server for Android Debug Bridge
  *
  * Entry point. Supports three transport modes (mutually exclusive):
- *   - stdio (default) — JSON-RPC over stdin/stdout for Claude Code
+ *   - stdio (default) — JSON-RPC over stdin/stdout for MCP clients (Claude Code, etc.)
  *   - HTTP/SSE — Set DA_HTTP_PORT to enable browser-based MCP clients
  *   - WebSocket — Set DA_WS_PORT to enable bidirectional streaming (requires `ws` package)
  *

package/build/middleware/output-processor.d.ts

@@ -1,7 +1,7 @@
 /**
  * Output Processor — Truncation, formatting, structured parsing, and binary handling.
  *
- * Sits between raw ADB output and what gets returned to Claude.
+ * Sits between raw ADB output and what gets returned to the MCP client.
  * Prevents context window blowout from verbose commands.
  */
 export declare class OutputProcessor {

package/build/middleware/output-processor.js

@@ -1,7 +1,7 @@
 /**
  * Output Processor — Truncation, formatting, structured parsing, and binary handling.
  *
- * Sits between raw ADB output and what gets returned to Claude.
+ * Sits between raw ADB output and what gets returned to the MCP client.
  * Prevents context window blowout from verbose commands.
  */
 import { config } from "../config/config.js";

package/build/middleware/png-utils.d.ts

@@ -0,0 +1,44 @@
+/**
+ * PNG Utilities — Zero-dependency PNG decode and encode for screenshot analysis and annotation.
+ *
+ * Provides pixel-level PNG decode (used by screenshot-diff.ts and ui.ts),
+ * PNG encode (used by ui.ts for annotated screenshots), and drawing primitives
+ * for compositing bounding boxes and number labels onto pixel buffers.
+ *
+ * No external image library dependencies — uses only Node.js built-ins (zlib, fs).
+ */
+/** Cycling color palette for element bounding box annotation. */
+export declare const ELEMENT_COLORS: ReadonlyArray<readonly [number, number, number]>;
+/**
+ * Draw a rectangle border on a pixel buffer (in-place).
+ * Coordinates are clamped to image bounds. Thickness applies inward from each edge.
+ */
+export declare function drawRect(pixels: Buffer, imgWidth: number, imgHeight: number, bpp: number, x1: number, y1: number, x2: number, y2: number, color: readonly [number, number, number], thickness?: number): void;
+/**
+ * Draw a filled label showing a number at pixel position (x, y).
+ * Background uses the provided color; foreground (digit pixels) auto-contrasts.
+ * Label is clamped to stay within image bounds.
+ * Each digit glyph is 5×7 px with 1 px padding on all sides.
+ */
+export declare function drawLabel(pixels: Buffer, imgWidth: number, imgHeight: number, bpp: number, x: number, y: number, num: number, bgColor: readonly [number, number, number]): void;
+/** Decoded PNG image: raw RGB or RGBA pixel data with dimensions. */
+export interface PngImage {
+    width: number;
+    height: number;
+    bytesPerPixel: number;
+    pixels: Buffer;
+}
+/**
+ * Decode a PNG file into raw pixel data.
+ * Handles RGBA (colorType 6) and RGB (colorType 2) — both produced by Android screencap.
+ * All 5 PNG row filter types (None, Sub, Up, Average, Paeth) are unfiltered.
+ * Returns null on any parse or decompression error — callers should handle gracefully.
+ */
+export declare function decodePngPixels(pngPath: string): PngImage | null;
+/**
+ * Encode a raw pixel buffer as a PNG file in memory.
+ * Uses filter type 0 (None) on every scanline and level-1 (fast) deflate.
+ * bpp must be 3 (RGB) or 4 (RGBA) to match the input data.
+ */
+export declare function encodePng(width: number, height: number, pixels: Buffer, bpp: 3 | 4): Buffer;
+//# sourceMappingURL=png-utils.d.ts.map

package/build/middleware/png-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"png-utils.d.ts","sourceRoot":"","sources":["../../src/middleware/png-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAyDH,iEAAiE;AACjE,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CASlE,CAAC;AAiBX;;;GAGG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAChE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAC9C,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EACxC,SAAS,SAAI,GACZ,IAAI,CAmBN;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAChE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EACjC,OAAO,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GACzC,IAAI,CA4CN;AAID,qEAAqE;AACrE,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAU,MAAM,CAAC;IACtB,MAAM,EAAS,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAS,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAkFhE;AAID;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,MAAM,CA0B3F"}

package/build/middleware/png-utils.js

@@ -0,0 +1,274 @@
+/**
+ * PNG Utilities — Zero-dependency PNG decode and encode for screenshot analysis and annotation.
+ *
+ * Provides pixel-level PNG decode (used by screenshot-diff.ts and ui.ts),
+ * PNG encode (used by ui.ts for annotated screenshots), and drawing primitives
+ * for compositing bounding boxes and number labels onto pixel buffers.
+ *
+ * No external image library dependencies — uses only Node.js built-ins (zlib, fs).
+ */
+import { readFileSync } from "fs";
+import { inflateSync, deflateSync } from "zlib";
+// ── CRC32 ─────────────────────────────────────────────────────────────
+const CRC32_TABLE = (() => {
+    const table = [];
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++) {
+            c = (c & 1) ? (0xEDB88320 ^ (c >>> 1)) : (c >>> 1);
+        }
+        table[n] = c >>> 0;
+    }
+    return table;
+})();
+function crc32(buf) {
+    let crc = 0xFFFFFFFF;
+    for (let i = 0; i < buf.length; i++) {
+        crc = ((CRC32_TABLE[(crc ^ buf[i]) & 0xFF] ?? 0) ^ (crc >>> 8)) >>> 0;
+    }
+    return (crc ^ 0xFFFFFFFF) >>> 0;
+}
+function makePngChunk(type, data) {
+    const lenBuf = Buffer.allocUnsafe(4);
+    lenBuf.writeUInt32BE(data.length, 0);
+    const typeBuf = Buffer.from(type, "ascii");
+    const crcBuf = Buffer.allocUnsafe(4);
+    crcBuf.writeUInt32BE(crc32(Buffer.concat([typeBuf, data])), 0);
+    return Buffer.concat([lenBuf, typeBuf, data, crcBuf]);
+}
+// ── 5×7 pixel font for digits 0–9 ─────────────────────────────────────
+/**
+ * Each digit: 7 rows, each row a 5-bit mask (MSB = leftmost pixel).
+ * Bit 16 (0b10000) = leftmost column, bit 1 (0b00001) = rightmost.
+ */
+const DIGIT_FONT = [
+    [14, 17, 17, 17, 17, 17, 14], // 0
+    [4, 12, 4, 4, 4, 4, 14], // 1
+    [14, 17, 1, 2, 4, 8, 31], // 2
+    [30, 1, 1, 14, 1, 1, 30], // 3
+    [2, 6, 10, 18, 31, 2, 2], // 4
+    [31, 16, 16, 30, 1, 1, 30], // 5
+    [14, 16, 16, 30, 17, 17, 14], // 6
+    [31, 1, 2, 4, 8, 8, 8], // 7
+    [14, 17, 17, 14, 17, 17, 14], // 8
+    [14, 17, 17, 15, 1, 1, 14], // 9
+];
+// ── Color palette ──────────────────────────────────────────────────────
+/** Cycling color palette for element bounding box annotation. */
+export const ELEMENT_COLORS = [
+    [255, 50, 50], // red
+    [50, 210, 50], // green
+    [50, 100, 255], // blue
+    [255, 200, 0], // yellow
+    [0, 210, 210], // cyan
+    [255, 100, 200], // pink
+    [220, 110, 0], // orange
+    [160, 50, 220], // purple
+];
+// ── Pixel operations ───────────────────────────────────────────────────
+/** Write one pixel into a packed row-major RGB/RGBA pixel buffer. No-op if x is out of range. */
+function setPixel(pixels, imgWidth, bpp, x, y, r, g, b) {
+    if (x < 0 || x >= imgWidth)
+        return;
+    const off = (y * imgWidth + x) * bpp;
+    pixels[off] = r;
+    pixels[off + 1] = g;
+    pixels[off + 2] = b;
+    if (bpp === 4)
+        pixels[off + 3] = 255;
+}
+/**
+ * Draw a rectangle border on a pixel buffer (in-place).
+ * Coordinates are clamped to image bounds. Thickness applies inward from each edge.
+ */
+export function drawRect(pixels, imgWidth, imgHeight, bpp, x1, y1, x2, y2, color, thickness = 2) {
+    x1 = Math.max(0, Math.min(x1, imgWidth - 1));
+    y1 = Math.max(0, Math.min(y1, imgHeight - 1));
+    x2 = Math.max(0, Math.min(x2, imgWidth - 1));
+    y2 = Math.max(0, Math.min(y2, imgHeight - 1));
+    const [r, g, b] = color;
+    for (let t = 0; t < thickness; t++) {
+        const top = y1 + t, bot = y2 - t, left = x1 + t, right = x2 - t;
+        if (top > bot || left > right)
+            break;
+        for (let x = left; x <= right; x++) {
+            setPixel(pixels, imgWidth, bpp, x, top, r, g, b);
+            setPixel(pixels, imgWidth, bpp, x, bot, r, g, b);
+        }
+        for (let y = top + 1; y < bot; y++) {
+            setPixel(pixels, imgWidth, bpp, left, y, r, g, b);
+            setPixel(pixels, imgWidth, bpp, right, y, r, g, b);
+        }
+    }
+}
+/**
+ * Draw a filled label showing a number at pixel position (x, y).
+ * Background uses the provided color; foreground (digit pixels) auto-contrasts.
+ * Label is clamped to stay within image bounds.
+ * Each digit glyph is 5×7 px with 1 px padding on all sides.
+ */
+export function drawLabel(pixels, imgWidth, imgHeight, bpp, x, y, num, bgColor) {
+    const text = num.toString();
+    const GLYPH_W = 5, GLYPH_H = 7;
+    const CHAR_W = 6; // glyph + 1 px gap between digits
+    const PAD = 1;
+    // Total label dims: pad on each side, glyphs side by side, no trailing gap
+    const labelW = text.length * CHAR_W - 1 + PAD * 2;
+    const labelH = GLYPH_H + PAD * 2;
+    // Clamp to image so label never partially overflows
+    const lx = Math.max(0, Math.min(x, imgWidth - labelW));
+    const ly = Math.max(0, Math.min(y, imgHeight - labelH));
+    const [bgR, bgG, bgB] = bgColor;
+    // Perceived brightness for contrast decision (ITU-R BT.601)
+    const bright = 0.299 * bgR + 0.587 * bgG + 0.114 * bgB;
+    const [fr, fg, fb] = bright < 140
+        ? [255, 255, 255]
+        : [0, 0, 0];
+    // Fill background rectangle
+    for (let dy = 0; dy < labelH && ly + dy < imgHeight; dy++) {
+        for (let dx = 0; dx < labelW && lx + dx < imgWidth; dx++) {
+            setPixel(pixels, imgWidth, bpp, lx + dx, ly + dy, bgR, bgG, bgB);
+        }
+    }
+    // Render each digit glyph
+    for (let ci = 0; ci < text.length; ci++) {
+        const digit = parseInt(text[ci], 10);
+        const glyph = DIGIT_FONT[digit] ?? DIGIT_FONT[0];
+        for (let row = 0; row < GLYPH_H; row++) {
+            const bits = glyph[row] ?? 0;
+            for (let col = 0; col < GLYPH_W; col++) {
+                if (bits & (16 >> col)) { // 16 = 0b10000; MSB-first 5-bit mask
+                    const px = lx + PAD + ci * CHAR_W + col;
+                    const py = ly + PAD + row;
+                    if (px < imgWidth && py < imgHeight) {
+                        setPixel(pixels, imgWidth, bpp, px, py, fr, fg, fb);
+                    }
+                }
+            }
+        }
+    }
+}
+/**
+ * Decode a PNG file into raw pixel data.
+ * Handles RGBA (colorType 6) and RGB (colorType 2) — both produced by Android screencap.
+ * All 5 PNG row filter types (None, Sub, Up, Average, Paeth) are unfiltered.
+ * Returns null on any parse or decompression error — callers should handle gracefully.
+ */
+export function decodePngPixels(pngPath) {
+    try {
+        const buf = readFileSync(pngPath);
+        // Verify full 8-byte PNG signature — rejects non-PNG files that happen to share partial magic bytes
+        const PNG_SIG = [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A];
+        if (buf.length < 8 || !PNG_SIG.every((b, i) => buf[i] === b))
+            return null;
+        let offset = 8;
+        let width = 0, height = 0, colorType = 0;
+        const idatChunks = [];
+        while (offset + 12 <= buf.length) {
+            const length = buf.readUInt32BE(offset);
+            if (offset + 12 + length > buf.length)
+                break;
+            const type = buf.slice(offset + 4, offset + 8).toString("ascii");
+            const data = buf.slice(offset + 8, offset + 8 + length);
+            if (type === "IHDR" && length >= 13) {
+                width = data.readUInt32BE(0);
+                height = data.readUInt32BE(4);
+                colorType = data[9];
+            }
+            else if (type === "IDAT") {
+                idatChunks.push(data);
+            }
+            else if (type === "IEND") {
+                break;
+            }
+            offset += 12 + length;
+        }
+        if (width === 0 || height === 0 || idatChunks.length === 0)
+            return null;
+        const bytesPerPixel = colorType === 6 ? 4 : colorType === 2 ? 3 : 0;
+        if (bytesPerPixel === 0)
+            return null; // unsupported colorType
+        // Defense-in-depth: reject absurd dimensions that would cause OOM.
+        // 10000×10000×4 = 400 MB pixel buffer — generous ceiling for any real screenshot.
+        const MAX_DIM = 10000;
+        if (width > MAX_DIM || height > MAX_DIM)
+            return null;
+        // Cap decompressed output to prevent zip-bomb decompression attacks.
+        // Expected size: (1 + width*bpp) * height — add 1% headroom for safety.
+        const expectedRawSize = (1 + width * bytesPerPixel) * height;
+        const maxInflateSize = Math.ceil(expectedRawSize * 1.01) + 1024;
+        const raw = inflateSync(Buffer.concat(idatChunks), { maxOutputLength: maxInflateSize });
+        const rowBytes = 1 + width * bytesPerPixel;
+        if (raw.length < rowBytes * height)
+            return null;
+        const pixels = Buffer.alloc(width * height * bytesPerPixel);
+        const prevRow = Buffer.alloc(width * bytesPerPixel);
+        for (let y = 0; y < height; y++) {
+            const rowStart = y * rowBytes;
+            const filterType = raw[rowStart];
+            const pixRowStart = y * width * bytesPerPixel;
+            for (let x = 0; x < width * bytesPerPixel; x++) {
+                let val = raw[rowStart + 1 + x] ?? 0;
+                const a = x >= bytesPerPixel ? pixels[pixRowStart + x - bytesPerPixel] : 0;
+                const b = prevRow[x];
+                const c = x >= bytesPerPixel ? prevRow[x - bytesPerPixel] : 0;
+                switch (filterType) {
+                    case 0: break; // None
+                    case 1:
+                        val = (val + a) & 0xFF;
+                        break; // Sub
+                    case 2:
+                        val = (val + b) & 0xFF;
+                        break; // Up
+                    case 3:
+                        val = (val + Math.floor((a + b) / 2)) & 0xFF;
+                        break; // Average
+                    case 4: { // Paeth
+                        const p = a + b - c;
+                        const pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+                        val = (val + (pa <= pb && pa <= pc ? a : pb <= pc ? b : c)) & 0xFF;
+                        break;
+                    }
+                    default: break; // Unknown filter — treat as None
+                }
+                pixels[pixRowStart + x] = val;
+            }
+            pixels.copy(prevRow, 0, pixRowStart, pixRowStart + width * bytesPerPixel);
+        }
+        return { width, height, bytesPerPixel, pixels };
+    }
+    catch {
+        return null; // Any decode failure is non-fatal for callers
+    }
+}
+// ── PNG encode ─────────────────────────────────────────────────────────
+/**
+ * Encode a raw pixel buffer as a PNG file in memory.
+ * Uses filter type 0 (None) on every scanline and level-1 (fast) deflate.
+ * bpp must be 3 (RGB) or 4 (RGBA) to match the input data.
+ */
+export function encodePng(width, height, pixels, bpp) {
+    const SIG = Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]);
+    const ihdr = Buffer.allocUnsafe(13);
+    ihdr.writeUInt32BE(width, 0);
+    ihdr.writeUInt32BE(height, 4);
+    ihdr[8] = 8; // bit depth
+    ihdr[9] = bpp === 4 ? 6 : 2; // colorType 6=RGBA, 2=RGB
+    ihdr[10] = 0; // compression (deflate)
+    ihdr[11] = 0; // filter method
+    ihdr[12] = 0; // no interlacing
+    // Prepend filter byte 0 (None) to each scanline
+    const rowSize = 1 + width * bpp;
+    const rawData = Buffer.allocUnsafe(rowSize * height);
+    for (let y = 0; y < height; y++) {
+        rawData[y * rowSize] = 0; // filter = None
+        pixels.copy(rawData, y * rowSize + 1, y * width * bpp, (y + 1) * width * bpp);
+    }
+    return Buffer.concat([
+        SIG,
+        makePngChunk("IHDR", ihdr),
+        makePngChunk("IDAT", deflateSync(rawData, { level: 1 })),
+        makePngChunk("IEND", Buffer.alloc(0)),
+    ]);
+}
+//# sourceMappingURL=png-utils.js.map