mobile-debug-mcp 0.32.4 → 0.34.0

package/docs/tools/interact.md

@@ -19,6 +19,90 @@ Important:
 - action tools report execution success, not outcome correctness.
 - `classify_action_outcome` should receive the runtime `action_type` when you want routing to distinguish local-state and side-effect actions.
 
+## Conditional actions
+
+`tap`, `tap_element`, and `swipe` (Android/iOS), plus Android `type_text` and
+`press_back`, accept an optional expected UI snapshot. Journey `tap` steps accept
+it per step. Other tools and step types reject `expectedState` rather than ignore
+it; it is not supported in journey defaults or on the journey itself.
+
+First call `get_ui_tree` on the chosen device. From a successful response, use
+`snapshot_session_id` and `snapshot_revision`:
+
+```json
+{
+  "platform": "android",
+  "deviceId": "emulator-5554",
+  "selector": { "accessibility_id": "save" },
+  "expectedState": {
+    "snapshotSessionId": "<snapshot_session_id from get_ui_tree>",
+    "snapshotRevision": 12,
+    "timeoutMs": 15000
+  },
+  "verificationMode": "none",
+  "responseMode": "compact"
+}
+```
+
+This is a `tap_element` example. Guarded standalone calls require explicit
+`platform` and concrete `deviceId` from the observed tree; `booted` and `default`
+are not valid guarded targets. Journey taps inherit the journey's resolved device.
+The expected-state object is strict: nonempty session ID, positive safe-integer
+revision, and optional integer timeout of 100–60000 ms (default 15000). Invalid or
+unsupported conditions return an `INVALID_ARGUMENT` error before device work.
+Calls without a condition preserve existing behaviour.
+
+After target and adapter preparation, the server reads a new hierarchy just
+before native input. It checks the same device, server session, and retained
+revision, even with post-action verification disabled. It never waits for a
+mismatch to become a match or retries/rebases the input automatically.
+
+| Result | Meaning |
+| --- | --- |
+| `condition.status: matched` | Condition passed; inspect the ordinary action outcome for delivery and verify its effect separately. |
+| `PRECONDITION_FAILED`, `condition.status: mismatch` | State changed; input was not dispatched. The condition includes the exact fresh tree that blocked it. |
+| `PRECONDITION_UNAVAILABLE`, `condition.status: unavailable` | Condition could not be established; input was not dispatched. Inspect `condition.reason` and observe again. |
+| `condition.status: not_checked` | Target/capability preparation failed before reaching the guard; inspect the original action failure. |
+
+Blocked input reports `success: false`, `dispatch_started: false`,
+`delivery_status: not_delivered`, `retryable: false`, `lifecycle_state: failed`,
+and `verification.status: not_requested`. No network action window is reset and
+no post-input verification runs. A failed conditional journey tap stops the
+journey; subsequent steps are `not_run` and earlier steps are not rolled back.
+
+Condition evidence has `status`, `expected: { snapshot_session_id,
+snapshot_revision }`, `observed`, `elapsed_ms`, and an optional `reason`.
+Reasons are `BASELINE_UNAVAILABLE`, `SESSION_MISMATCH`, `DEVICE_MISMATCH`,
+`OBSERVATION_FAILED`, `OBSERVATION_INVALID`, `CONDITION_TIMEOUT`, or
+`ACTION_NOT_REACHED` for a check that was not reached. `observed` is null when
+there is no valid fresh observation. Error trees cannot authorise input merely
+because they contain an old revision.
+
+Debug responses retain the full condition tree. Compact responses retain full
+fresh evidence on mismatch/unavailable results; this is an exception to their
+usual omission of device identifiers and tree contents. Successful compact
+conditions contain only observed session/revision and capture time. UI trees may
+contain private text; avoid copying them into logs unnecessarily.
+
+The baseline must still be in this process's same-device history: up to eight
+revisions, retained for ten minutes since a successful observation of that
+revision. Server restart or eviction requires a new observation. A fresh read
+cannot evict the baseline out from under its own check.
+
+The match covers the existing normalized accessibility snapshot: element text,
+identity, state, bounds, actionability, screen, and resolution. String identity
+fields are trimmed/lowercased; native state values retain their representation.
+All elements contribute, even when delta history is truncated. Pixel-only,
+backend, inaccessible, and normalization-hidden changes are not detected; the
+current tree does not establish foreground package/activity. Any observed
+intervening change invalidates the old revision, even if the UI later returns.
+
+A condition read can add seconds. Its timeout budget is separate from the action
+budget; enclosing operation deadlines still apply. This check is not atomic with
+OS input delivery. Concurrent clients, external input, or app updates can change
+the UI after the observation. Sequence device actions and verify outcomes with
+`expect_*` as usual.
+
 ## tap / swipe / type_text / press_back
 
 These tools return a shared action execution envelope.
@@ -633,7 +717,13 @@ has unknown delivery and must be observed before retrying.
 
 `tap_element` accepts exactly one `elementId` or `selector`. A selector supports
 `text`, `resource_id`, `accessibility_id`, and `contains`. Optional `waitFor` waits
-for the target before tapping; without it, resolution uses one observation.
+for the target before tapping; without it, resolution uses one observation with
+the action budget (default 5,000 ms), rather than a separate shorter cutoff.
+An explicit `waitFor.timeoutMs` remains bounded by the overall action budget.
+Selector taps resolve matching label text to its actionable ancestor using the
+existing clickable-wait policy, including `waitFor.condition: exists` or `visible`.
+Hidden/disabled labels and non-actionable containers cannot be bypassed.
+Observation timeouts report `ACTION_TIMEOUT`, rather than claiming a missing target.
 Ambiguous targets require an explicit `waitFor.match.index`.
 
 `run_journey` accepts 1–50 steps with unique IDs, on one platform/device. Supported
@@ -644,5 +734,38 @@ the journey; remaining steps report `not_run`. Journey responses default to comp
 `defaults` supplies execution controls; step verification overrides the default.
 `captureOnFailure: true` includes a screenshot-free failure snapshot in debug mode.
 
-See [RFC 018](../specs-deltas/018-interaction-latency-and-batched-journeys.md) for
+See [RFC 018](../specs/018-interaction-latency-and-batched-journeys/spec.md) for
 contracts and the device acceptance criteria.
+
+## Readiness-aware waits
+
+`wait_for_ui` and `wait_for_ui_change` accept optional `requireReady: true`.
+They require both their existing predicate and settled full-screen UI readiness
+on the same current samples. Readiness uses a 500 ms stability window, shares the
+wait's existing deadline (including retries), and adds no separate hierarchy reads.
+
+```json
+{
+  "platform": "android",
+  "deviceId": "emulator-5554",
+  "selector": { "text": "Ready" },
+  "condition": "visible",
+  "requireReady": true,
+  "timeout_ms": 30000
+}
+```
+
+Results retain the existing success/timeout envelope and include `readiness`
+evidence and limitations. Opt-in shared-deadline expiry uses a `TIMEOUT` error
+code and preserves whether the underlying predicate was observed; a readiness
+timeout does not mean that a visible target was absent. A visible target while a loader is active cannot pass
+this opt-in check. Observation failure resets readiness continuity; an exhausted
+budget is not proof of an unresponsive app. Default `requireReady: false` retains
+existing predicate semantics. There is no new journey assertion or change to
+conditional-action preconditions. See [app readiness](observe.md#app-readiness)
+for supported states and limits.
+
+## Correlated evidence
+
+Actions and journeys expose identifiers and phase timestamps for linking later
+observations. See [correlated evidence](evidence.md) for scope and limitations.

package/docs/tools/observe.md

@@ -10,6 +10,12 @@ These tools are primarily for:
 
 They are **not** the primary success signal when an applicable `expect_*` tool exists.
 
+Covered observations support optional `actionRef` and return acquisition/freshness
+metadata; see [correlated evidence](evidence.md).
+
+Android performance investigations can use [system traces](system-traces.md)
+to bracket a journey and retrieve a local Perfetto artifact.
+
 ## get_logs
 
 Fetch recent logs as structured entries optimized for AI agents.
@@ -91,6 +97,11 @@ Notes:
 - Elements may include a normalized `state` object when the platform exposes readable state such as checked, selected, focused, expanded, text input, or slider values.
 - Elements may also include platform-native identity hints such as `stable_id`, `role`, `test_tag`, `selector`, and `semantic`.
 - The tree response may include `snapshot_revision`, `captured_at_ms`, and `loading_state` when a reliable signal is available.
+- Successful tree observations include `snapshot_session_id`, a random identifier
+  for this server process. Use it with `snapshot_revision` for
+  [conditional actions](interact.md#conditional-actions) on the same device.
+  Compact tree responses preserve the session ID and revision. Never derive an
+  expectation from an error tree, even when it carries an older revision.
 - Prefer `wait_for_ui` for deterministic element resolution in interactive flows.
 - Android reads the accessibility hierarchy with `uiautomator dump` through ADB. No helper APK is installed or required.
 
@@ -210,3 +221,62 @@ read_log_stream response example:
 ```json
 { "entries": [ { "timestamp": "2026-03-20T...Z", "level": "ERROR", "tag": "AppTag", "pid": 1234, "message": "FATAL EXCEPTION" } ], "crash_summary": { "crash_detected": true } }
 ```
+
+## App readiness
+
+`get_app_readiness` observes at most two fresh hierarchies; `wait_for_app_ready`
+waits for settled evidence within one budget. Require `platform`; optionally
+select `deviceId`. Each call pins its device and keeps its sampling history local.
+
+| Control | Default | Accepted integer range |
+| --- | --- | --- |
+| `timeoutMs` | get: 15000; wait: 30000 | 100–60000 |
+| `stabilityMs` | 500 | 100–10000 |
+| `pollIntervalMs` (wait only) | 500 | 100–1000 |
+
+```json
+{ "platform": "android", "deviceId": "emulator-5554", "timeoutMs": 30000 }
+```
+
+Both return `success`, resolved `device`, `readiness`, `elapsed_ms`, and a
+`failure_code` on failure. Get succeeds when it establishes loading, transitioning,
+or settled; wait succeeds only for settled. Codes are `READINESS_UNAVAILABLE`,
+`READINESS_TIMEOUT`, and `DEVICE_UNAVAILABLE`. Invalid/unknown inputs are rejected.
+
+`readiness.state` is loading, transitioning, settled, unknown, or debugger_paused
+for an owned Android debugger stop. Visible native
+progress indicators establish loading; exact Loading / Please wait labels
+(ignoring case, whitespace and trailing dots/ellipsis) are heuristic loading.
+Loading takes priority over unchanged trees. Two different valid signatures show
+transitioning; consecutive identical signatures spanning the stability window
+show settled. Failed, empty, stale-session, wrong-device, or invalid observations
+cannot establish stability and break sample continuity. Broad legacy loading
+keywords such as a button named Progress are not sufficient loading evidence.
+
+The summary includes `basis` (observed/heuristic/insufficient), `scope: device_ui`,
+latest successful capture time and snapshot session/revision, sample
+count, `stable_for_ms`, up to eight signal-code evidence records, limitations,
+and capability flags. Evidence excludes UI text and full trees. Managed Android
+[debugger pauses](debugger.md) are reported from session evidence without acquiring
+a UI tree; readiness waits fail with `DEBUGGER_PAUSED`. External-debugger and iOS
+pause detection remain unsupported. Unresponsive detection is unsupported; neither
+slow hierarchy retrieval nor a deadline expiry proves a pause or unresponsiveness.
+
+Tree responses (including compact and nested trees) add a single-sample readiness
+summary without extra reads. It reports an owned debugger pause when known;
+otherwise a single-sample summary reports loading or unknown; it does
+not inherit stability from an earlier request. Existing loading/delta fields and
+compact error evidence are preserved.
+
+Readiness describes normalized foreground UI during the capture window. It does
+not verify foreground app identity, process health, business outcome, or backend
+completion, and does not guarantee the UI will stay unchanged. A screenshot alone
+never establishes readiness. Network observation windows and device input are
+untouched. Timeouts include `DEADLINE_EXCEEDED` and retain the last valid
+readiness evidence; an aborted acquisition does not erase that observation.
+A non-timeout observation failure still makes current state unknown. Sampling and subprocess cleanup respect outer budgets.
+Transport cancellation does not currently abort platform reads immediately;
+reads remain bounded by their operation deadlines.
+
+See [readiness-aware waits](interact.md#readiness-aware-waits) to combine this
+signal with a specific UI predicate.

package/docs/tools/system-traces.md

@@ -0,0 +1,126 @@
+# Android system traces
+
+Use system traces to collect scheduling and system annotations around a slow
+interaction. Capture is optional, device-wide and Android-only; it does not
+automatically diagnose performance problems. No root or Android CLI installation
+is required. The device must provide Perfetto (Android API 29+), authorised ADB,
+tracing services, required sched/input categories, readable process identity,
+base64 decoding and writable `/data/misc/perfetto-traces` storage.
+
+## Tools
+
+All inputs reject unknown fields. `platform` is `android` or `ios`; iOS is
+unsupported and never starts capture. Optional `deviceId` uses existing device
+resolution; supplying one is recommended when multiple devices are connected.
+
+| Tool | Arguments | Result |
+| --- | --- | --- |
+| `get_system_trace_capabilities` | `platform`, `deviceId?` | `supported`, `backend`, resolved `device`, prerequisite booleans, reasons, enabled sources, unavailable categories, limitations. No recording. |
+| `start_system_trace` | `platform`, `deviceId?`, `durationMs?` | Owned recording session after data-source acknowledgement. Duration is an integer 1,000–120,000 ms, default 30,000. |
+| `get_system_trace_status` | `traceId` | Reconcile process/deadline and finalise ended recording. |
+| `stop_system_trace` | `traceId` | Gracefully stop and retrieve local artifact; retry transfer/cleanup after failure. |
+| `cancel_system_trace` | `traceId` | Stop and discard partial files. Already retrieved artifacts remain local. |
+
+Trace control IDs are UUIDs and cannot redirect to another device. One capture
+per device and four pending sessions per server are allowed. Pending failed
+cleanup reserves its slot until resolved. Terminal records with complete cleanup
+expire after 10 minutes or eviction beyond 100 records. Server restart invalidates
+IDs. Repeated terminal operations return the stored outcome.
+
+## Agent workflow and interpretation
+
+Trace a reproducible slow or stalled interaction when existing UI timing/state
+and logs leave a performance question unresolved. Check tool discovery first:
+older installed servers may not expose these tools. Capability failure is a
+reported limitation; it is not evidence that the app is frozen.
+
+Establish the initial UI state and include an outcome assertion in the journey.
+The launch-only example below demonstrates bracketing; it does not prove an app
+outcome. Use a fresh screenshot or semantic assertion appropriate to the actual
+screen. Settings, for example, may resume a subpage rather than show its main
+title. Allow enough capture time for complete observations as well as inputs.
+
+Always finalise an owned recording, including when a journey fails. Stop to keep
+diagnostic evidence; cancel to discard it. Check both `state` and `cleanup`, and
+use status/retry for an unresolved session before starting another capture.
+Do not rely on automatic duration expiry as routine cleanup.
+
+A useful report identifies the device, journey and assertion outcomes, trace ID,
+linked correlation IDs, coverage, artifact path and cleanup outcome. `covered`
+describes the capture session lifetime, not proof that every event survived the
+ring buffer. Capture success and valid trace contents are separate from a
+performance diagnosis. These tools do not return CPU summaries, frame metrics,
+blocked-thread analysis or a root cause. Inspect the artifact with an available
+analyser before making those claims; otherwise report analysis **unrun** and
+provide the local artifact for follow-up. Host/device clocks remain unaligned.
+
+## Bracket a journey
+
+1. `get_system_trace_capabilities({"platform":"android","deviceId":"emulator-5554"})`
+2. `start_system_trace({"platform":"android","deviceId":"emulator-5554","durationMs":30000})`
+3. Use the returned `trace_id` as `systemTraceId`:
+
+```json
+{
+  "platform": "android",
+  "deviceId": "emulator-5554",
+  "systemTraceId": "<trace_id>",
+  "steps": [
+    { "id": "launch", "type": "start_app", "appId": "com.android.settings", "verificationMode": "none" }
+  ]
+}
+```
+
+4. `stop_system_trace({"traceId":"<trace_id>"})` returns `artifact.path` for local
+   inspection in Perfetto. Delete the file/directory when finished.
+
+An invalid, inactive, foreign-server or different-device reference prevents all
+journey steps. A failed journey leaves the capture available to stop or cancel;
+journeys do not control its lifetime. Without `systemTraceId`, journey behaviour
+and evidence remain unchanged. Linked journey/step evidence has
+`trace_context: {"supported":true,"trace_id":"…","markers":[]}`. The journey
+returns `system_trace` with `trace_id`, `coverage` (`covered` or `partial` if
+capture ended during execution), and `clock_alignment:"unknown"`. Trace results
+list linked `correlation_ids`. These are associations, not injected markers or
+proof of causality; host intervals are not aligned with device trace clocks.
+
+## Session response and failures
+
+JSON responses contain `trace_id`, process-scoped `session_id`, `device`,
+`backend:"perfetto"`, `state` (starting/recording/stopping/completed/cancelled/failed),
+nullable `reason` and `completion_reason`, host UTC capture bounds, nullable
+`artifact`, `cleanup`, `correlation_ids`, `enabled_sources`, and
+`unavailable_categories`. Capture bounds include command/acknowledgement latency.
+
+`artifact` contains absolute `path`, `format:"perfetto"` and `size_bytes`.
+`cleanup` contains `status` (pending/complete/failed) and `remaining_resources`.
+Errors preserve known session metadata and set MCP `isError`. Argument/unknown-ID
+errors return `{error:{tool,code,message}}` without a session. Codes include
+`INVALID_ARGUMENT`, `UNSUPPORTED_PLATFORM`, `TRACE_UNSUPPORTED`, `TRACE_BUSY`,
+`TRACE_NOT_FOUND`, `TRACE_START_FAILED`, `TRACE_STOP_FAILED`,
+`TRACE_ARTIFACT_FAILED`, `ACTION_TIMEOUT`, and `TRACE_CANCELLED`.
+Capability failures return ordinary `supported:false` responses with reasons.
+Read state/cleanup independently: a successful artifact transfer can still have
+failed device-file cleanup. Retry stop/status, or cancel to discard failed output.
+
+## Limits and privacy
+
+The fixed preset requests sched, freq, idle, am, wm, gfx, view and input categories,
+a 16 MiB ring buffer and a 32 MiB maximum output. Missing optional categories are
+reported; missing sched/input rejects start. No arbitrary config, wildcard app
+annotations, heap, screenshot or logcat sources are enabled. Device/system
+annotations may still contain sensitive information; this is not app-private data.
+
+Capture has a device-side duration limit and a server finalisation timer. Start
+acknowledgement has a 35-second budget, graceful stop 10 seconds, and transfer
+30 seconds. Only the recorded PID/start-time/output-path owner can be signalled;
+no kill-by-name cleanup. A device disconnect or uncertain stop reports failure,
+never a successful artifact. Partial transfers are discarded; bounded device
+output remains retryable. Successful transfers remove owned device files.
+
+Host artifacts use unique restricted temporary directories and remain for
+user-managed deletion. Nothing is uploaded or returned as base64. Normal server
+shutdown attempts owned cleanup for up to 10 seconds. A server crash can leave
+a uniquely named bounded device file for manual removal; restart performs no
+broad cleanup sweep. Device suspend can extend Perfetto's own monotonic duration
+limit; the server timer bounds wall-clock lifetime while the server is running.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.32.4",
+  "version": "0.34.0",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {

package/scripts/agent-plugin.mjs

@@ -1,20 +1,62 @@
 import assert from 'node:assert/strict'
-import { copyFileSync, readFileSync } from 'node:fs'
+import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import path from 'node:path'
 
 const repositoryRoot = fileURLToPath(new URL('../', import.meta.url))
-const packagedSkill = path.join(repositoryRoot, 'agent-plugin/skills/mobile-debug-mcp/SKILL.md')
-const sourceSkill = path.join(repositoryRoot, 'skills/mobile-debug-tools-usage/SKILL.md')
-const packagedLicense = path.join(repositoryRoot, 'agent-plugin/LICENSE')
+const pluginRoot = path.join(repositoryRoot, 'agent-plugin')
+const packagedSkill = path.join(pluginRoot, 'skills/mobile-debug-mcp/SKILL.md')
+const packagedLicense = path.join(pluginRoot, 'LICENSE')
 const sourceLicense = path.join(repositoryRoot, 'LICENSE')
 const packageInfo = JSON.parse(readFileSync(path.join(repositoryRoot, 'package.json'), 'utf8'))
-const plugin = JSON.parse(readFileSync(path.join(repositoryRoot, 'agent-plugin/plugin.json'), 'utf8'))
-const mcp = JSON.parse(readFileSync(path.join(repositoryRoot, 'agent-plugin/mcp.json'), 'utf8'))
+const plugin = JSON.parse(readFileSync(path.join(pluginRoot, 'plugin.json'), 'utf8'))
+const mcp = JSON.parse(readFileSync(path.join(pluginRoot, 'mcp.json'), 'utf8'))
+const { $schema: _pluginSchema, extensions, ...pluginMetadata } = plugin
+const { $schema: _mcpSchema, ...codexMcp } = mcp
+const codexManifest = {
+  ...pluginMetadata,
+  skills: './skills/',
+  mcpServers: './.mcp.json',
+  interface: extensions['com.openai'].interface,
+}
+const sharedMetadata = Object.fromEntries(
+  ['name', 'version', 'description', 'author', 'repository', 'license'].map(key => [key, plugin[key]]),
+)
+const claudeManifest = {
+  ...sharedMetadata,
+  mcpServers: {
+    [packageInfo.name]: {
+      command: 'npx',
+      args: ['--yes', `${packageInfo.name}@${packageInfo.version}`, 'server'],
+    },
+  },
+}
+const cursorManifest = {
+  ...sharedMetadata,
+  skills: './skills/',
+  mcpServers: {
+    [packageInfo.name]: {
+      type: 'stdio',
+      command: 'npx',
+      args: ['--yes', `${packageInfo.name}@${packageInfo.version}`, 'server'],
+      cwd: '${CURSOR_PLUGIN_ROOT}',
+    },
+  },
+}
+const manifests = [
+  ['.codex-plugin/plugin.json', codexManifest],
+  ['.claude-plugin/plugin.json', claudeManifest],
+  ['.cursor-plugin/plugin.json', cursorManifest],
+]
 
 if (process.argv[2] === '--sync') {
-  copyFileSync(sourceSkill, packagedSkill)
   copyFileSync(sourceLicense, packagedLicense)
+  writeFileSync(path.join(pluginRoot, '.mcp.json'), `${JSON.stringify(codexMcp, null, 2)}\n`)
+  for (const [relativePath, manifest] of manifests) {
+    const manifestPath = path.join(pluginRoot, relativePath)
+    mkdirSync(path.dirname(manifestPath), { recursive: true })
+    writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
+  }
 }
 else if (process.argv[2] !== '--check') throw new Error('Use --sync or --check')
 
@@ -30,8 +72,26 @@ assert.equal(server.type, 'stdio')
 assert.equal(server.command, 'npx')
 assert.deepEqual(server.args, ['--yes', `${packageInfo.name}@${packageInfo.version}`, 'server'])
 assert.equal(server.cwd, '${PLUGIN_DATA}', 'npx must run outside the same-named source checkout')
-assert.deepEqual(readFileSync(packagedSkill), readFileSync(sourceSkill), 'packaged usage skill must match its source')
 assert.deepEqual(readFileSync(packagedLicense), readFileSync(sourceLicense), 'packaged license must match its source')
+assert.deepEqual(JSON.parse(readFileSync(path.join(pluginRoot, '.mcp.json'), 'utf8')), codexMcp, 'Codex MCP configuration must match the portable plugin')
+for (const [relativePath, expectedManifest] of manifests) {
+  assert.deepEqual(
+    JSON.parse(readFileSync(path.join(pluginRoot, relativePath), 'utf8')),
+    expectedManifest,
+    `${relativePath} must match the portable plugin`,
+  )
+}
+for (const marketplacePath of [
+  '.agents/plugins/marketplace.json',
+  '.claude-plugin/marketplace.json',
+  '.cursor-plugin/marketplace.json',
+]) {
+  const marketplace = JSON.parse(readFileSync(path.join(repositoryRoot, marketplacePath), 'utf8'))
+  assert.equal(marketplace.name, plugin.name, `${marketplacePath} name must match the plugin`)
+  assert.equal(marketplace.plugins.length, 1, `${marketplacePath} must expose one plugin`)
+  assert.equal(marketplace.plugins[0].name, plugin.name, `${marketplacePath} plugin name must match`)
+  assert.equal(marketplace.plugins[0].source?.path ?? marketplace.plugins[0].source, './agent-plugin', `${marketplacePath} source must point to the plugin`)
+}
 const skillName = readFileSync(packagedSkill, 'utf8').match(/^---\r?\nname: ([a-z0-9-]+)\r?\n/)?.[1]
 assert.equal(skillName, path.basename(path.dirname(packagedSkill)), 'packaged skill directory must match its frontmatter name')
 

package/src/debugger/android.ts

@@ -0,0 +1,65 @@
+import { resolveAdbCmd } from '../utils/android/utils.js'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { DebuggerError, debuggerRemaining, debuggerSignal, nativeError } from './worker.js'
+const exec = promisify(execFile)
+export interface DebugTarget { app_id: string; pid: number; process_name: string; start_identity: string; uid: number }
+export interface DebugNative {
+  candidates(device: string, app: string): Promise<DebugTarget[]>
+  identity(device: string, target: DebugTarget): Promise<DebugTarget>
+  forward(device: string, pid: number): Promise<number>
+  removeForward(device: string, port: number, pid: number): Promise<void>
+}
+export class AndroidDebugNative implements DebugNative {
+  async adb(device: string, args: string[]) {
+    try { return (await exec(resolveAdbCmd(), ['-s', device, ...args], { timeout: debuggerRemaining(5000), signal: debuggerSignal(), maxBuffer: 1024 * 1024 })).stdout.trim() }
+    catch (e) { throw nativeError(e, 'DEVICE_UNAVAILABLE') }
+  }
+  async identity(device: string, target: DebugTarget): Promise<DebugTarget> {
+    try {
+      const stat = await this.adb(device, ['shell', 'cat', `/proc/${target.pid}/stat`])
+      const fields = stat.slice(stat.lastIndexOf(')') + 2).split(/\s+/)
+      const status = await this.adb(device, ['shell', 'cat', `/proc/${target.pid}/status`])
+      const uid = Number(/^Uid:\s+(\d+)/m.exec(status)?.[1])
+      const name = (await this.adb(device, ['shell', 'cat', `/proc/${target.pid}/cmdline`])).split('\0')[0]
+      if (!/^\d+$/.test(fields[19] ?? '') || uid !== target.uid || name !== target.process_name || (target.start_identity && fields[19] !== target.start_identity)) throw new Error('identity')
+      return { ...target, start_identity: fields[19] }
+    } catch (e) { if (e instanceof DebuggerError && ['DEBUGGER_TIMEOUT', 'DEBUGGER_CANCELLED', 'DEVICE_UNAVAILABLE'].includes(e.code)) throw e; throw new DebuggerError('PROCESS_CHANGED') }
+  }
+  async candidates(device: string, app: string) {
+    if (!/^[A-Za-z][\w]*(?:\.[A-Za-z][\w]*)+$/.test(app)) throw new DebuggerError('INVALID_ARGUMENT')
+    const packages = await this.adb(device, ['shell', 'cmd', 'package', 'list', 'packages', '-U', app])
+    const uid = Number(new RegExp(`^package:${app.replaceAll('.', '\\.')} uid:(\\d+)$`, 'm').exec(packages)?.[1])
+    if (!Number.isSafeInteger(uid)) throw new DebuggerError('PROCESS_NOT_FOUND')
+    // `adb jdwp` is a subscription, not a one-shot command. Bound the sample.
+    let jdwpOutput: string
+    try { jdwpOutput = (await exec(resolveAdbCmd(), ['-s', device, 'jdwp'], { timeout: debuggerRemaining(500), signal: debuggerSignal(), maxBuffer: 1024 * 1024 })).stdout }
+    catch (e: any) {
+      if (debuggerSignal()?.aborted) throw new DebuggerError('DEBUGGER_CANCELLED')
+      debuggerRemaining(1)
+      if (!e.killed || e.stderr?.trim()) throw nativeError(e, 'DEVICE_UNAVAILABLE')
+      jdwpOutput = e.stdout ?? ''
+    }
+    const jdwp = new Set(jdwpOutput.split(/\s+/).filter(id => /^\d+$/.test(id)))
+    const ps = await this.adb(device, ['shell', 'ps', '-A', '-o', 'PID,NAME'])
+    const result: DebugTarget[] = []
+    for (const line of ps.split('\n').slice(1)) {
+      const [pid, name] = line.trim().split(/\s+/)
+      if (jdwp.has(pid) && (name === app || name.startsWith(app + ':'))) result.push(await this.identity(device, { app_id: app, pid: Number(pid), process_name: name, start_identity: '', uid }))
+    }
+    return result
+  }
+  async forward(device: string, pid: number) {
+    const port = Number(await this.adb(device, ['forward', '--no-rebind', 'tcp:0', `jdwp:${pid}`]))
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) throw new DebuggerError('DEBUGGER_ATTACH_FAILED')
+    return port
+  }
+  async removeForward(device: string, port: number, pid: number) {
+    const list = await this.adb(device, ['forward', '--list'])
+    const entry = list.split('\n').find(line => line.trim().split(/\s+/)[1] === `tcp:${port}`)
+    if (!entry) return
+    const [serial, local, remote] = entry.trim().split(/\s+/)
+    if (serial !== device || local !== `tcp:${port}` || remote !== `jdwp:${pid}`) throw new DebuggerError('DEBUGGER_CLEANUP_FAILED')
+    await this.adb(device, ['forward', '--remove', `tcp:${port}`])
+  }
+}

package/src/debugger/guard.ts

@@ -0,0 +1,26 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { DebuggerError } from './worker.js'
+let pauseProvider: (device: string) => any = () => null
+export function registerDebuggerPauseProvider(provider: typeof pauseProvider) { pauseProvider = provider }
+const context = new AsyncLocalStorage<{ platform: string; device: string; dispatched: boolean }>()
+export function withDebuggerGuard<T>(platform: string, device: string, operation: () => Promise<T>) {
+  return context.run({ platform, device, dispatched: false }, operation)
+}
+// Synchronous checks and native submission share a JS turn with pause updates.
+export function checkDebuggerGuard(dispatch = false) {
+  const current = context.getStore()
+  if (!current || current.platform !== 'android') return
+  if (pauseProvider(current.device)) throw new DebuggerError('DEBUGGER_PAUSED')
+  if (dispatch) current.dispatched = true
+}
+export function guardDispatched() { return context.getStore()?.dispatched ?? false }
+export function pausedReadiness(device: string) {
+  const paused = pauseProvider(device)
+  if (!paused) return null
+  return { state: 'debugger_paused' as const, scope: 'device_ui' as const, basis: 'observed' as const,
+    captured_at_ms: paused.captured_at_ms, sample_count: 0, stable_for_ms: 0, snapshot_session_id: null, snapshot_revision: null,
+    evidence: [{ code: 'DEBUGGER_PAUSED', source: 'debugger', captured_at_ms: paused.captured_at_ms, snapshot_revision: null }],
+    limitations: ['FOREGROUND_APP_UNVERIFIED', 'DEVICE_WIDE_UI_GUARD'],
+    capabilities: { loading: true, transitioning: true, settled: true, unresponsive: false, debugger_paused: true },
+    debug_session_id: paused.debug_session_id, target: paused.target }
+}