mobile-debug-mcp 0.34.0 → 0.35.0

package/CONTRIBUTING.md

@@ -0,0 +1,79 @@
+# Contributing
+
+Read the [development process](docs/specs/process.md) before planning, editing,
+or reviewing a change. Documentation and maintenance use its lightweight path;
+new capabilities and material contract changes require intent and specification
+approval. Automated contributors also start with [AGENTS.md](AGENTS.md).
+
+## Local development
+
+Use Node.js 22 or newer and npm. Platform tooling is needed only for the mobile
+operations you exercise; see [requirements and setup](README.md#requirements).
+
+```sh
+npm ci
+npm run build
+npm start
+```
+
+The TypeScript entrypoint is [src/server.ts](src/server.ts); registration and
+dispatch live in [src/server-core.ts](src/server-core.ts) and [src/server/](src/server/).
+The optional Java debugger bridge lives in
+[src/debugger/java/](src/debugger/java/). It is shipped as source and compiled
+on demand by the debugger; the TypeScript build does not compile Java.
+
+Platform operations are grouped under `src/manage/`, `src/interact/`,
+`src/observe/`, `src/debugger/`, and `src/system/`, with shared helpers in `src/utils/`.
+
+## Validation
+
+```sh
+npm run verify
+npm run test:device
+```
+
+`verify` runs lint, the TypeScript build, automated unit tests, and plugin
+consistency checks. Run applicable device checks for native or runtime changes;
+record which devices and behaviours actually ran. See the [process verification
+requirements](docs/specs/process.md#5-verify-and-report) for reporting failures,
+blocked checks, and unrun coverage. Documentation-only work needs diff, relative
+link/path, command, and consistency checks; builds and device tests are unnecessary.
+
+Load the [test-authoring skill](.agents/skills/test-authoring/SKILL.md) before
+changing tests, and the [MCP builder skill](.agents/skills/mcp-builder/SKILL.md)
+for installation or native toolchain work. Automated unit tests belong in
+`test/unit/`, automated device tests in `test/device/automated/`, and manual
+helpers in `test/device/manual/`.
+
+## Code structure
+
+Follow the [code structure and quality checks](docs/code-structure.md) for module
+ownership, enforced limits, and review of legacy exceptions. `npm run lint`
+includes ESLint, structural/type limits and ArchUnitTS dependency checks; CI runs
+the same checks. To diagnose a failure, run `npm run check:quality` or
+`npm run check:architecture` separately. Change a rule or reviewed exception only
+with the corresponding design rationale, rather than suppressing the failure.
+
+## Documentation conventions
+
+Use the [documentation index](docs/README.md) to place new material. Keep one
+page responsible for each contract and link to it from related guides. Keep
+setup in the root README, current tool contracts in `docs/tools/`, design records
+in `docs/specs/`, and measurements in `docs/benchmarks/`.
+
+Write guides around a reader's task: explain when to use the page, show a complete
+example where useful, and link to the likely next step. Keep agent usage
+workflows in the existing plugin skill and detailed contracts in the tool
+reference. Avoid duplicating the full navigation on every page; long references
+should offer task-based links to their own sections.
+
+Use one descriptive level-one heading per document and a logical heading
+hierarchy. Use relative links for repository files. Explain prerequisites before
+commands and distinguish examples, proposals, and verified behaviour. Keep
+historical approval and verification evidence dated; avoid chat-relative wording,
+agent handoff instructions, transient checkout status, and temporary log paths.
+Do not turn an earlier design decision into a current support or release claim.
+
+When usage changes, update the relevant tool reference, README, and changelog.
+When plugin metadata or its server pin changes, run `npm run sync:agent-plugin`
+and `npm run check:agent-plugin`; see the [plugin guide](agent-plugin/README.md).

package/README.md

@@ -1,56 +1,138 @@
 # Mobile Debug Tools
 [![npm version](https://img.shields.io/npm/v/mobile-debug-mcp.svg)](https://www.npmjs.com/package/mobile-debug-mcp)
 
-A minimal, secure MCP server for AI-assisted mobile development. Build, install, interact and inspect Android/iOS apps from an MCP-compatible client.
+Build, install, control, and inspect Android and iOS apps from an MCP-compatible
+client. Mobile Debug Tools connects your client to local device toolchains and
+provides UI actions, screenshots, logs, state assertions, and optional Android
+performance capture and runtime debugging.
+
+Android, iOS, and Kotlin Multiplatform projects are supported. Flutter and React
+Native have not been tested. Platform and device limitations are described in the
+[tool reference](docs/tools/TOOLS.md).
+
+## What you can use it for
+
+Mobile Debug Tools gives a coding agent access to a running app, so development
+can include feedback from the device as well as the source code. For example:
+
+- **Build and test a feature.** After adding a settings screen, build and install
+  the app, navigate to it, and check that its controls display and behave as
+  expected. See [app management](docs/tools/manage.md) and
+  [UI interactions and assertions](docs/tools/interact.md).
+- **Check a bug fix or regression.** Reproduce a sequence such as opening a form,
+  entering text and submitting it, then verify the resulting screen or control
+  state. Repeat the journey after a code change to check the outcome.
+- **Review the UI on a device.** Capture screenshots to inspect layout and visual
+  changes, or inspect the UI hierarchy for exposed labels and control state.
+  See [observations](docs/tools/observe.md).
+- **Investigate an app failure.** Collect logs, screenshots and a debug snapshot
+  around a failing action to understand what happened. [Evidence
+  correlation](docs/tools/correlated-evidence.md) links observations to the action.
+- **Investigate Android performance or runtime behaviour.** Capture a
+  [Perfetto trace](docs/tools/system-traces.md) during a slow flow, or attach the
+  [runtime debugger](docs/tools/debugger.md) to a debuggable app to inspect
+  breakpoints, call stacks and locals.
+
+## How it works
+
+Your agent client launches a local MCP server and communicates with it over
+stdio. The server translates tool calls into operations through Android's ADB
+or Apple's Xcode tools and idb, then returns device observations and action
+results to the client. It connects to emulators, simulators and supported
+physical devices through those toolchains.
+
+The agent plugin bundles the server configuration and usage skill. The same
+server can also be configured directly in an MCP client or run from a source
+checkout. See [code structure](docs/code-structure.md#module-ownership) for the
+implementation's module boundaries.
+
+## Start here
+
+Choose how to connect:
+
+1. **[Agent plugin](#agent-plugin) — Recommended.** Installs the server configuration
+   and usage skill together for supported agent clients.
+2. **[Direct MCP configuration](#mcp-configuration).** Connect the published server
+   to another MCP-compatible client.
+3. **[Manual setup](#manual-setup).** Build and run a local source checkout.
+
+Check the [requirements](#requirements) for your platform before installing.
 
-> **Support:**
-> * KMP
-> * Android
-> * iOS
-> * Flutter - not tested
-> * React native - not tested
+## Requirements
 
-Actions, screenshots, trees, and logs expose [correlated evidence](docs/tools/evidence.md)
-with explicit action references, phase timestamps, and conservative freshness.
+- Node.js >= 22
+- [Android SDK](https://developer.android.com/studio) (adb) for Android support
+- Xcode and its command-line tools on macOS for iOS support
+- [idb](https://github.com/facebook/idb) for iOS UI inspection and interaction
+- JDK 17+ for optional [Android runtime debugging](docs/tools/debugger.md)
 
-Android [system traces](docs/tools/system-traces.md) can bracket existing journeys
-and return local Perfetto artifacts with explicit correlation metadata.
+## Agent plugin
 
-Android [runtime debugging](docs/tools/debugger.md) supports explicit process attach,
-source breakpoints, bounded stacks/locals, stepping, resume and owned detach.
-JDK 17+ is optional and required only for debugger tools.
+The preferred setup for supported agent clients is the
+[agent plugin](agent-plugin/README.md). It installs the MCP server configuration
+and usage skill together. Choose your client below.
 
-## Requirements
+<details>
 
-- Node.js >= 18
-- [Android SDK](https://developer.android.com/studio) (adb) for Android support
-- Xcode command-line tools for iOS support
-- [idb](https://github.com/facebook/idb) for iOS device support
+<summary>Codex plugin</summary>
 
-## Environment Setup
+Install the plugin from this repository's marketplace:
 
-The server discovers Android and iOS tools automatically from standard locations by default. Manual environment setup is still supported, but it should be treated as the fallback for non-standard installs, overrides, or reproducible pinned toolchains.
+```bash
+codex plugin marketplace add clivejefferies/mobile-debug-tools
+codex plugin add mobile-debug-tools@mobile-debug-tools
+```
 
-Use explicit paths when:
-- you have multiple SDKs installed
-- the tools live outside standard locations
-- you want deterministic setup across machines
-- automatic discovery does not find the expected binary
+</details>
 
-Leave the variables unset when:
-- the tools are already on `PATH`
-- the standard Android and Xcode locations are enough
+<details>
 
-Common environment variables:
-- `ADB_PATH`: explicit path to `adb`
-- `ANDROID_SDK_ROOT` or `ANDROID_HOME`: Android SDK root
-- `XCRUN_PATH`: explicit path to `xcrun`
-- `MCP_IDB_PATH` or `IDB_PATH`: explicit path to `idb`
-- `GRADLE_JAVA_HOME` or `JAVA_HOME`: Java home for Gradle-backed operations
+<summary>Claude Code plugin</summary>
 
-For normal use, call `get_system_status` first. It reports the detected host, Android, and iOS toolchain state so the client can decide whether automatic discovery is sufficient or whether explicit overrides are needed.
+Install the plugin from this repository's marketplace:
 
-## MCP Configuration
+```bash
+claude plugin marketplace add clivejefferies/mobile-debug-tools
+claude plugin install mobile-debug-tools@mobile-debug-tools
+```
+
+</details>
+
+<details>
+
+<summary>Cursor plugin</summary>
+
+The repository includes a [Cursor marketplace](.cursor-plugin/marketplace.json).
+Teams and Enterprise admins can import the repository in Dashboard → Plugins & MCPs → Team
+Marketplaces. To test it locally, copy [agent-plugin](agent-plugin/) into
+`~/.cursor/plugins/local/mobile-debug-tools`, then reload Cursor.
+
+</details>
+
+Start a new chat or session after installation so the client loads the skill
+and MCP tools. Each plugin launches the published npm package locally and needs
+Node.js 22 or newer and the platform toolchains for your device. If you also
+registered the MCP server directly, disable that registration to avoid
+duplicate tools.
+
+## MCP configuration
+
+For a standard installation, add this stdio server to your client's MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "mobile-debug": {
+      "command": "npx",
+      "args": ["--yes", "mobile-debug-mcp"]
+    }
+  }
+}
+```
+
+If your client uses separate fields, choose stdio, set the command to `npx`, and
+supply `--yes` and `mobile-debug-mcp` as arguments. The examples below add optional
+path overrides; replace the placeholder paths before using them.
 
 <details>
 
@@ -63,7 +145,7 @@ Recommended when you want Android only, or when you want to make the Android too
   "mcpServers": {
     "mobile-debug": {
       "command": "npx",
-      "args": ["--yes","mobile-debug-mcp","server"],
+      "args": ["--yes", "mobile-debug-mcp"],
       "env": {
         "ADB_PATH": "/path/to/adb",
         "ANDROID_SDK_ROOT": "/path/to/android/sdk",
@@ -89,7 +171,7 @@ Recommended when you want iOS simulator or device support, or when `idb` lives i
   "mcpServers": {
     "mobile-debug": {
       "command": "npx",
-      "args": ["--yes","mobile-debug-mcp","server"],
+      "args": ["--yes", "mobile-debug-mcp"],
       "env": {
         "XCRUN_PATH": "/usr/bin/xcrun",
         "MCP_IDB_PATH": "/path/to/idb",
@@ -104,107 +186,52 @@ For iOS-only setups, `ADB_PATH` and `ANDROID_SDK_ROOT` are not required unless y
 
 </details>
 
-<details>
-
-<summary>Codex</summary>
-
-Use STDIO
-
-command: npx
-
-args: 
-* --yes
-* mobile-debug-mcp
-
-environment variables:
-* ADB_PATH: /path/to/adb
-* XCRUN_PATH: /usr/bin/xcrun
-* IDB_PATH: /path/to/idb
-* MCP_IDB_PATH: /path/to/idb
-* ANDROID_SDK_ROOT: /path/to/android/sdk
-* GRADLE_JAVA_HOME: /path/to/jdk
-* JAVA_HOME: /path/to/jdk
-
-If you are unsure whether the environment is configured correctly, run `get_system_status` first. It reports the detected host, Android, and iOS toolchain state in a structured form.
-
-</details>
-
-## Agent Plugin
+## Manual setup
 
-For clients that support Agent Plugins, the [agent-plugin](agent-plugin/README.md)
-package installs the MCP server configuration together with the existing usage
-skill. Direct npm/MCP configuration above remains supported.
+For a local source checkout, follow the [development setup](CONTRIBUTING.md#local-development)
+to install dependencies and build the server. Then configure your MCP client to
+launch that build over stdio:
 
-<details>
-
-<summary>Codex plugin</summary>
-
-Install the plugin from this repository's marketplace:
-
-```bash
-codex plugin marketplace add clivejefferies/mobile-debug-tools
-codex plugin add mobile-debug-tools@mobile-debug-tools
-```
-
-</details>
-
-<details>
-
-<summary>Claude Code plugin</summary>
-
-Install the plugin from this repository's marketplace:
-
-```bash
-claude plugin marketplace add clivejefferies/mobile-debug-tools
-claude plugin install mobile-debug-tools@mobile-debug-tools
+```json
+{
+  "mcpServers": {
+    "mobile-debug": {
+      "command": "node",
+      "args": ["/absolute/path/to/mobile-debug-mcp/dist/server.js"]
+    }
+  }
+}
 ```
 
-</details>
-
-<details>
-
-<summary>Cursor plugin</summary>
-
-The repository includes a [Cursor marketplace](.cursor-plugin/marketplace.json).
-Teams and Enterprise admins can import the repository in Dashboard → Plugins & MCPs → Team
-Marketplaces. To test it locally, copy [agent-plugin](agent-plugin/) into
-`~/.cursor/plugins/local/mobile-debug-tools`, then reload Cursor.
-
-</details>
-
-Start a new chat or session after installation so the client loads the skill
-and MCP tools. Each plugin launches the published npm package locally and needs
-Node.js 18 or newer and the platform toolchains for your device. If you also
-registered the MCP server directly, disable that registration to avoid
-duplicate tools.
+Replace the path with your checkout location. Rebuild after source changes.
 
-## Usage 
+## Environment setup
 
-Crash fixing:
-> I have a crash on the app, can you diagnose it, fix and validate using the mcp tools available
+The server discovers platform tools from standard locations and `PATH`. Leave
+path overrides unset for a standard installation. Use them for non-standard
+locations, multiple toolchains, or a pinned development environment.
 
-Feature building:
-> Add a button, hook into the repository and confirm API request successful
+| Variable | Purpose |
+| --- | --- |
+| `ADB_PATH` | Path to `adb`. |
+| `ANDROID_SDK_ROOT` or `ANDROID_HOME` | Android SDK root. |
+| `XCRUN_PATH` | Path to `xcrun`. |
+| `MCP_IDB_PATH` or `IDB_PATH` | Path to `idb`. |
+| `GRADLE_JAVA_HOME` or `JAVA_HOME` | Java home for Gradle-backed operations. |
 
-For actions that depend on a previously observed UI, use an optional
-`expectedState` from `get_ui_tree` on the same explicit device. The server checks
-a fresh snapshot immediately before input and returns `PRECONDITION_FAILED`
-with current UI evidence if the state changed. See
-[conditional actions](docs/tools/interact.md#conditional-actions) for supported
-tools, examples, and the limits of the check.
+After connecting the client, call `get_system_status` to check discovery and
+prerequisites. See [environment diagnostics](docs/tools/system.md) if a toolchain
+or device is unavailable.
 
-## Docs
+Android debugger errors include bounded, sanitized failure classifications and recovery guidance; see the [debugger guide](docs/tools/debugger.md#failure-diagnostics).
 
-Use `get_app_readiness` to observe loading, transitioning, settled, or unknown UI
-state, and `wait_for_app_ready` for a bounded wait. Existing UI waits can opt into
-`requireReady: true`. Results include evidence and uncertainty; see
-[app readiness](docs/tools/observe.md#app-readiness) for limits and examples.
+## Documentation
 
-- Tools: [Tools](docs/tools/TOOLS.md) — full input/response examples
-- Changelog: [Changelog](docs/CHANGELOG.md)
-- Agents: [AGENTS.md](AGENTS.md) — cold-start guidance for autonomous agents entering the public repo
-- Skills: [.agents/skills/README.md](.agents/skills/README.md) — portable Markdown skill packages for agents such as Copilot, Codex, Claude, or custom systems
+- [Documentation guide](docs/README.md) — find the guide for your task.
+- [Tool reference](docs/tools/TOOLS.md) — inputs, responses, examples, and shared principles.
+- [Contributing](CONTRIBUTING.md) — develop the server and run its checks.
+- [Changelog](docs/CHANGELOG.md) — release history.
 
 ## License
 
-Apache-2.0
+[Apache-2.0](LICENSE)

package/agent-plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-tools",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Mobile app debugging tools and usage guidance for Android and iOS agents.",
   "author": {
     "name": "mobile-debug-tools contributors"
@@ -12,7 +12,7 @@
       "command": "npx",
       "args": [
         "--yes",
-        "mobile-debug-mcp@0.34.0",
+        "mobile-debug-mcp@0.35.0",
         "server"
       ]
     }

package/agent-plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-tools",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Mobile app debugging tools and usage guidance for Android and iOS agents.",
   "repository": "https://github.com/clivejefferies/mobile-debug-tools",
   "license": "Apache-2.0",

package/agent-plugin/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-tools",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Mobile app debugging tools and usage guidance for Android and iOS agents.",
   "author": {
     "name": "mobile-debug-tools contributors"
@@ -14,7 +14,7 @@
       "command": "npx",
       "args": [
         "--yes",
-        "mobile-debug-mcp@0.34.0",
+        "mobile-debug-mcp@0.35.0",
         "server"
       ],
       "cwd": "${CURSOR_PLUGIN_ROOT}"

package/agent-plugin/.mcp.json

@@ -5,7 +5,7 @@
       "command": "npx",
       "args": [
         "--yes",
-        "mobile-debug-mcp@0.34.0",
+        "mobile-debug-mcp@0.35.0",
         "server"
       ],
       "cwd": "${PLUGIN_DATA}"

package/agent-plugin/README.md

@@ -1,17 +1,22 @@
 # Mobile Debug MCP agent plugin
 
-Install this directory as an Agent Plugins package in a client that supports
-both skills and stdio MCP servers. It provides the existing mobile-debug MCP
+[Documentation](../docs/README.md) · [Client installation](../README.md#agent-plugin)
+
+Use the [client installation instructions](../README.md#agent-plugin) to install
+the plugin. It supports clients with
+both skills and stdio MCP servers. It provides the mobile-debug MCP
 usage skill and launches the published `mobile-debug-mcp` npm package. The
-plugin requires Node.js 18 or newer, `npx`, and the platform toolchains needed
+plugin requires Node.js 22 or newer, `npx`, and the platform toolchains needed
 for the devices you want to use. The first launch may need npm registry access.
 The MCP process starts in the client-managed plugin data directory so npm does
 not resolve the source checkout as a local package when installed from this repo.
 
+## Versions and maintenance
+
 The server is pinned to the published npm version in `mcp.json`. The plugin's
 `plugin.json` version advances independently for guidance-only releases; do not
-change the server pin to an unpublished npm version. The skill in
-`skills/mobile-debug-mcp/SKILL.md` is shared by all three clients. Run
+change the server pin to an unpublished npm version. The
+[usage skill](skills/mobile-debug-mcp/SKILL.md) is shared by all three clients. Run
 `npm run sync:agent-plugin` after updating the plugin metadata or server pin to
 refresh the thin Codex, Claude Code, and Cursor manifests in this directory.
 The three marketplaces all point here and share one skill.
@@ -19,6 +24,11 @@ The packaged directory uses the skill's declared name, `mobile-debug-mcp`, as
 required by Agent Skills. `npm run check:agent-plugin` checks the packaged
 copies and configuration.
 
+## Using the plugin
+
+After installation, the [usage skill](skills/mobile-debug-mcp/SKILL.md) guides the
+agent through device selection, observation, interaction and verification.
+
 The usage skill prefers screenshots for routine visual checks and reserves
 hierarchy reads for semantic selection and structured assertions. Assertion
 timeouts must cover a fresh tree read as well as the expected app transition.
@@ -30,4 +40,4 @@ updating the skill does not update the pinned server or installed plugin.
 If you already configured the MCP server directly in your agent client, disable
 that separate registration when enabling this plugin to avoid duplicate tools.
 The direct npm installation remains available without this plugin. See the
-repository README for platform toolchain setup and `get_system_status` guidance.
+[repository README](../README.md#environment-setup) for platform toolchain setup and `get_system_status` guidance.

package/agent-plugin/mcp.json

@@ -4,7 +4,7 @@
     "mobile-debug-mcp": {
       "type": "stdio",
       "command": "npx",
-      "args": ["--yes", "mobile-debug-mcp@0.34.0", "server"],
+      "args": ["--yes", "mobile-debug-mcp@0.35.0", "server"],
       "cwd": "${PLUGIN_DATA}"
     }
   }

package/agent-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "mobile-debug-tools",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Mobile app debugging tools and usage guidance for Android and iOS agents.",
   "repository": "https://github.com/clivejefferies/mobile-debug-tools",
   "license": "Apache-2.0",

package/agent-plugin/skills/mobile-debug-mcp/SKILL.md

@@ -161,6 +161,13 @@ an older installed server may lack them. This requires JDK 17+ and a running,
 debuggable Android app. iOS and native debugging are unsupported. Keep ordinary
 navigation and UI verification on the existing interaction path.
 
+For routine debugger calls, opt into `responseMode: "compact"` to omit repeated
+`device`, `target` and `capabilities`. Default `debug` preserves full output;
+attach, capabilities and state remain full in either mode. Use `get_debugger_state`
+to recover the baseline. Errors, diagnostics, IDs, stop/execution state, limits,
+truncation and cleanup remain available. Compact output is not privacy redaction
+and does not establish execution recovery.
+
 1. Call `get_debugger_capabilities` with `platform: "android"`, explicit `deviceId`
    and `appId`. Inspect `supported`, prerequisites and candidate processes. Provide
    `processId` when ambiguous; general system health does not prove attach support.
@@ -176,12 +183,22 @@ navigation and UI verification on the existing interaction path.
    `get_debugger_locals` with `stopId`/`frameId` from the returned frame. Inspection
    is shallow and bounded; check availability and truncation. ART may return
    `EMPTY_OR_UNAVAILABLE_VARIABLE_METADATA`: an empty table does not prove that
-   the frame has no locals. Values can contain private data; report only what is
+   the frame has no locals. On Kotlin assignment lines, the local may not yet be
+   initialized or in its emitted variable scope; compare a stop after assignment
+   and compiler metadata before diagnosing a worker defect.
+   Values can contain private data; report only what is
    needed for the investigation.
 5. Use `step_debugger` (`kind: into/over/out`) or `resume_debugger` with the current
    `stopId`. Acknowledgement is not proof of a later stop. Discard all old stop,
    thread and frame IDs after execution resumes; acquire fresh IDs from events.
-6. Always finish with `detach_debugger`, including after failed investigations.
+6. On operation failure, inspect `error.diagnostic.stage`, `.reason` and `.recovery`
+   when present. These are bounded classifications and static guidance, not raw
+   worker output or proof of root cause. Capability probes may return ordered
+   `diagnostics` (JDK, then target) while retaining `success: true` and
+   `supported: false`. Terminal state retains sanitized failure diagnostics.
+   Timeout/cancellation can leave execution uncertain: reconcile state and cleanup
+   before another state-changing command; never automatically retry attach/step/resume.
+7. Always finish with `detach_debugger`, including after failed investigations.
    Inspect `cleanup.status`; retry incomplete detach rather than starting another
    session. Use `get_debugger_state` to reconcile an uncertain command outcome;
    do not automatically repeat attach, step or resume.
@@ -200,6 +217,14 @@ traversal, coroutine reconstruction or heap capture. A successful debugger comma
 establishes only its reported execution/inspection evidence, not the visible app
 outcome or the cause of a bug.
 
+For Kotlin coroutines, use explicit source breakpoints before and after suspension
+and verify each observed location. Thread-based stepping can stop in generated
+state-machine code; it does not promise to follow a coroutine across dispatchers.
+Inspect compiler line/local metadata when source bindings or values are unclear.
+Shallow locals do not expose spilled continuation fields, suspended coroutine
+inventories, parent/child identities or logical asynchronous stacks. Do not enable
+debug probes or add app instrumentation without a separately agreed design.
+
 ## Report evidence precisely
 
 State the device, actions taken, observed result, evidence source, and any

package/dist/contracts/execution-controls.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+export const verificationModes = ['none', 'light', 'full'];
+export const responseModes = ['compact', 'debug'];
+export const verificationModeSchema = z.enum(verificationModes);
+export const responseModeSchema = z.enum(responseModes);
+export const verificationModeJson = { type: 'string', enum: [...verificationModes] };
+export const responseModeJson = { type: 'string', enum: [...responseModes] };
+export function interactionControls(args) {
+    const verificationMode = (typeof args.verificationMode === 'string' ? args.verificationMode : undefined) ?? 'full';
+    const responseMode = (typeof args.responseMode === 'string' ? args.responseMode : undefined) ?? 'debug';
+    if (!verificationModes.includes(verificationMode) || !responseModes.includes(responseMode))
+        throw new Error('INVALID_ARGUMENT');
+    for (const key of ['verificationMode', 'responseMode'])
+        if (args[key] !== undefined && typeof args[key] !== 'string')
+            throw new Error('INVALID_ARGUMENT');
+    for (const key of ['actionTimeoutMs', 'verificationTimeoutMs'])
+        if (args[key] !== undefined && (typeof args[key] !== 'number' || !Number.isInteger(args[key])))
+            throw new Error('INVALID_ARGUMENT');
+    const actionTimeoutMs = (typeof args.actionTimeoutMs === 'number' && Number.isFinite(args.actionTimeoutMs) ? args.actionTimeoutMs : undefined);
+    const verificationTimeoutMs = (typeof args.verificationTimeoutMs === 'number' && Number.isFinite(args.verificationTimeoutMs) ? args.verificationTimeoutMs : undefined);
+    return { verificationMode, responseMode,
+        actionTimeoutMs: actionTimeoutMs === undefined ? undefined : Math.max(100, Math.min(30000, actionTimeoutMs)),
+        verificationTimeoutMs: verificationTimeoutMs === undefined ? 3000 : Math.max(100, Math.min(60000, verificationTimeoutMs)) };
+}

package/dist/contracts/selector.js

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+export const selectorSchema = z.object({
+    text: z.string().min(1).optional(), resource_id: z.string().min(1).optional(),
+    accessibility_id: z.string().min(1).optional(), contains: z.boolean().optional()
+}).strict().refine(value => !!(value.text || value.resource_id || value.accessibility_id), 'Selector requires a target');
+export const selectorJson = { type: 'object', additionalProperties: false, properties: {
+        text: { type: 'string', minLength: 1 }, resource_id: { type: 'string', minLength: 1 }, accessibility_id: { type: 'string', minLength: 1 }, contains: { type: 'boolean' }
+    }, anyOf: ['text', 'resource_id', 'accessibility_id'].map(key => ({ required: [key] })) };

package/dist/contracts/target.js

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import { selectorSchema as selector, selectorJson } from './selector.js';
+const pollIntervalMs = z.number().int().min(50).max(1000).optional();
+export const waitForSchema = z.object({
+    condition: z.enum(['exists', 'visible', 'clickable']).optional(),
+    timeoutMs: z.number().int().min(100).max(10000).optional(), pollIntervalMs,
+    match: z.object({ index: z.number().int().nonnegative().optional() }).strict().optional()
+}).strict();
+export const targetFields = { selector: selector.optional(), elementId: z.string().min(1).optional() };
+export const exactlyOneTarget = (value) => Number(!!value.selector) + Number(!!value.elementId) === 1;
+export const tapElementControlsSchema = z.object({
+    elementId: z.string().min(1).optional(), selector: selector.optional(), waitFor: waitForSchema.optional()
+}).strict().refine(value => Number(!!value.elementId) + Number(!!value.selector) === 1 && (!value.elementId || !value.waitFor));
+export const targetJson = { selector: selectorJson, elementId: { type: 'string', minLength: 1 } };
+export const oneTargetJson = [{ required: ['selector'], not: { required: ['elementId'] } }, { required: ['elementId'], not: { required: ['selector'] } }];

package/dist/contracts/ui.js

@@ -0,0 +1 @@
+export {};