mobile-debug-mcp 0.33.0 → 0.35.0

package/docs/specs/028-compact-debugger-responses/plan.md

@@ -0,0 +1,112 @@
+# Plan: compact debugger responses
+
+[Approved intent](intent.md) · [Accepted specification](spec.md)
+
+Intent and specification each approved with “yes” in this chat on 2026-11-02.
+No commit, push or publication requested.
+
+## Implementation
+
+- [x] Add per-call schema mode and immutable response projection at the handler.
+- [x] Test defaults, exact retention, failures and worker argument isolation.
+- [x] Extend isolated Android journey for compact MCP calls and paired byte counts.
+- [x] Align tool docs, changelog, usage skill and public schema fixture.
+
+## Verification
+
+Node >=22, JDK >=17; device fixture requires Android SDK/build-tools 36.
+
+| Acceptance | Check |
+| --- | --- |
+| 1–3 | Focused response/schema/handler unit tests and existing debugger units |
+| 4–5 | `MCP_DEBUGGER_DEVICE=emulator-5554 npm run test:device`; focused runtime fixture in both modes |
+| 1–3, 6 | `npm run verify`; public definitions and plugin consistency |
+
+Device journey uses only the existing isolated fixture. Record build fingerprint,
+Android target, known stop/local, fresh Result 43 UI assertion, stale references,
+detach and forward cleanup. Pair both projections of each captured full response;
+exercise actual compact responses separately. Preserve existing fixture finally
+cleanup. Physical Android and hosted CI remain separate evidence.
+
+Initial sandbox ADB discovery cannot bind its listener; retry with execution
+access. No dependency, release or Java worker change is needed. Review omission
+rules and error paths against the accepted specification before completion.
+
+## Results
+
+Implementation and focused review complete. Schema changes add only the optional
+mode to all eleven debugger tools; the compatibility fixture changed by exactly
+those eleven properties. Projection omits exactly three top-level fields, retains
+unknown future fields and never mutates session/worker data. Presentation input
+is removed before session dispatch. Reviewed success/catch/validation paths,
+null and unknown session handling, diagnostic retention and detach uncertainty.
+
+The focused unit check passed for all tool projections, schema defaults/invalid
+modes, success/failure, paused references, unknown fields, incomplete cleanup,
+immutability, handler errors and session argument isolation. Documentation links
+and `git diff --check` passed. Remaining maintainer/device results follow below.
+
+### Paired response measurement
+
+Node 22.23.4, emulator-5554, Android 16/API 36, MCP stdio. Server fingerprint
+(dist plus Java sources):
+`fd2f526b5ee310ba485dcb2c3d060a06fe221b24afe511fa669347586f3a3a42`.
+Default/full fixture journey **passed**. Starting state: isolated fixture freshly
+installed/launched. It established source stops, known local 42, shallow summaries,
+into/over/out stepping, stale references, fresh UI Result 43 after resume,
+missing-metadata limitations, cancellation, detach, process loss and active paused
+server shutdown. Owned forwards and fixture package/temp data were cleaned up.
+
+Measured UTF-8 bytes of `JSON.stringify` on each MCP tool-result envelope, with
+its existing pretty-printed JSON text. Each compact result projects the same
+captured full payload: IDs, timestamps and operation data are identical. This
+excludes transport JSON-RPC framing. The core table selects the first occurrence
+of each named operation from the extended fixture journey; extra pending/removal,
+stepping, failure and recovery calls are excluded from this table.
+
+| Core operation | Debug bytes | Compact bytes |
+| --- | ---: | ---: |
+| Attach | 1,141 | 1,141 |
+| Set breakpoint | 1,640 | 1,063 |
+| Stop event | 2,597 | 2,020 |
+| Stack | 7,805 | 7,228 |
+| Locals | 2,780 | 2,203 |
+| Step | 2,346 | 1,769 |
+| Resume | 2,346 | 1,769 |
+| Detach | 1,122 | 545 |
+| Total | 21,777 | 17,738 |
+
+Core reduction: **18.55%** (4,039 bytes). Across all 37 measured debugger calls:
+81,974 → 65,818 bytes, **19.71%**. Each projected routine response saved 577 bytes
+for this fixture target; discovery/state saved zero by design. These are measured
+fixture results, not a general performance target. Parsed structure preservation
+is checked independently in units. Raw per-call counts are in
+`/tmp/mobile-debug-82-device.log`; no private user-app values were used.
+
+### Final verification
+
+- `PATH=/private/tmp/mobile-debug-node22/node_modules/node/bin:$PATH npm run verify`:
+  **pass**, Node 22.23.4; lint/quality/architecture, TypeScript, all 89 unit files
+  and plugin consistency. Log: `/tmp/mobile-debug-82-verify-node22.log`.
+  Preliminary Node 23 verification also passed.
+- `MCP_DEBUGGER_DEVICE=emulator-5554 npm run test:device` with Node 22.23.4:
+  **pass**, all 10 device files. Includes Android debugger and interaction,
+  Android/iOS screenshot/log/tree and correlated evidence, plus Android traces.
+  Log: `/tmp/mobile-debug-82-device.log`. iOS observation coverage establishes
+  no iOS debugger support. Trace artifacts removed; suite left Settings foreground.
+- `MCP_DEBUGGER_DEVICE=emulator-5554 MCP_DEBUGGER_RESPONSE_MODE=compact npx tsx test/device/automated/debugger/runtime.android.test.ts`
+  with Node 22.23.4: **pass**, same server fingerprint/API as above. Actual MCP
+  calls verified omitted metadata on routine success/failure responses while
+  retaining known locals, stop/cursor/state, stale errors, stepping, resume UI,
+  process-loss and shutdown recovery. Fixture package/temp data and owned forwards
+  removed in finally; unrelated forwards preserved. Log:
+  `/tmp/mobile-debug-82-compact.log`. This run exercises compact output; its empty
+  measurement list means byte counts are taken only from the paired full run,
+  not that compact responses contain zero bytes.
+
+Local maintainer verification additionally checks plugin consistency. Hosted CI
+also compiles the Java worker with JDK 17 and checks package contents; those
+hosted jobs were not run here. Android hosted integration is manual-dispatch
+only. Physical Android debugger, real 60-second pause expiry, JDK 17 execution
+and hosted CI remain **unrun**. No publication or installed-package claim is made.
+Changes remain local, uncommitted and unpushed; issue status is unchanged.

package/docs/specs/028-compact-debugger-responses/spec.md

@@ -0,0 +1,108 @@
+# Specification: compact debugger responses
+
+[Approved intent](intent.md) · [Development process](../process.md)
+
+Date: 2026-11-02. Status: accepted.
+Source: [issue #82](https://github.com/clivejefferies/mobile-debug-tools/issues/82).
+Intent approved by the maintainer with “yes” in this chat on 2026-11-02.
+
+## Behaviour and compatibility
+
+Add optional `responseMode: 'compact' | 'debug'` to all eleven existing debugger
+tools. Omission defaults to `debug`, preserving the current response shape.
+`debug` means the existing full response; do not introduce a separate `full`
+alias. Mode selection applies to one call and never changes session state or
+future defaults. Invalid modes return the existing `INVALID_ARGUMENT` error.
+Input JSON schemas and strict runtime validation must agree.
+
+Compact mode reduces repeated session metadata, not inspected application data.
+It does not change breakpoints, suspension, stepping, locals, limits, event
+delivery, timeouts, cancellation, cleanup or error classification. It must not
+silently select compact output for existing clients.
+
+## Exact response projection
+
+Keep the current MCP text-content envelope and `isError` rules. JSON remains
+formatted using the existing serializer; savings must come from omitted repeated
+fields, not a whitespace-only change. Do not add a mode marker or rename fields.
+
+For `get_debugger_capabilities`, `attach_debugger` and `get_debugger_state`,
+compact and debug payloads are identical. These are explicit discovery and
+session-baseline operations: callers need their resolved target, capabilities
+and complete state. Clients can request state again to recover that baseline.
+
+For the remaining eight tools, compact mode omits exactly these top-level fields
+when the payload has a non-null `debug_session_id`:
+
+- `device`
+- `target`
+- `capabilities`
+
+Preserve every other field, including future fields unless separately specified.
+In particular, retain `success`, `debug_session_id`, `state`, `captured_at_ms`,
+`reason`, `stop`, `limitations`, `cleanup`, `error`, `execution_state`, `result`,
+`breakpoints`, `events`, `next_cursor`, `overflow` and `timed_out` whenever present.
+Do not prune nulls, empty collections or nested fields. Stack/frame/thread/stop
+and breakpoint identifiers, locals metadata/truncation, pending breakpoints and
+all event details therefore remain intact. Repeated stop information is retained
+to make current execution state explicit.
+
+Apply the same projection to success and failure payloads. A null-session
+failure retains the existing complete payload, because no prior session baseline
+can be assumed. A supplied but unknown session ID may be echoed as today; that
+does not establish a valid session. `DEBUGGER_NOT_FOUND` remains explicit.
+Neither mode may suppress diagnostics, error codes, retryability, limitations,
+unknown execution outcomes or remaining cleanup resources. Diagnostic content
+continues to use the bounded sanitized catalog introduced by #81.
+
+## Lifecycle, safety and platforms
+
+Projection occurs at the server response boundary after the existing operation
+and error handling. It must not mutate session summaries, worker replies or
+shared capability objects. Strip the presentation-only input before forwarding
+command arguments to the session/Java worker. No Java protocol change is needed.
+
+Device/process selection and session ownership are unchanged. A session ID
+continues to identify the originally resolved Android target; omitting repeated
+target metadata grants no ability to retarget it. Concurrency, deadlines,
+cancellation and subprocess cleanup remain governed by existing contracts.
+Detach must retain `execution_state: 'unknown'`, cleanup status and exact
+remaining resources, including failed cleanup that requires a retry.
+
+This covers the current Android debugger only. It adds no iOS support or new
+prerequisites. Inspection still returns potentially private locals on request;
+compact mode is not redaction. Do not persist real app values in benchmarks or
+public artifacts. Use the isolated debugger fixture and synthetic failures.
+
+## Acceptance and verification
+
+1. All eleven registered tools accept both modes; omission and explicit `debug`
+   preserve legacy output structure. Invalid mode values fail validation.
+2. Compact output follows the exact omission rule, preserving all other values
+   for success, paused/stale/unknown references, worker failure, timeout,
+   cancellation and incomplete cleanup. Full discovery/state remains available.
+3. Presentation does not alter command arguments, shared data, session lifecycle
+   or device ownership. Existing debugger regression coverage remains passing.
+4. Compare UTF-8 serialized MCP response bytes and parsed payload structure for
+   the same isolated attach → breakpoint → stop → stack → locals → step →
+   resume → detach journey. Project the same captured responses into both modes
+   for a paired comparison; separately exercise actual compact calls through
+   MCP. Report per-call/total bytes and percentage savings without a preset
+   target. Retain real IDs/timestamps in measurement, publishing only safe
+   aggregate results. Report unchanged discovery calls honestly.
+5. Run `npm run verify`, applicable `npm run test:device` and a focused Android
+   fixture journey against the updated build. Record server build and target;
+   separate mocked checks, emulator results and physical-device/unrun coverage.
+6. Update tool documentation, changelog and packaged usage guidance: default,
+   exact omissions, baseline recovery through state/debug mode, and privacy and
+   execution-state limitations. Check registration/runtime/plugin consistency.
+
+Affected areas: debugger schemas/handler, a small response-projection helper,
+unit and existing device fixture coverage, tool docs and packaged usage skill.
+The main risk is accidentally hiding lifecycle or diagnostic evidence; an
+explicit three-field omission rule and structural equality checks bound it.
+
+## Approval
+
+The maintainer accepted this complete specification with “yes” in this chat on
+2026-11-02. Implementation is authorized within this scope.

package/docs/specs/029-kotlin-locals-validation/report.md

@@ -0,0 +1,119 @@
+# Kotlin locals validation — issue #83
+
+[Documentation](../../README.md) · [Debugger tools](../../tools/debugger.md) ·
+[Fixture and reproduction](../../../test/fixtures/debugger-app/README.md)
+
+Date: 2026-11-02. Source: [issue #83](https://github.com/clivejefferies/mobile-debug-tools/issues/83).
+
+## Scope and method
+
+The issue originated from empty locals observed while debugging Modul8. The
+maintainer clarified in this chat: “you dont need modul8, that is just where we
+found it”. Validation therefore uses an isolated Kotlin calculation, without
+building, modifying or debugging Modul8. This is lightweight validation/test
+work under the shared process, with no new debugger contract or capability.
+
+Hypothesis: plain Kotlin arguments and initialized named locals are inspectable
+through the existing Android debugger; absence before initialization is a scope
+condition, not sufficient evidence of a worker defect.
+
+The Kotlin variant of the existing disposable Android fixture uses
+`dev.mobiledebugmcp.debugfixture.MainActivity.calculate(seed: Int)`. The same
+build helper compiles the checked-in source and installs its generated APK.
+Compiler local-variable tables are checked using `javap -p -c -l`; source/APK
+and server fingerprints are recorded by the runner. No app instrumentation,
+debug probes, coroutine support or production server change is introduced.
+
+| Source stop (`MainActivity.kt`) | Expected observation |
+| --- | --- |
+| Line 28, before `known = seed + 35` | `seed=7`; `known` absent |
+| Line 29, before `answer = known + 1` | `known=42`; `answer` absent |
+| Line 30, before setting result text | `known=42`; `answer=43` |
+
+The runner verifies actual source/method/line stops, reads stack/frame IDs and
+locals using compact MCP calls, and checks that an earlier stop/frame is stale.
+After removing breakpoints and resuming, detach must report complete cleanup
+and preserve unrelated forwards. A fresh UI-tree assertion of `Kotlin result 43`
+independently establishes execution recovery. Finally removes only the fixture
+package and temporary build directory.
+
+## Evidence and interpretation
+
+Initial focused device journey: **PASS**, emulator-5554, Android 16/API 36,
+Node 22.23.4, Kotlin JVM compiler/stdlib 2.0.21, Oracle JDK 17.0.11.
+All three scope observations, stale-reference rejection, UI recovery and owned
+forward cleanup passed. Log: `/tmp/mobile-debug-83-kotlin.log`.
+
+Server fingerprint (dist plus Java sources):
+`fd2f526b5ee310ba485dcb2c3d060a06fe221b24afe511fa669347586f3a3a42`.
+Kotlin source SHA-256:
+`79bab4babbfeb216f01fc6e53fc5400f6d0082628317e922951b11890d0eb8df`.
+The final Kotlin journey in the full device run also **passed**. Its compiler
+scope tables showed `seed` at bytecode offset 0 (length 50), `known` at offset 5
+(length 45), and `answer` at offset 9 (length 41). These are class-file offsets,
+not claimed DEX addresses. The runtime stops independently established the named
+values above. Generated APK SHA-256:
+`ea1ec8021f39ace2bbf5d7fb3aa18054eebd39395d4703dd77325d1e75d76804`.
+Signing is ephemeral, so subsequent APK hashes can differ. The final run uses the
+same source and server fingerprints. Log: `/tmp/mobile-debug-83-device.log`.
+
+The before/after comparison shows usable named Kotlin values and intentional
+scope absence on this path. No worker defect was reproduced; no runtime fix was
+made. This does not prove the cause of every earlier empty-table observation.
+The existing Java `NoLocals` fixture separately omits variable metadata and must
+retain `availability: unknown` / `EMPTY_OR_UNAVAILABLE_VARIABLE_METADATA` on ART.
+An empty table alone cannot distinguish a genuinely empty scope from unavailable
+metadata. Compiler tables plus successful later value reads supply the stronger
+evidence for this Kotlin case.
+
+The first compiler attempt used cached Kotlin 2.0.21 with JDK 25, which failed
+before device installation because that compiler could not parse the JDK version.
+Using installed JDK 17 resolved it. Another initial assertion used case-sensitive
+button text; matching native button text case-insensitively follows the existing
+fixture convention. Both were test setup issues, not debugger defects. Temporary
+output from the failed compilation was removed; the build helper now removes its
+temporary directory on any build failure.
+
+## Final checks and limits
+
+`PATH=/private/tmp/mobile-debug-node22/node_modules/node/bin:$PATH npm run verify`
+**passed** on Node 22.23.4: lint/quality/architecture, build, all 89 unit files,
+and plugin consistency. Log: `/tmp/mobile-debug-83-verify.log`.
+An isolated compiler-start failure check also passed: a missing compiler raises
+an error and leaves no new temporary fixture directory. Changed relative links,
+plugin consistency and `git diff --check` passed.
+
+The full device suite **passed**, all 11 files, using:
+
+```sh
+# With the documented compiler/stdlib/JDK variables set:
+MCP_KOTLIN_DEVICE=emulator-5554 MCP_DEBUGGER_DEVICE=emulator-5554 npm run test:device
+```
+
+Coverage: isolated Kotlin scopes and Java debugger/metadata/stepping/cleanup,
+Android interactions, Android/iOS observation smoke checks and correlated
+evidence, and Android traces. The suite removed its artifacts and left Settings
+foreground. iOS observation results do not establish iOS runtime debugging.
+Log: `/tmp/mobile-debug-83-device.log`.
+
+Final review retained the attach session ID before asserting success so failed
+attach cleanup can be retried in finally. Focused lint passed after this test-only
+adjustment. The final focused Kotlin run **passed** on the same server/source,
+compiler and emulator, with identical scope-table ranges and all observations.
+Log: `/tmp/mobile-debug-83-final-kotlin.log`; final generated APK SHA-256:
+`98b5401e1957bc1a8e61d7beec5ead63ece586d6c173db75d79af28cde7575aa`.
+Owned forwards, fixture package and temporary output were removed. No unrelated
+forward or user-app data was changed. Changes remain local, uncommitted and
+unpushed; the issue/board status has not been changed.
+
+Hosted CI additionally compiles the worker with JDK 17 and checks package
+contents; those hosted checks were not run. The Kotlin journey is explicitly
+opt-in and existing hosted workflows do not provision its compiler. This run
+uses cached local compiler dependencies through a temporary CLI wrapper and the
+matching stdlib; no compiler/cache artifacts are committed. Reproduction with a
+standard Kotlin CLI installation is documented in the fixture README.
+
+Physical-device debugging, other Kotlin/compiler versions,
+coroutines, inline/suspend functions, optimization/obfuscation and hosted CI are
+unrun. iOS runtime debugging remains unsupported. Only fixed synthetic fixture
+values are included; no private app values are used or published.