Debug Bridge

Debug bridge

Debug builds carry an exported receiver (app/src/debug/.../debug/DebugBridgeReceiver.kt) that calls the mesh directly and answers in JSON, so an agent can drive the send→verify loop with no UI and no screenshots. This skill is the procedure. The per-action extras and reply fields are in .agents/context/debug-bridge.md, and this file points into it rather than copying it.

Gate 0: whether you may

Obey .agents/rules/devices.md. An emulator is fair game. A physical phone, including every lab phone on network adb, needs the user's go-ahead for this task, every time. Being reachable in adb devices is not permission, and neither is a yes from an earlier task. Never toggle Wi-Fi over adb on a lab phone. Always pin the target with -s <serial> or ANDROID_SERIAL: several devices are usually attached.

Gate 1: a debug build that matches

• The bridge exists only in debug builds. A release or nonMinifiedRelease install answers nothing.
• Install with ./gradlew :app:installDebug. Don't adb install the intermediates/apk file, which AGP 9 never rewrites.
• A lab phone may run a feature branch with a newer Room schema than yours, and installing over it half-runs the app. Check what the device has before you install, and say what you replaced.
• After an install the package is in the stopped state. scripts/bridge.sh delivers to it anyway (-f 0x20). A hand-written am broadcast without that flag gets an empty reply until the app is opened.

The call

scripts/bridge.sh <serial|-> <ACTION> [am-extras…]      # JSON on stdout; "-" = $ANDROID_SERIAL
scripts/bridge.sh emulator-5554 STATE | jq '{self, health, reachable}'
scripts/bridge.sh - SEND --es text 'hi there 😀' --es conv nearby

The script single-quotes every extra for the device shell, adds -f 0x20 and -p app.getknit.knit, pulls the data="…" out of Broadcast completed, and falls back to the receiver's KnitBridge:I log mirror (only lines newer than the call). It exits 1 with a hint on stderr when nothing parsable came back. A refusal is still a reply, though: a missing extra answers {"status":"error","message":"missing 'path' extra"} with exit 0, so check .status (jq -e '.status == "ok"') before reading fields. Extras use am's own flags: --es string, --ei int, --ez bool.

If you must write the raw form, quote the whole remote command and single-quote the values. adb re-parses on the device, so a bare --es text "hi there" arrives as hi:

adb -s A shell "am broadcast -f 0x20 -a app.getknit.knit.debug.SEND -p app.getknit.knit --es text 'hi there' --es conv nearby"

The core loop

1. STATE on each device: note self.nodeId and confirm the other side is in reachable[]. A peer that isn't there is a radio problem, not a delivery one. Read transports[] (per-radio health, linked, nearby) first, then meshEnabled, meshPaused and meshStartDeferred, any of which leaves a mesh that looks alive with no peers.
2. Act on A, e.g. SEND --es text '<unique body>' --es conv <nearby | peerNodeId | g-…>. Use a body you can grep for (prefix it soak or burst so PURGE can clean it up later).
3. Verify on B with STATE --es conv <id>: the body appears in messages[]. Then, if the test is about the ✓✓, read A's own row (mine: true) until its received flips: that flag is the delivery tick coming home to the sender, not something the receiver's row carries. Poll in a bounded loop. Never trust one bare sleep: delivery order and timing across radios are not promised.

for i in $(seq 1 30); do
  scripts/bridge.sh B STATE --es conv nearby | jq -e --arg b "$BODY" '.messages[] | select(.body == $b)' && break
  sleep 2
done

Which oracle answers which question

Each row's caveats (the retiring and accounted spool fields, the TTL edge on allFingerprint) are in the context doc. Read its bullet before you call a result converged or diverged.