mobridge-mcp 0.8.9 → 0.9.0

package/AI-USAGE.md

@@ -81,6 +81,8 @@ After an install/update, connect waits for the companion to become ready (a few
 - Every single mutation needs an operationId; every workflow has a workflowId and stable stepIds. When switching MCP↔CLI,
   look up mobridge operation status <operationId>, or call mobile.run with plan={"control":"status"} and the workflowId.
   The CLI equivalent: mobridge run --status --workflow-id <id>; to resume use the same plan/device/workflowId and --resume-token.
+- Reusing an operationId with the same payload returns the earlier receipt with idempotentReplay:true and executes nothing; use a new operationId for a new action.
+- screen.act results carry `app` {appId, title, generation}: the foreground app observed after the action, so you do not need an observe just to see where a tap landed.
 - Do not retry/replay a mutation after a transport drop or RESULT_UNKNOWN. requestId only identifies a call;
   operationId identifies the logical effect. The WAL keeps a tombstone for 5 minutes; an old unresolved entry becomes EXPIRED_UNKNOWN and is never turned into a new command.
 - A workflow checkpoint lives at most 24 hours and stores only an HMAC plan hash and verdict/step ids, never the plan or secrets. After a daemon restart, status returns a fresh resumeToken;
@@ -92,8 +94,6 @@ After an install/update, connect waits for the companion to become ready (a few
 - Prefer valueRef/a user-approved secret broker for secrets; the CLI can read stdin. Do not pass secrets in argv,
   do not use env as the default, and never put plaintext in a workflow checkpoint, trace or audit.
 - FLAG_SECURE only blocks capture/vision; if semantics still work, keep using the semantic path.
-- Closing an ad: BACK is only the fast path; report success only after the foreground Activity has left the ad. If the ad is still there, use assisted capture/vision;
-  never click a CTA and never tap from an old screenshot.
 
 ## Routing (the daemon picks the executor, the agent does not)
 
@@ -110,7 +110,7 @@ After an install/update, connect waits for the companion to become ready (a few
 - One known goal with visible text: one command, e.g. `mobridge screen act click --text "Login" --verify auto`.
 - Several steps: `mobridge run plan.jsonl`, or chain commands with `&&`. Long chains: `mobridge session --jsonl` (input lines {"id","argv":[...]}, output lines {"id","exit","output"}) so you do not pay a process spawn per command.
 - Unknown screen: `mobridge screen observe`. Look only when needed: `mobridge screen capture`.
-- Stuck on an ad, canvas or unlabeled icon: `mobridge screen capture`, then `mobridge screen act at --capture <captureId> --x X --y Y`; for a full-screen ad: `mobridge ad dismiss`.
+- Stuck on a canvas, unlabeled icon or ad overlay: `mobridge screen capture`, then `mobridge screen act at --capture <captureId> --x X --y Y`.
 - The CLI and MCP share one daemon (no separate WebSocket), but every CLI call still pays process start-up; do not run dozens of single commands when one JSONL plan does the job.
 - In `a && b || c`, `||` runs when a OR b fails, not only when a fails; use `if` to branch.
 
@@ -122,6 +122,7 @@ After an install/update, connect waits for the companion to become ready (a few
 - A node without CLICK (plain text or icon): `--allow-gesture` taps the node centre by coordinates. It requires a `--verify` policy that checks the screen changed, never DISPATCH_ONLY. Use it only when needed; an ambiguous parent is still refused.
 - `screen act at`: `--stale-policy strict` is the default; use `dynamic` when the screen has video, ads or animation. `--space image|screen` selects the coordinate space (default image; the capture result carries a coordinateGuide).
 - `screen capture` defaults to a small image (scale 0.5): for small text use `--mode detail` or `--roi x,y,w,h`. The file format follows the `-o` extension (.png, .jpg, .webp) or `--format png|jpeg|webp`.
+- `screen burst --duration S --interval MS` is a cheap stand-in for a video: ordered screenshots on a wall-clock schedule, held in daemon memory for 120 s (never on disk; max 60 s, 120 frames, 48 MB). The result lists frames {seq, tMs, frameId, changedFromPrev} without images; fetch one with `screen burst --frame <burstId>.<n> --stdout|-o <file>`, a range `<burstId>.<a>-<b>` (JSON, base64), or pass `--inline`. The minimum interval is 350 ms (the Android screenshot rate limit); a smaller value is raised and reported as effectiveIntervalMs. Capture slower than the interval drops slots (dropped, seq gaps, achievedIntervalMs). Burst frames are for looking: they cannot be used with `screen act at`.
 - `screen observe --app-only` drops the status bar and unfocused system chrome (on by default in MCP, off by default in the CLI). Content below the status bar, such as a heads-up notification, is kept.
 - `type --secret` or `--secret-env VAR` keeps passwords out of argv.
 - `--nth <n>` and `--within <json>` narrow down duplicate matches.
@@ -134,9 +135,8 @@ After an install/update, connect waits for the companion to become ready (a few
 {"id":"s4","type":{"field":"com.example.app:id/email","text":"a@b.c"}}
 {"id":"s5","scroll":{"query":{"text":{"value":"Settings","match":"CONTAINS"}},"direction":"FORWARD"}}
 {"id":"s6","key":"BACK"}
-{"id":"s7","ad":"dismiss"}
 
-The `ad` step is VERIFIED when the ad is closed or there was no ad. If an ad is still up the plan stops PAUSED with a NEEDS_VISION yield (with a capture and closeCandidate): look at the image, close it by hand, then resume. A `wait` condition is always wrapped in nodeExists/nodeAbsent/anyOf/allOf, never a bare {"text":"Home"}.
+A `wait` condition is always wrapped in nodeExists/nodeAbsent/anyOf/allOf, never a bare {"text":"Home"}.
 
 ## Lesser-known commands
 
@@ -161,7 +161,6 @@ The `ad` step is VERIFIED when the ad is closed or there was no ad. If an ad is
 
 ## Typed commands (generated from the registry)
 
-- ad: mobridge-ad dismiss · mobridge-ad tap-close
 - app: app clear · app force · open
 - device: devices · health --preflight · health · doctor · doctor --restart-adb · connect · state
 - diag: diag
@@ -171,7 +170,7 @@ The `ad` step is VERIFIED when the ad is closed or there was no ad. If an ad is
 - package: app install · app uninstall
 - permission: permission set · permission set --revoke · permission respond
 - run: batch · run · scenario
-- screen: screen act click | type | scroll · screen act at · analyze · screen capture · diff · find · inspect · screen observe · record · screen act scroll · wait · watch
+- screen: screen act click | type | scroll · screen act at · analyze · screen burst · screen capture · diff · find · inspect · screen observe · record · screen act scroll · wait · watch
 
 ## Examples
 

package/README.md

@@ -122,7 +122,6 @@ Two or more steps: send a JSONL plan instead of many calls. The daemon keeps the
 | Open an app and tap something | CLI `mobridge open <package>` then `act` with a query. Do not observe in between. |
 | Fill a form | One `mobile.run` plan with `type` steps and a final `tap`. |
 | Answer a permission dialog | CLI `mobridge permission respond --decision ALLOW_WHILE_USING` (answers the dialog like a user). `permission set <pkg> CAMERA` changes the state directly via ADB and reads it back. They are not interchangeable. |
-| Close an ad | CLI `mobridge ad dismiss`. It tries BACK, then assisted capture; it never taps a call-to-action. Exit 8 = pick the close point from the returned capture, then `mobridge ad tap-close`. |
 | Install / force-stop / uninstall | CLI `mobridge app install <file.apk>` (copies it into `MSM_APK_DIR` and reads the package id with aapt2/aapt, from PATH or the Android SDK build-tools), `app install <package> --apk <name>`, `app uninstall`, `app force`; `package install|uninstall` and `process stop` are aliases. Each reads the package/process state back. |
 | Wait / exit codes | `mobridge wait` that runs out of time returns status `TIMEOUT` and exit 10 (never VERIFIED/0). Exit codes: 0 VERIFIED, 1 FAILED, 2 DISPATCHED, 3 RESULT_UNKNOWN, 4 needs setup, 5 ambiguous, 6 policy, 7 transport, 8/9 `ad`, 10 TIMEOUT. Exit 2 means "sent, effect unproven", so do not chain on it with `&&` without a `--verify` policy; `mobridge open <pkg>` returns 0 when the package is already in front. `mobridge daemon restart` replaces a stale daemon (use after upgrading the package). `mobridge screen act key` takes `BACK`, `HOME`, `RECENTS` or `NOTIFICATION_SHADE`, positional or `--key`. |
 | Diagnose | CLI `mobridge diag LOGCAT|CRASH|BATTERY|NETWORK|DISPLAY|POWER`. |